Office 365 Message Trace Integration via API

Prerequisites

Before you start, ensure you have:

• Azure Administrator privileges (or access to an admin who can grant required permissions).
• Access to the Azure portal (https://portal.azure.com).

Step 1: Create an App Registration in Microsoft Entra ID

1. Log into the Azure portal: https://portal.azure.com
2. In the left sidebar, navigate to Microsoft Entra ID.
3. Click on App registrations.
4. Click New registration.
5. Enter a Name for your application (e.g., Logsign_Office365_SP).
6. Choose Supported account types → Select Accounts in this organizational directory only (Single tenant).
7. Leave Redirect URI blank (not required for this integration).
8. Click Register. NOTE: After registering, note down the Application (client) ID and Directory (tenant) ID from the Overview page. You will need these later.

Step 2: Generate Client Credentials

1. In your App Registration, click Certificates & secrets in the left sidebar.
2. Click New client secret.
3. Enter a descriptive name (e.g., Logsign_Office365_Secret).
4. Set an expiration period (e.g., 1 year, 2 years, etc.).
5. Click Add.
6. Copy the generated Value and store it securely. NOTE: You will not be able to view the secret value again once you leave the page.

Step 3: Configure API Permissions

This integration reads message trace data through Microsoft Graph, so the permission has to be granted on the Microsoft Graph API. Permissions granted on the older Office 365 Exchange Online API, such as ReportingWebService.Read.All, do not work here and will cause the access token to be rejected.

1. In your App Registration, click API permissions in the left sidebar.
2. Remove any existing permissions by clicking ... → Remove permission.
3. Click Add a permission.
4. Select the Microsoft Graph.
5. Select Application permissions.
6. Find and check ExchangeMessageTrace.Read.All.
7. Click Add permissions.
8. Click Grant admin consent and confirm. NOTE: After granting admin consent, a green checkmark should appear next to the permission.

NOTE: ExchangeMessageTrace.Read.All is the only permission this integration needs. You do not have to assign the Security Reader directory role to the application. Assign it only if your own organization's policy requires it, it has no effect on whether message trace collection works.

Step 4: Create Transport Data Platform Service Principal

The Microsoft Graph API message trace endpoint requires the Transport Data Platform service principal to exist in each tenant. This is a Microsoft first party application with the following fixed App ID (the same for every tenant):

8bd644d1-64a1-4d4b-ae52-2e0cbf64e373

NOTE: Do not create this service principal via Enterprise applications → New application → Create your own application. That screen always generates a new, random App ID and cannot reproduce the required App ID above. Use the Microsoft Graph Explorer method below instead. You must be signed in as a tenant administrator.

Create the service principal via Microsoft Graph Explorer

1. Go to Microsoft Graph Explorer: https://aka.ms/ge
2. Sign in with an account that has administrator permissions in your tenant.
3. If prompted, consent to the Application.ReadWrite.All permission.
4. Set the request method to POST and the URL to:
   https://graph.microsoft.com/v1.0/servicePrincipals
5. In the Request body, enter:
   {
   "appId": "8bd644d1-64a1-4d4b-ae52-2e0cbf64e373"
   }
6. Click Run query. A 201 Created response confirms the service principal was created.

Verify

1. In Microsoft Entra ID → Enterprise applications, set the filter to All applications.
2. Search for the App ID 8bd644d1-64a1-4d4b-ae52-2e0cbf64e373.
3. Confirm an entry (named Transport Data Platform) appears with exactly that App ID.

NOTE: If you previously created a Transport Data Platform app whose App ID is different from the one above, that entry is wrong. Delete it and re-create the service principal using the Graph Explorer method above.

NOTE: After creating this service principal, provisioning may take several hours to complete. During this period the API may return an authentication error such as "the service principal for App ID 8bd644d1-64a1-4d4b-ae52-2e0cbf64e373 was not found". This is expected, retry after a few hours. If it persists longer than a day, the service principal was created with the wrong App ID (see the note above).

Step 5: Collect Required Information

You will need the following values when adding this source in Logsign USO:

• Client ID → App Registration > Overview > Application (client) ID
• Tenant ID → App Registration > Overview > Directory (tenant) ID
• Client Secret → The Value generated in Step 2
• OAuth Scope → https://graph.microsoft.com/.default

NOTE: The OAuth Scope field is mandatory and must be entered exactly as https://graph.microsoft.com/.default. This is the only scope this integration accepts, because the poller reads message traces from Microsoft Graph. A scope pointing at a different Microsoft service, for example https://outlook.office365.com/.default, produces a token that Graph rejects with the error "InvalidAuthenticationToken: Access token validation failure. Invalid audience." An empty scope prevents the token from being issued at all.

Step 6: Add the Source in Logsign USO

1. Log in to the Logsign USO interface.
2. Click Settings > Data Collection > +Device.
3. Select API, then choose Office 365 from the list.
4. Fill in Client Secret, Client ID, Scope and Tenant ID with the values collected in Step 5.
5. Set the remaining device settings (Device Name, Data Policy, Check Health, Tags, Roles) as needed, then save.

NOTE: The source list also contains an entry called Office 365 Management. That is a different integration, it collects audit activity through the Office 365 Management Activity API and uses different permissions. For message trace data, select Office 365.

Verify SSL (optional): the Add Device form also has a Verify SSL checkbox, checked by default. If your network routes outbound traffic through a TLS-inspecting proxy that presents its own certificate for graph.microsoft.com, uncheck this to disable certificate verification for this source. Leave it checked unless you have this specific proxy setup, since disabling it removes protection against a man-in-the-middle on the connection to Microsoft Graph.

Step 7: Restart the Poller After Changing Credentials

The poller keeps the access token it obtained from Microsoft in a short-lived cache. If you edit the Scope, Client ID, Client Secret or Tenant ID of an existing source, the cached token stays in use until it expires, which can take up to an hour, so the source appears to keep failing even though the settings are now correct.

After changing any of these four values, restart the API poller service on the Logsign server so the new settings take effect immediately:

systemctl restart logsign-poller-api

If you do not have shell access to the Logsign server, contact Logsign support and we will restart the service for you.

Troubleshooting

If the source does not produce logs, check the poller log on the Logsign server for the Office365_API entries. The errors seen most often are the following.

InvalidAuthenticationToken, Invalid audience. The OAuth Scope is not https://graph.microsoft.com/.default, or it was corrected but the poller has not been restarted. Review Step 5 and Step 7.

Service principal-less authentication failed, the service principal for App ID 8bd644d1-64a1-4d4b-ae52-2e0cbf64e373 was not found. The Transport Data Platform service principal is missing, or it was created recently and Microsoft has not finished provisioning it. Review Step 4.

Your recent queries have surpassed the permitted limit, please try again later. Microsoft throttles this API at 100 requests per five minutes per tenant. The poller stays well inside that limit on its own, so this normally appears only when other tools in your organization query the same API at the same time. Collection resumes by itself once the window resets.

Microsoft serves message trace data for the last 90 days only, and a newly added source starts by collecting the last few hours rather than the full history.