Office 365 Exchange Message Tracing collector

1. Go to Microsoft Azure and log in with your account.

2. Navigate the App registration blade (you can search for it in the search toolbar).

3. Click on the + New Registration button.

4. Give the application a name. If needed change the Supported account types.

5. Click the Register button.

1. On the Overview page, search for your application in the list.

2. Under the Essentials section, copy the Application (client) ID and Directory (tenant) ID values.

3. On the left side menu, navigate to the Certificates & secrets page.

4. Click on + New client secret button.

5. Set a description and an expiration for the secret.

6. Click on the Add button.

7. Copy its Value field.

1. On the left side panel of your previously registered application, navigate to the API permissions page.

2. Click the + Add a permission button.

3. On the right side modal, navigate the APIs my organization uses tab.

4. Select Office 365 Exchange Online entry from the list - you can use the search bar tool to find it -.

5. Click the Application permissions button.

6. Under the ReportingWebService section, mark the ReportingWebService.Read.All permission.

7. Click the Add permissions button.

8. Click ✓ Grant admin consent for {your_domain} button and then on the Yes button on the appeared modal.

9. To verify that the permission was correctly added, execute the following cURL command replacing (or assigning) the $CLIENT_ID, $CLIENT_SECRET, and $TENANT_ID shell variables with the credentials you obtained in the previous instructions:

   $ curl -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&resource=https://outlook.office365.com" -X POST https://login.windows.net/$TENANTID/oauth2/token

   A JSON response will be received containing an "access_token" field. By copying its value and pasting it on the jwt.ms: Welcome! web page, the token will appear decoded. Inside, there must be a "roles" field whose value is an array containing the ReportingWebService.Read.All permission. Otherwise, the permissions have not been correctly added.

1. Navigate the Azure Active Directory blade (you can search for it in the search bar on the top).

2. On the left-side menu, navigate to the Roles and administrators page.

3. In the list, search for either the Global Reader or Security Reader role (both are valid) and click on it to select it.

4. Click the + Add assignments button.

5. On the right-side modal, use the search bar to find the application you created. Search by either its name (make sure you write the whole name, not only parts of it) or its Client ID in case you cannot find it. Once it appears on the list, select it.

6. Click the Add button.

7. To verify that the role has been correctly assigned, execute the following cURL command replacing (or assigning) the $REPORTING_TOKEN shell variable with the token you obtained in the previous instructions:

   $ curl -i -H "Authorization: Bearer $REPORTING_TOKEN" https://reports.office365.com/ecp/ReportingWebService/Reporting.svc

   This response will include the HTTP Response code and headers (note the -i parameter). You should expect to get an HTTP 200 OK response with an XML containing at least the <atom:title>MessageTrace</atom:title> tag. Other responses will be incorrect; here are some examples and their explanation:

   1. 401 - Unauthorized: Access is denied due to invalid credentials.: your token is either invalid or outdated. Review the previous instructions to obtain a working token.

   2. No permission to access the report for the organization.: The role has not been properly assigned. Review these instructions to do it.

Once the collector has been launched, it is important to check if the ingestion is performed in a proper way. To do so, go to the collector’s logs console.

This service has the following components:

Setup output

A successful run has the following output messages for the setup module:

Puller output

A successful initial run has the following output messages for the puller module:

After a successful collector’s execution (that is, no error logs found), you will see the following log message: