API - Office 365 Message Tracking (Microsoft)

Office 365 Message Tracking is a collection of metadata about email messages sent and received within an organization, containing information such as:

• Sender & Recipient
• Subject
• Size
• Status (such as pending or delivered)

In addition to auditing, these logs can help identify messages with delayed or failed delivery.

The System Monitor Agent can import Office 365 Message Tracking logs into LogRhythm for analysis. This document explains how to configure the collection of Office 365 Message Tracking logs via the LogRhythm System Monitor Agent.

Prerequisites

Before proceeding, ensure that you have the following:

• Access to the LogRhythm System Monitor Agent that will be collecting from Office 365 Message Tracking
• Admin access to O365 - Microsoft Entra Admin Center
• The correct permissions or role in O365 to use message trace search

Register an Application with Microsoft Entra

These steps might reference a version of the Entra admin portal that is different from the one you have. If your user interface does not have the menus and descriptions included here, see https://learn.microsoft.com/en-us/previous-versions/office/developer/o365-enterprise-developers/jj984325(v=office.15) for more information on registering your application.

Create an Application in the Entra Admin Portal

The same application can also be used for the API - Office 365 Management Activity (Microsoft) log source for ease of management. However, permissions must be added separately for each log source.

To open the Entra Admin Portal and create an application:

1. On the left-side menu in the Office 365 portal Admin app, click Show all, then All Admin centers, and then click Microsoft Entra.
   The Entra Admin Center appears.
2. On the left-side menu, click Applications - App Registrations.
3. In the top menu, click New Registration.
4. Complete the fields on the right side of the page:
   • Name the application.
   • Select a support account type.
   • Provide a sign-on URL (for example, https://localhost/).
5. Click Register.
   Your new application appears under the Display Name header.

Add O365 Message Tracking API Permissions

For Message Tracking collection to work, your application requires two API permissions and one role assigned. To assign these permissions:

1. On the App Registrations directory page, click the name of your application.
2. Click API permissions in the left pane.
3. Click Add a permission.
4. In the Request API permissions pane, on the APIs my organization uses tab, select Office 365 Exchange Online API.
5. Click Delegated permissions.
6. Under Delegated Permissions, expand the header ReportingWebService and check the following boxes:
   • ReportingWebService.Read
7. Click Application permissions.
8. Under Application Permissions, expand the header ReportingWebService and check the following box:
   • ReportingWebService.Read.All
9. Click Add permissions.
   Verify that your changes have been saved on the API permissions page.
10. Select Grant admin consent for <Organization Name> to apply the Application Permissions previously selected.
11. Select Yes to continue.
    A successful confirmation appears.

Obtain the Client and Tenant IDs and Generate the Client Secret

To obtain the client and tenant IDs and client secret, from the App Registrations screen:

1. Select the application created above.
2. In the left-hand panel, click Overview.
3. Under the Essentials header, copy the following strings into a text file for later use:
   1. Application (client) ID (the Client ID used in the .ini configuration file).
   2. Directory (tenant) ID (the Tenant ID used in the .ini configuration file).
4. In the left-hand panel, click Certificates and Secrets, and then Client Secrets.
5. Click New client secret.
   The Add a client secret window appears.
6. Enter a Description for this client secret.
7. Select the desired expiry period from the Expires drop-list.
8. Click Add.

9. Copy the Value fields into a text file for later use in the .ini configuration file.

   

   Once this page is closed, the client secret cannot be re-obtained. Please ensure the value has been stored in a text file before closing this window.

Assign Microsoft Entra Roles to the Application

The supported role for applications to access the Reporting Web Service is Global Reader.

To assign this role to the newly registered app:

1. On the left-side menu in the Office 365 portal Admin app, click Show all, then All Admin centers, and then click Microsoft Entra.
   The Entra Admin Center appears.
2. In the left-hand panel, click Roles & Admins.
3. In the search bar, type Global Reader and click on the role that appears.
4. Click Add assignments.
5. Click No member selected to assign the role to the app.
   The Select a member window appears.
6. In the search bar, type the application's name, and then click the checkbox next to your application.
7. Click Add.

Update the O365MessageTracking.ini File

The O365MessageTracking.ini file must be located on the host of the Agent collecting logs. It is used to create a secure connection between the LogRhythm System Monitor and Office 365 Message Tracking. A sample file is installed in the LogRhythm System Monitor's config directory, typically C:\Program Files\LogRhythm\LogRhythm System Monitor\config. Modify this file or copy it to configure the Agent that will be collecting logs.

Upgrading to System Monitor version 7.10.0.8000 requires new fields to be added to previously configured Office 365 Message Tracking .ini files.

The following needs to be copied and pasted into existing .ini files, updating the Tenant ID, Client ID, and Client Secret as described below. These fields are the OAuth2.0 replacement for the Basic Auth username and password fields.

CODE

# O365 Message Tracking Endpoint Hostname
# API details are available: https://msdn.microsoft.com/en-us/library/office/jj984335.aspx
Endpoint=reports.office365.com

# Tenant ID
TenantID =CHANGE_THIS

# Client ID
# Must be encrypted using the lrcrypt command line utility.
ClientID =CHANGE_THIS

# Client Secret
# Must be encrypted using the lrcrypt command line utility.
ClientSecret=CHANGE_THIS

To edit the O365MessageTracking.ini file:

1. Open Windows Explorer on the host of the Agent collecting logs, and then go to the following directory: C:\Program Files\LogRhythm\LogRhythm System Monitor\config.

2. Open the O365MessageTracking.ini file with a text editor and edit the following values:

   Setting	Default Value (Range)	Description
   Endpoint	reports.office365.com	The hostname of the Office 365 Message Tracking endpoint. API details are available at https://msdn.microsoft.com/en-us/library/office/jj984335.aspx.
   TenantID	CHANGE_THIS	Obtain the TenantID from the Entra Admin Center. This can be found in your App Registration > Application Name > Overview screen (Listed as Directory (tenant) ID).
   ClientID	CHANGE_THIS	Obtain the ClientID from the Entra Admin Center. This can be found in your App Registration > Application Name > Overview screen (Listed as the Application (client) ID). This must be encrypted using the lrcrypt command line utility. For more information, see LogRhythm Password Encryption.
   Client Secret	CHANGE_THIS	Obtain the ClientSecret from the Entra Admin Center. This can be found in your App Registration > Certificates & secrets > value of created secret. The client secret value can only be obtained when it is first created. If you did not copy the value at the time, simply generate a new client secret. This must be encrypted using the lrcrypt command line utility. For more information, see LogRhythm Password Encryption.
   Delay	60 minutes (0 to 1440)	The amount of time, in minutes, that the Agent should delay the collection request, to ensure that logs are available. Especially in global organizations, there is often latency between when an email is sent and when it is available in the API for collection. For example, if the delay is 60 minutes and the API is called at 1:00pm, logs from 11:00pm to 12:00pm are requested. Setting this value below 60 (minutes) may result in higher-latency logs not being collected.
   Window	60 minutes (1 to 1440)	The collection window, in minutes. If set to 60, then 60 minutes worth of messages will be collected. Use this setting to limit the amount of data requested at one time, which can be important for environments with a large number of messages, especially for the initial collection. This value works in conjunction with Frequency (below), and this value must be greater than Frequency. EXAMPLE If an organization sends approximately one million emails per hour, an initial collection of 24 hours would be 24 million records. If you set Frequency to 60 seconds and Window to 5 minutes, the Agent requests five minutes worth of emails (80,000 messages) every minute. At this rate, it would take 300 requests to catch up, but it would throttle the number of messages forwarded by the Agent to LogRhythm, which is recommended.
   Frequency	300 seconds (10 to [<Window>*60] - 1)	The collection frequency, in seconds, indicating how often messages are requested. For information about using this value in conjunction with Window, see the example in the Window setting.
   GroupByMessageId	false	This flag can be used to group logs by message ID, or sender. If true, the Agent sends one log per sender. If false (default), the API sends one log per recipient. This is how the API provides logs. EXAMPLE User1 sends a message to user2 and user3. If GroupByMessageId=true, the result is a single log:  MESSAGEID=1, SENDER=user1@example.com, RECIPIENT=user2@example.com;user3@example.com If GroupByMessageId=false, the result is two logs: MESSAGEID=1, SENDER=user1@example.com, RECIPIENT=user2@example.com MESSAGEID=1, SENDER=user1@example.com, RECIPIENT=user3@example.com
   Timeout	300 seconds (0 - 300)	The timeout, in seconds, to use when requesting data from the API. Setting this value to 0 indicates an infinite timeout (no timeout).
   ErrorRetryTimeSpan	60 minutes	The amount of time, in minutes, after which the Agent tries to collect again following an error.
   ErrorRetryCount	3	The number of times the Agent should retry collection for reports that produce an error when read.
   LogApiRequests	false	Enables (true) or disables (false) logging of requests made to the API. This option should not be enabled without assistance from LogRhythm Professional Services or Customer Support.
   Proxy Settings
   ProxyServer	The IP address or DNS name of a proxy server to use for connecting to the specified endpoint.
   ProxyPort	The port to use on the proxy server.
   UserName	The user name to send if authentication is required on the proxy server. If the user name is an email account, be sure to include the full address.
   Password	The password for the specified user name.
   Domain	The domain to use for connecting to the proxy server.

3. Save and close the file.

After you configure the device, you must also configure LogRhythm according to the instructions provided on the overview page of this guide. LogRhythm requires a LogRhythm System Monitor Agent be used to collect the logs.

Only Global Admins or Restricted Admins with elevated View and Manage privileges can take this action.

The name of the log message source is API - Office 365 Message Tracking. In addition, when configuring this log source:

• For Log Message Processing Engine (MPE) Policy, select LogRhythm Default.
• On the Flat File Settings tab, enter the full file path to the Office 365 Message Tracking configuration file, including the file name and extension (typically C:\Program Files\LogRhythm\LogRhythm System Monitor\config\O365MessageTracking.ini).