Microsoft has announced deprecation of the legacy Message Trace API and Reporting Web Service endpoint. The new Microsoft Graph Source is available, and legacy Message Trace support is scheduled for deprecation on April 8, 2026. Plan to migrate to this Source before that date to avoid data loss.

Cribl Stream supports receiving Microsoft 365 Message Trace data via the Microsoft 365 Graph Source. This data can be used to detect and report on malicious activity, including bulk emails, spoofed-domain emails, and data exfiltration.

The Microsoft 365 Graph Source uses a scheduled REST Collector under the hood. 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.

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

TLS is enabled via HTTPS on this Source’s underlying Microsoft Graph REST API.

Prerequisites and Microsoft 365 Setup

​

At a minimum, your Microsoft 365 service account or application must have permissions to access Message Trace data via Microsoft Graph and be assigned to a tenant that contains Exchange Online.

For detailed prerequisites and Microsoft Graph permission requirements, follow Microsoft’s Graph-based message trace API onboarding guide. This guide walks you through registering an app, configuring ExchangeMessageTrace.Read.All application permissions, granting admin consent, and provisioning the required Service Principal in your tenant.

You must also ensure that your account or application has appropriate roles for message tracking and mail flow reporting in Exchange Online and Microsoft Entra ID,

While the exact roles and Graph permissions can vary by environment and Microsoft cloud, make sure to:

• Assign a role that allows access to message tracking/reporting.
• Ensure that the account or application is scoped appropriately for your tenant and compliance requirements.
• Confirm that all required Microsoft Graph application permissions have admin consent granted for your tenant.

To validate your configuration and experiment with queries and permissions, you can use Microsoft Graph Explorer. Graph Explorer lets you sign in to your tenant, test the Graph-based Message Trace APIs, and verify that your app registration and permissions return the data you expect before wiring them into this Source.

Modern Authentication (OAuth 2.0) Setup

​

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 Microsoft 365 setup.

1. In the Microsoft Azure portal, create a Microsoft Entra ID App Registration for Cribl Stream. This will automatically create a corresponding Service Principal in your tenant. For details, see the Microsoft Azure documentation.
2. Grant your Application the Microsoft Graph permissions required for Message Trace.
   • Navigate to API permissions on your App Registration and select Add a permission.
   • On the Microsoft APIs tab, select Microsoft Graph and grant the appropriate Application permissions (ExchangeMessageTrace.Read.All).
3. Assign the Service Principal a Microsoft Entra ID role that enables it to access the Graph-based Message Trace data.

Configure Cribl Stream to Receive Microsoft Graph Message Trace Data

​

1. On the top bar, select Products, and then select Cribl Stream. Under Worker Groups, select a Worker Group. Next, you have two options:
   • To configure via QuickConnect, navigate to Routing > QuickConnect. Select Add Source and select the Source you want from the list, choosing either Select Existing or Add New.
   • To configure via the Routes, select Data > Sources. Select the Source you want. Next, select Add Source.
2. In the New Source modal, configure the following under General Settings:
   • Input ID: Enter a unique name to identify this Source definition. If you clone this Source, Cribl Stream will add -CLONE to the original Input ID.
   • Description: Optionally, enter a description.
   • Endpoint: The Microsoft Graph API endpoint URL (for example, https://graph.microsoft.com/v1.0/admin/exchange/tracing/messageTraces).
   • 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. The default value of 60 means the Source will run the collection job every 60 minutes.
3. Under Authentication:
   • Authentication method: Select an authentication method: OAuth, OAuth (text secret), or OAuth Certificate. The default is OAuth. All OAuth options rely on the OAuth 2.0 protocol.
   • Client secret: client_secret to pass in the OAuth request parameter.
   • Tenant identifier: Directory ID (tenant identifier) in Azure Active Directory.
   • Client ID: client_id to pass in the OAuth request parameter.
   • Resource: Resource to pass in the OAuth request parameter.
   • Subscription plan: Your Office 365 subscription plan for your organization, typically Office 365 Enterprise.
4. Next, you can configure the following 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, the value defaults to info.
   • Tags: Optionally, add tags that you can use to filter and group Sources in Cribl Stream’s UI. These tags aren’t added to processed events. Use a tab or hard return between (arbitrary) tag names.
5. Optionally, you can adjust the Processing, Retries, and Advanced settings, or Connected Destinations outlined in the sections below.
6. Select Save, then Commit & Deploy.

Authentication

​

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://graph.microsoft.com.

OAuth Secret Authentication

​

Selecting OAuth (text secret) exposes three of the same controls as the default OAuth method, but 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://graph.microsoft.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 newer - 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://graph.microsoft.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

Processing Settings

​

Fields

​

In this section, you can define new fields or modify existing ones using JavaScript expressions, similar to the Eval function.

• The Field Name can either be a new field (unique within the event) or an existing field name to modify its value.

• The Value is a JavaScript expression (enclosed in quotes or backticks) to compute the field’s value (can be a constant). Select this field’s advanced mode icon (far right) if you’d like to open a modal where you can work with sample data and iterate on results.

This flexibility means you can:

• Add new fields to enrich the event.
• Modify existing fields by overwriting their values.
• Compute logic or transformations using JavaScript expressions.

Pre-Processing

​

In this section’s Pipeline drop-down list, you can select a single existing Pipeline or Pack 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. The default is set to Backoff, meaning Cribl Stream will use an exponential backoff for retries.

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 limit specified in Retry limit. The default is set to 1000.

Retry limit: Maximum number of times to retry a failed HTTP request. Maximum: 20. A value of 0 means don’t retry at all. The default value is 5.

Backoff multiplier: Base for exponential backoff. The default value is 2 and 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, 500, and 503). Cribl Stream does not retry codes in the 200 series.

Honor Retry-After header: When toggled on (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 off, Cribl Stream ignores all retry-after headers.

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

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

Advanced Settings

​

Request timeout (seconds): Max time to wait for an individual Graph Message Trace request. The default is 300 seconds.

Reschedule tasks and Task reschedule limit: Automatically reschedule tasks that fail with non-fatal errors. The default for Task reschedule limit is 1.

Job timeout: Max time a job can run. A value of 0 means the time is unlimited.

Time to live: How long to keep job artifacts on disk and in Job Inspector. The default is 4h, meaning Cribl Stream keeps the collector’s job artifacts on disk and visible in Job Inspector for 4 hours, then automatically cleans them up.

Disable time filter: Controls Collector event time filtering when a date range is specified.

Environment: For GitOps workflows, optionally restrict this configuration to a single Git branch; leave empty to enable 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

Connected Destinations

​

Select Send to Routes to enable conditional routing, filtering, and cloning of this Source’s data via the Routing table.

Select QuickConnect to send this Source’s data to one or more Destinations via independent, direct connections.

Viewing Scheduled Jobs

​

After saving the Source:

• Reopen the Source’s configuration modal and select the Job Inspector tab to view results for this Source’s scheduled jobs.
• Or go to Monitoring > System > Job Inspector > Currently Scheduled to see jobs across all Collectors and Sources.

Mitigating Stuck-Job Problems

​

Occasionally, a scheduled job fails but continues running for a long time (“stuck”, “orphaned”, or “zombie” jobs). This can cause missing events downstream and HTTP timeouts in logs.

To reduce risk:

1. Lower Request timeout (secs) to a value shorter than the default (for example, under 300 seconds).
2. Set Job timeout to a maximum duration so stuck jobs are terminated automatically.

Proxying Requests

​

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

See Also

​

The Community-contributed Microsoft Office Activity & Azure Logs Pack provides sample Pipelines to parse and streamline ingested Office 365 and EntraID/Azure AD data. You can import these and adapt them to your own needs.

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 Issues

​

Job fails with statusCode: 401

​

If a collection job fails with HTTP 401, check for:

• Incorrect or missing Microsoft Graph permissions.
• Expired or invalid OAuth access tokens.
• Misconfigured Resource or scope values in the OAuth request.