On This Page

Home / Stream/ Sources/ Office 365·Office 365 Message Trace Source

Office 365 Message Trace Source

Cribl Stream supports receiving Office 365 Message Trace data. This mail-flow metadata can be used to detect and report on malicious activity including bulk emails, spoofed-domain emails, and data exfiltration.

Type: Pull | TLS Support: YES | Event Breaker Support: YES

TLS is enabled via the HTTPS protocol on this Source’s underlying REST API.

Office 365 Setup
​

At a minimum, your Office 365 service account should include a role with Message Tracking and View‑Only Recipients permissions, assigned to the Office 365 user that will integrate with Cribl Stream. Assign these permissions in the Exchange admin center (https://admin.exchange.microsoft.com).

Modern Authentication (OAuth 2.0) Setup
​

If you plan to use OAuth, OAuth Secret, or OAuth Certificate authentication, you must configure an Application and its associated Service Principal within Microsoft Entra ID as part of your Office 365 setup.

  1. In the Microsoft Azure portal, create a Microsoft Entra ID App Registration. This will automatically create a corresponding Service Principal in your tenant. For details, see the Microsoft Azure documentation.

  2. Grant your Application the API permissions it needs to access Office 365 Message Trace data.

    • On your newly created App Registration, navigate to API permissions and select Add a permission.
    • On the Microsoft APIs tab, select Office 365 Exchange Online. If it’s not immediately visible, search for Office 365 Exchange Online.
    • Under Application permissions, add the ReportingWebService.Read.All permission and consent to the changes.


    For detailed steps on adding API permissions, see Microsoft’s documentation on how to add permissions to access web APIs.

  3. Assign the Service Principal (your registered Application’s identity in the tenant) at least one Azure AD role that will enable it to access the Reporting Web Service:

    • Global Reader
    • Global Administrator
    • Exchange Administrator


    For detailed steps on assigning Azure AD roles to a Service Principal (Application), see Microsoft’s documentation on how to assign Microsoft Entra roles. When assigning the role, you will search for your Application name (the Service Principal) to select it as a member.

If you encounter an error with statusCode: 401 and details showing host:"reports.office365.com" and path:"/ecp/reportingwebservice/reporting.svc/MessageTrace", this indicates the App Registration (Service Principal) is not correctly authorized to access the Office 365 Message Trace service.

Configuring Cribl Stream to Receive Office 365 Message Trace Data
​

From the top nav, click Manage, then select a Worker Group to configure. Next, you have two options:

  • To configure via QuickConnect, click Routing then QuickConnect (Cribl Stream) or Collect (Cribl Edge). Next, click Add Source and from the resulting drawer’s tiles, select Office 365 Message Trace. Next, click either Add Source or (if displayed) Select Existing.
  • To configure via the Routes, click Data then Sources (Cribl Stream) or More then Sources (Cribl Edge). Select Office 365 Message Trace from the list of tiles or the Sources list. Next, click Add Source to open a New Source modal.

General Settings
​

Input ID: Enter a unique name to identify this Office 365 Message Trace definition. If you clone this Source, Cribl Stream will add -CLONE to the original Input ID.

Report URL: Enter the URL to use when retrieving report data. Defaults to: https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace.

Poll interval: How often (in minutes) to run the report. Must divide evenly into 60 minutes to create a predictable schedule, or Save will fail. See About Polling Intervals below.

Authentication Settings
​

In the Authentication section, use the buttons to select an Authentication method: Basic, Basic (credentials secret), OAuth, OAuth (text secret), or OAuth Certificate. The default is OAuth. All OAuth options rely on the OAuth 2.0 protocol.

Basic Authentication
​

Selecting Basic exposes Username and Password fields, where you directly enter the HTTP Basic credentials to use on Message Trace API calls.

Basic Secret Authentication
​

Selecting Basic (credentials secret) exposes a Credentials secret drop-down, where you select an existing stored secret that references your credentials on the Message Trace API. You can use the adjacent Create button to store a new, reusable secret.

OAuth Authentication
​

The default OAuth authentication method exposes the following fields, all required:

  • Client secret: Directly enter the client_secret to pass in the OAuth request parameter.
  • Tenant identifier: Directory ID (tenant identifier) in Microsoft Entra ID.
  • Client ID: The client_id to pass in the OAuth request parameter.
  • Resource: Resource parameter to pass in the OAuth request parameter. Defaults to: https://outlook.office365.com.
OAuth Secret Authentication
​

Selecting OAuth (text secret) exposes three of the same controls as the default OAuth method, but – as you’d expect – you instead enter the Client secret by reference:

  • Client secret: Use the drop-down to select an existing stored client_secret to pass in the OAuth request parameter. You can use the adjacent Create button to store a new, reusable secret.
  • Tenant identifier: Directory ID (tenant identifier) in Microsoft Entra ID.
  • Client ID: The client_id to pass in the OAuth request parameter.
  • Resource: Resource parameter to pass in the OAuth request parameter. Defaults to: https://outlook.office365.com.
OAuth Certificate Authentication
​

Selecting OAuth (certificate) exposes two of the same controls as the above OAuth methods (Tenant identifier and Client ID). But this authentication method – available in Cribl Stream 4.1.3 and later – foregrounds controls to define the certificate you’re using to authenticate. Treat all fields here as required, except for the optional Passphrase:

  • Certificate name: Use the drop-down to select an existing certificate to pass in the OAuth request parameter. You can use the adjacent Create button to store a new, reusable cert.
  • Private key path: Path to the private key to use. The key should be in PEM format. Can reference $ENV_VARS.
  • Passphrase: If your private key requires a passphrase to decrypt it, enter that passphrase here.
  • Certificate path: Path to the certificate to use. The cert should be in PEM format. Can reference $ENV_VARS.
  • Tenant identifier: Directory ID (tenant identifier) in Microsoft Entra ID.
  • Client ID: The client_id to pass in the OAuth request parameter.
  • Resource: Resource parameter to pass in the OAuth request parameter. Defaults to: https://outlook.office365.com.
  • Subscription Plan: Select the Office 365 subscription plan for your organization. Options include:
    • Office 365 Enterprise
    • Office 365 GCC
    • Office 365 GCC High
    • Office 365 DoD

Optional Settings
​

Use the Date range start and Date range end settings to specify the time window for data collection. These settings help compensate for delays and gaps in Message Trace data. Use relative time formats for ongoing data collection and exact epoch values to backfill specific time gaps.

Date range start: Backward offset for the head of the search date range. Supports relative time format like -3h@h or exact epoch values like 1720536960.

Date range end: Backward offset for the tail of the search date range. Supports relative time format like -2h@h or exact epoch values like 1720533360.

Log level: For data collection’s runtime log, set the verbosity level to one of debug, info, warn, or error. (If not selected, defaults to info.)

Tags: Optionally, add tags that you can use to filter and group Sources in Cribl Stream’s Manage Sources page. These tags aren’t added to processed events. Use a tab or hard return between (arbitrary) tag names.

About Polling Intervals
​

To poll the Office 365 Message Trace API, Cribl Stream uses the Poll interval field’s value to establish the cron schedule. For example, */${interval} * * * *.

Because the interval is set in minutes, it must divide evenly into 60 minutes to create a predictable schedule. Dividing 60 by intervals like 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, or 60 itself yields an integer, so you can enter any of these values.

Cribl Stream will reject intervals like 23, 42, or 45, or 75 – which would yield non-integer results, meaning unpredictable schedules.

Processing Settings
​

Fields
​

In this section, you can add Fields to each event, using Eval-like functionality.

Name: Field name.

Value: JavaScript expression to compute field’s value, enclosed in quotes or backticks. (Can evaluate to a constant.)

Pre-Processing
​

In this section’s Pipeline drop-down list, you can select a single existing Pipeline to process data from this input before the data is sent through the Routes.

Retries
​

Retry type: The algorithm to use when performing HTTP retries. Options include Backoff (the default), Static, and Disabled.

Initial retry interval (ms): Time interval between failed request and first retry (kickoff). Maximum allowed value is 20,000 ms (1/3 minute). A value of 0 means retry immediately until reaching the retry limit in Max retries.

Max retries: Maximum number of times to retry a failed HTTP request. Defaults to 5. Maximum: 20. A value of 0 means don’t retry at all.

Backoff multiplier: Base for exponential backoff. A value of 2 (default) means that Cribl Stream will retry after 2 seconds, then 4 seconds, then 8 seconds, and so on.

Retry HTTP codes: List of HTTP codes that trigger a retry. Leave empty to use the defaults (429 and 503). Cribl Stream does not retry codes in the 200 series.

Honor Retry-After header: When toggled to Yes (the default) and the retry-after header is present, Cribl Stream honors any retry-after header that specifies a delay, up to a maximum of 20 seconds. Cribl Stream always ignores retry-after headers that specify a delay longer than 20 seconds.

  • Cribl Stream will log a warning message with the delay value retrieved from the retry-after header (converted to ms).
  • When toggled to No, Cribl Stream ignores all retry-after headers.

Retry Connection Timeout: Toggle to Yes to automatically retry a single connection attempt after a timeout (ETIMEDOUT) to ensure data continuity.

Retry Connection Reset: Toggle to Yes to automatically retry a connection after a peer reset (ECONNRESET) to maintain data flow.

Advanced Settings
​

Request timeout (secs): Maximum time to wait for an individual Message Trace API request to complete. Defaults to 300 seconds (5 minutes). Enter 0 to disable metering, allowing unlimited response time. Because there is a single request to the Message Trace API per page of data, this timeout is applied at the page (request) level.

Job timeout: Maximum time a job is allowed to run. Defaults to 0, for unlimited time. Units are seconds if not specified. Sample entries: 30, 45s, 15m.

Time to live: How long to keep the job’s artifacts on disk after job completion. This also affects how long a job is listed in Job Inspector. Defaults to 4h.

Disable time filter: Disables Collector event time filtering when a date range is specified in General Settings. Toggle to No to allow filtering.

Environment: If you’re using GitOps, optionally use this field to specify a single Git branch on which to enable this configuration. If empty, the config will be enabled everywhere.

Internal Fields
​

Cribl Stream uses a set of internal fields to assist in handling of data. These “meta” fields are not part of an event, but they are accessible, and Functions can use them to make processing decisions.

Fields for this Source:

  • __final
  • __inputId
  • __isBroken
  • __source

How Cribl Stream Pulls Data
​

The Office 365 Message Trace Source uses a scheduled REST Collector. It runs one collection task every Poll interval, and a single Worker will process the collection. The data is paginated, so the Worker might make multiple calls to fetch the data.

Viewing Scheduled Jobs
​

This Source executes Cribl Stream’s scheduled collection jobs. Once you’ve configured and saved the Source, you can view those jobs’ results by reopening the Source’s config modal and clicking its Job Inspector tab.

You can also view these jobs (among scheduled jobs for other Collectors and Sources) in the Monitoring > System > Job Inspector > Currently Scheduled tab.

Mitigating Stuck-Job Problems
​

Occasionally, a scheduled job fails, but continues running for hours or even days, until someone intervenes and cancels it. If left alone, such a “stuck”, “orphaned,” or “zombie” job will never complete. This can cause missing events in downstream receivers, along with HTTP timeout or similar errors in Cribl Stream’s logs.

To keep stuck jobs from running excessively long:

  • First, try setting Advanced > Timeout (secs) to a duration shorter than the default of 600 seconds (10 minutes).
  • If adjusting Timeout (secs) does not fix the problem, try setting Advanced > Job Timeout – whose default of 0 allows a job to run indefinitely – to a desired maximum duration.

Using these settings in tandem works like this:

  • Timeout (secs) limits the time that Cribl Stream will wait for an HTTP request to complete.
  • Then, if a job gets stuck and keeps running beyond that limit, Job Timeout can catch and terminate the job, because it monitors the overall time the job has been running.

Proxying Requests
​

If you need to proxy HTTP/S requests, see System Proxy Configuration.

Troubleshooting
​

The Source’s configuration modal has helpful tabs for troubleshooting:

Live Data: Try capturing live data to see real-time events as they are ingested. On the Live Data tab, click Start Capture to begin viewing real-time data.

Logs: Review and search the logs that provide detailed information about the ingestion process, including any errors or warnings that may have occurred.

You can also view the Monitoring page that provides a comprehensive overview of data volume and rate, helping you identify ingestion issues. Analyze the graphs showing events and bytes in/out over time.

Common Issue
​

“Dropping request because token invalid”,“authToken”: “Bas…Njc=”"
​

The specified token is invalid. Note the above message is logged only at debug level.