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 

Grant the required permissions for the Office 365 Exchange Online API.

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.

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: Assign Security Reader Role 

Assign the Security Reader role to allow the application to read message trace logs.

NOTE: This step is optional. The Microsoft Graph message trace API requires only the ExchangeMessageTrace.Read.All permission (Step 3) and the service principal (Step 4). Assign Security Reader only if your organization's policy requires it.

1. In Microsoft Entra ID, click Roles and administrators in the left sidebar.
2. Search for Security Reader and select it.
3. Click Add assignments.
4. Search for the application you created in Step 1, select it, and click Save. NOTE: You may need an Azure administrator to perform this step if you do not have sufficient privileges.

Step 6: 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. An empty or incorrect scope will prevent the access token from being issued.