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
  • A valid username and password for connecting to the Office 365 reports API
  • The correct permissions or role in O365 to use message trace search
  • Basic authentication must be enabled for Reporting Web Services using parameter AllowBasicAuthReportingWebServices

Register an Application with Azure AD

These steps might reference a version of the Azure AD 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 Azure Portal

To open the Azure Portal and create an application:

  1. On the left-side menu in the Office 365 portal Admin app, click Admin centers, and then click Azure AD.
    The Azure AD Dashboard appears.
  2. On the left-side menu, click Azure Active Directory.
  3. (Optional.) If you have more than one directory, select the correct directory name.
  4. On the directory page, click App Registrations in the menu on the left.
  5. In the top menu, click New Registrations.
  6. 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/).
  7. Click Register.
    Your new application appears under the Display Name header.

Add O365 Message Tracking API Permissions

  1. On the directory page, click the name of your application.
  2. Click API permissions.
  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 ReportingWebService.Read and ReportingWebService.Read.All boxes.
  7. Click Application permissions.
  8. Under Application Permissions, expand the header Other permissions and check the full_access_as_app box.
  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.

Assign Azure AD Roles to the Application

The supported roles for applications to access the Reporting Web Service are:

  • Global Reader
  • Security Reader

To assign these roles to the newly registered app:

  1. On the left-side menu in the Office 365 portal Admin app, click Admin centers, and then click Azure AD.
    The Azure AD Dashboard appears.
  2. On the left-side menu, click Azure Active Directory.
  3. On the directory page, click Roles and administrators from the menu on the left.
  4. In the search bar, type Global Reader and click on the role that appears.
  5. Click Add assignments.
  6. Click No member selected to assign the role to the app.
    The Select a member window appears.
  7. In the search bar, type the application's name, and then click Select.
  8. Click Next.
  9. Enter a justification (a reason for assigning the role), and then click Assign.
  10. Repeat steps 4 through 9 for the other role, Security Reader.

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.

# 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
CODE

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:

    SettingDefault Value (Range)Description
    Endpointreports.office365.comThe hostname of the Office 365 Message Tracking endpoint. API details are available at https://msdn.microsoft.com/en-us/library/office/jj984335.aspx.
    TenantIDCHANGE_THISObtain the TenantID from the Azure AD portal. This can be found in your App Registration > Overview screen (alternatively known as the Directory ID).
    ClientIDCHANGE_THIS

    Obtain the ClientID from the Azure AD portal. This can be found in your App Registration > Overview screen (alternatively known as the Application ID).

    This must be encrypted using the lrcrypt command line utility. For more information, see LogRhythm Password Encryption.

    Client SecretCHANGE_THIS

    Obtain the ClientSecret from the Azure AD portal. This can be found in your App Registration > Certificates & secrets > value of created secret.

    This must be encrypted using the lrcrypt command line utility. For more information, see LogRhythm Password Encryption.

    Delay60 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.
    Window60 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.

    Frequency300 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.

    GroupByMessageIdfalse

    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
    Timeout300 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).
    ErrorRetryTimeSpan60 minutesThe amount of time, in minutes, after which the Agent tries to collect again following an error.
    ErrorRetryCount3The number of times the Agent should retry collection for reports that produce an error when read.
    LogApiRequestsfalseEnables (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
    ProxyServerThe IP address or DNS name of a proxy server to use for connecting to the specified endpoint.
    ProxyPortThe port to use on the proxy server.
    UserNameThe 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.
    PasswordThe password for the specified user name.
    DomainThe 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).