Office 365 Message Trace REST API protocol configuration options

The Office 365 Message Trace REST API protocol for IBM® Security QRadar® collects message trace logs from the Message Trace REST API. This active outbound protocol is used to collect Office 365 email logs.

Important: As of 1 January 2023, Microsoft will no longer support basic authentication. To continue receiving Message Trace events, you must use modern authentication. Modern authentication uses OAuth 2.0 to authenticate and authorize access to the events. For more information about the deprecation of basic authentication, see Basic Authentication Deprecation in Exchange Online – September 2022 Update.

To use modern authentication, you must register a new application in the Microsoft Azure portal (https://portal.azure.com/). In the portal, you can obtain important values that you must use when you create a Microsoft Office 365 Message Trace log source.

  1. Create an application that can be used to authenticate with the Office 365 Message Trace REST API. For more information, see Use the portal to create an Azure AD application and service principal that can access resources.
    1. Assign Azure AD roles to the application. For more information, see Assign Azure AD roles to the application.
    2. Set the ReportingWebService.Read.All application permission. For more information, see Specify the permissions your app requires to access the Reporting Web Service.
  2. Obtain the Client ID, Tenant ID, and Client Secret values.
    1. On the Overview page of the application, locate and copy the Client ID and Tenant ID values. You use these values when you create a Microsoft Office 365 Message Trace log source. For more information, see Get tenant and app ID values for signing in.
    2. On the Certificates and Secrets page of the application, click New Secret to create the client secret, and then copy the client secret to a text editor. You use this value for the Client Secret parameter when you create a Microsoft Office 365 Message Trace log source. For more information, see Create a new application secret.
The following parameters require specific values to collect events from the Office 365 Message Trace REST API:
Important: If the start date and end date in an audit log run are overlapping, then there is duplication of events in the reports with different indexes. In such cases, you must manually handle the events in the reports.
Table 1. Office 365 Message Trace REST API protocol log source parameters
Parameter Value
Log Source Identifier

A unique name for the log source.

The name can't include spaces and must be unique among all log sources of this type that are configured with the Office 365 Message Trace REST API protocol.
Authentication Method Modern authentication uses OAuth 2.0 to authenticate and authorize access to the resource. Basic authentication uses the username and password.

If you select the Basic authentication method, the Office 365 User Account email and Office 365 User Account Password parameters appear. Provide an Office 365 email account with proper permissions.

Important: As of 1 January 2023, Microsoft will no longer support basic authentication. To continue receiving Message Trace events, you must use Modern authentication.
Client ID The Client ID value from your application configuration of Microsoft Azure Active Directory. For more information, see Get tenant and app ID values for signing in.
Client Secret The client secret that you created for your application on the Microsoft Azure portal. For more information, see Create a new application secret.
Tenant ID The Tenant ID value that is used for Microsoft Azure Active Directory authentication. For more information, see Get tenant and app ID values for signing in.
Event Delay

The delay, in seconds, for collecting data.

Office 365 Message Trace logs work on an eventual delivery system. To ensure that no data is missed, logs are collected on a delay. The default delay is 900 seconds (15 minutes), and can be set as low as 0 seconds.
Use Proxy If the API is accessed by using a proxy, select this checkbox.

Configure the Proxy Server, Proxy Port, Proxy Username, and Proxy Password fields. If the proxy does not require authentication, you can leave the Proxy Username and Proxy Password fields blank.
Enable Advanced Options Select this option to modify the default values for the Microsoft API Login Endpoint and Office 365 Message Trace API Management URL parameters. If you do not enable this parameter, the default values are used.
Microsoft API Login Endpoint Specify the Microsoft API login endpoint. The default value is https://login.windows.net.

If you do not enable the Enable Advanced Options parameter, the default value is used.
Office 365 Message Trace API Management URL The Office 365 Message Trace API management URL grants your token access to the specified resource. The default value is https://outlook.office365.com.

If you do not enable the Enable Advanced Options parameter, the default value is used.
Recurrence

The time interval between log source queries to the Office 365 Message Trace REST API for new events.

The time interval can be in hours (H), minutes (M), or days (D). The default is 5 minutes.
EPS Throttle

The maximum number of events per second that QRadar ingests.

If your data source exceeds the EPS throttle, data collection is delayed. Data is still collected and then it is ingested when the data source stops exceeding the EPS throttle.

The default is 5000.

Conditional access for reading reports

If you receive the error message "Status Code: 401 | Status Reason: Unauthorized," review the following Conditional Access policies documentation to confirm that the user account has access to the legacy application Office 365 Message Trace API: