Microsoft 365 is a widely adopted productivity suite from Microsoft. The suite includes Microsoft Exchange Online collaboration service for email, calendars, contacts, and tasks. Message tracing is one of the basic tools used by administrators to monitor email flow.
Some email information is stored in logs and is available for administrative purposes. The administrator will be able to see sent and received emails even though the user has deleted or purged them. With message tracing, you can’t see the content of the messages but you can get very useful information such as:
Sender and recipient.
Send and received dated.
Subject and size of the email.
Status and details of events. There are seven possible values in the delivery status field: delivered, failed, pending, expanded, quarantined, filtered as spam, and unknown.
IP address used to send the message.
Message ID: This is a unique number that identifies the message. If a message is sent to more than one recipient it will display once for every recipient, but all will have the same Message ID.
Message tracking logs
You won’t be able to edit the messages in Office 365 since they are not simple text files. To do that you can use message tracking logs in on-prem Exchange that allow you to edit them directly since they are simple text files.
Configuration requirements
To run this collector, there are some configurations detailed below that you need to consider.
Configuration
Details
Configuration
Details
Microsot Azure account
It is a requirement to have an account so you can run this collector.
Microsoft 365 account
It is a requirement to have an account so you can run this collector.
More information
Refer to the Vendor setup section to know more about these configurations.
Devo collector features
Feature
Details
Feature
Details
Allow parallel downloading (multipod)
Not allowed
Running environments
Collector server
On-premise
Populated Devo events
Table
Flattening preprocessing
No
Data sources
Data source
Description
API endpoint
Collector service name
Devo table
Available from release
Data source
Description
API endpoint
Collector service name
Devo table
Available from release
Message Reports
Reports for every email sent and received through the Exchange Online organization
For more information on how the events are parsed, visit our page.
Minimum configuration required for basic pulling
Although this collector supports advanced configuration, the fields required to retrieve data with basic configuration are defined below.
This minimum configuration refers exclusively to those specific parameters of this integration. There are more required parameters related to the generic behavior of the collector. Check setting sections for details.
Setting
Details
Setting
Details
tenant_id
This is the Tenant ID you copied during the Obtain the client credentials step.
client_id
This is the Application (client) ID you copied during the Obtain the client credentials step.
client_secret
This is the created secret’s Value field you copied during the Obtain the client credentials step.
Accepted authentication methods
Authentication method
Details
Authentication method
Details
Modern OAuth2 Auth
You will need your Tenant ID, client ID, and Client Secret.
Vendor setup
There are some minimal requirements to enable this collector:
Microsoft Azure account: The account must be able to register applications and assign roles.
Microsoft Office 365 account: The account must have administrative permissions in the Office 365 organization.
There are some configurations you need to do to enable the collector.
Give the application a name. If needed change the Supported account types.
Click the Register button.
On the Overview page, search for your application in the list.
Under the Essentials section, copy the Application (client) ID and Directory (tenant) ID values.
On the left side menu, navigate to the Certificates & secrets page.
Click on + New client secret button.
Set a description and an expiration for the secret.
Click on the Add button.
Copy its Value field.
If you get errors, please, check your subscriptions and permissions:
# Update the client id, client secret, domain, tenant, and endpoint here
$ClientID = "<YOUR_APPLICATION_ID"
$ClientSecret = "<YOUR_CLIENT_SECRET>"
$loginURL = "https://login.microsoftonline.com/"
$tenantdomain = "<YOUR_DOMAIN>.onmicrosoft.com"
# Get the tenant GUID from Properties | Directory ID under the Azure Active Directory section. For $resource, use one of these endpoint values based on your subscription plan: Enterprise - manage.office.com; GCC - manage-gcc.office.com; GCC High: manage.office365.us; DoD: manage.protection.apps.mil
$TenantGUID = "<YOUR_TENANT_GUID>"
$resource = "https://<YOUR_API_ENDPOINT>"
# auth
$body = @{grant_type="client_credentials";resource=$resource;client_id=$ClientID;client_secret=$ClientSecret}
$oauth = Invoke-RestMethod -Method Post -Uri $loginURL/$tenantdomain/oauth2/token?api-version=1.0 -Body $body
$headerParams = @{'Authorization'="$($oauth.token_type) $($oauth.access_token)"}
# This will try to return the subscriptions list
Invoke-WebRequest -Headers $headerParams -Uri "$resource/api/v1.0/$tenantGUID/activity/feed/subscriptions/list"
If this fails, then create the subscripttions that fail with this command:
Invoke-WebRequest -Method Post -Headers $headerParams -Uri "https://<YOUR_API_ENDPOINT>/api/v1.0/$tenantGUID/activity/feed/subscriptions/start?contentType=Audit.AzureActiveDirectory"
On the left side panel of your previously registered application, navigate to the API permissions page.
Click the + Add a permission button.
On the right side modal, navigate the APIs my organization uses tab.
Select Office 365 Exchange Online entry from the list - you can use the search bar tool to find it -.
Click the Application permissions button.
Under the ReportingWebService section, mark the ReportingWebService.Read.All permission.
Click the Add permissions button.
Click ✓ Grant admin consent for {your_domain} button and then on the Yes button on the appeared modal.
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.
On the left-side menu, navigate to the Roles and administrators page.
In the list, search for the Global Reader and click on it to select it.
Click the + Add assignments button.
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.
Click the Add button.
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:
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:
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.
No permission to access the report for the organization.: The role has not been properly assigned. Review these instructions to do it.
Source Event Obfuscation
This collector obfuscates the following parameters:
tenant_id
client_id
client_secret
Run the collector
Once the data source is configured, you can either send us the required information if you want us to host and manage the collector for you (Cloud collector), or deploy and host the collector in your own machine using a Docker image (On-premise collector).
Collector services detail
This section is intended to explain how to proceed with specific actions for services.
Events service
Collector operations
This section is intended to explain how to proceed with specific operations of this collector.
