Setting up TensorGuard with Microsoft 365

To connect TensorGuard to Microsoft 365, you need to set up an App Registration in Microsoft Entra ID (formerly Azure Active Directory). This acts as a dedicated, headless service account for the code, allowing it to authenticate securely using the OAuth2 Client Credentials flow.

This tool features three distinct collection modules.

1. The Mailbox Collector (.eml files)
2. The Unified Audit Log (UAL) Collector
3. The Message Trace Collector

You can configure your tenant for one, two, or all three, depending on your needs.

---

Part 1: Core Application Setup (Required for all modules)

Regardless of which collectors you plan to use, you must first create the identity for the tool.

Phase 1: Register the Application

1. Log in to the Microsoft Entra admin center using an account with Application Administrator or Global Administrator privileges.
2. Navigate to Entra ID —> App registrations in the left menu panel.
3. Click + New registration at the top.
   • Name: TensorGuard M365 Collector
   • Supported account types: Select Single tenant only - [YOUR TENANT NAME] (Single tenant).
   • Redirect URI: Leave blank.
4. Click Register.

Capture your IDs: From the app’s Overview page, copy and save these to your notes:

• Application (client) ID —> CLIENT_ID
• Directory (tenant) ID —> TENANT_ID

Phase 2: Generate the Client Secret

1. On your application’s left menu, navigate to Certificates & secrets.
2. Under the Client secrets tab, click + New client secret.
3. Add a description (e.g., Prod-Collector-Key) and set an expiration based on your company’s policy.
4. Click Add.

Capture your Secret:

• CRITICAL: Immediately copy the string in the Value column —> and store to CLIENT_SECRET in your notes.

Warning

Be sure to copy the “Secret Value”, not the “Secret ID”. Once you navigate away, the secret value is hidden forever.

---

Part 2: Module-Specific Permissions & Configuration

Now that your app exists, you must grant it the specific permissions for the modules you wish to use.

Navigate to your app’s API permissions menu, on the left hand side, click + Add a permission —> Microsoft Graph —> Application permissions.

Select the permissions below based on your needs.

Module A: Forensic Mailbox Collector (.eml files)

Pulls raw, full-fidelity emails directly from user inboxes.

• Required Entra ID Permission: Mail.Read
• Setup: None. This module is active the moment you grant the permission.

Module B: Unified Audit Log (UAL) Collector

Pulls historical administrative, file, and login events.

• Required Entra ID Permission: AuditLogsQuery.Read.All

Note

Do not select the legacy AuditLog.Read.All. Microsoft’s new asynchronous beta endpoints strictly require the AuditLogsQuery permission).

Accept the permission consent prompt, to apply the permission.

Next, choose between the two options below to actually enable the Microsoft UAL (this is disabled by default on lower subscription tiers, but is free to enable).

Enabling the UAL via the Web Interface:

Before attempting to enable the UAL, you should verify that Microsoft’s internal Purview service principal is instantiated in your tenant. If it is missing, Purview will throw an error when you try to turn auditing on, or accessing it.

1. Navigate to the Microsoft Purview Portal and sign in.
2. On the left navigation pane, select Solutions -> Audit.
3. If auditing is not yet turned on for your tenant, you will see a banner at the top of the page. Click Start recording user and admin activity. (Note: If you do not see this banner, auditing is already enabled).
4. If you just enabled auditing, you will see a notification that “Sorry, we’re having trouble figuring out if activity is being recorded. Try refreshing the page.” You should stay at this step and refresh the page periodically, until this error message goes away.

Enabling the UAL via PowerShell

This is not necessary if you enabled the UAL via the web interface, but can be used as an alternative method.

The UAL must actually be turned on in your tenant to record data.

1. Open a PowerShell terminal and connect to Exchange Online:

   Connect-ExchangeOnline

2. Enable the UAL:

   Set-AdminAuditLogConfig -UnifiedAuditLogIngestionEnabled $true

Module C: Exchange Message Trace Collector

Pulls global mail routing and delivery logs.

• Required Entra ID Permission: ExchangeMessageTrace.Read.All

Note

Microsoft actively blocks this API until a specific, hidden first-party Microsoft application is manually instantiated in your tenant. (See Microsoft’s official documentation).

To instantiate this without PowerShell:

1. Go to Microsoft Graph Explorer and sign in.
2. Below the URL bar, click the Modify permissions tab, search for Application.ReadWrite.All, and click Consent.
3. Change the method to POST.
4. Set the URL to: https://graph.microsoft.com/v1.0/servicePrincipals
5. In the Request body, paste the exact Microsoft Transport App ID:

   {
     "appId": "8bd644d1-64a1-4d4b-ae52-2e0cbf64e373"
   }

6. Click Run query. A 201 Created or 200 OK confirms success.

---

Part 3: Finalizing Setup & Managing Expectations

Once you have added all your desired permissions from Part 2, you must formally apply them.

1. Back on the API permissions screen, click ✅ Grant admin consent for [Your Tenant].
2. Ensure the “Status” column shows a green checkmark for all selected permissions.

Cloud Propagation Delays

Microsoft’s global infrastructure does not sync instantly. Depending on which modules you configured, do not expect data ingest to work the exact second you finish this guide. If the script throws 401 Unauthorized or 400 Bad Request errors after following these steps, you are simply waiting on Microsoft.

• Forensic Mailbox Module: Instant.
• UAL Module: If you just enabled the UAL, it can take over 60 minutes for the API to accept jobs, and up to 24 to 48 hours before events globally populate into the search indexes.
• Message Trace Module: Instantiating the hidden Transport App can face extreme backend delays in our testing. In some tenant regions, it can take anywhere from 2 to 50 hours for the Service Principal to replicate across Exchange Online’s global databases.

Patience is key. Once the cloud finishes replicating your changes, your TensorGuard extractor will successfully authenticate and stream logs directly to your interface.

---

TensorGuard™ is a trademark of TensorGuard Inc. All other trademarks are the property of their respective owners.