Microsoft Graph with Cribl Stream

What the source collects

The Microsoft Graph Source in Cribl Stream pulls Microsoft 365 Message Trace data via the Microsoft 365 Graph Source, documented on the Microsoft Graph source page. The page says the data can be used to detect and report on malicious activity, including bulk emails, spoofed-domain emails, and data exfiltration.

The page classifies it as a Pull-type source with TLS support and Event Breaker support; TLS is enabled via HTTPS over the underlying Microsoft Graph REST API. Under the hood it is a scheduled REST Collector: one collection task runs every Poll interval on a single Worker, and the Worker might make multiple calls because the data is paginated.

The Source supports delta queries for incremental collection, returning only records that changed since the last poll. Delta mode activates automatically when the Endpoint URL ends with /delta, and query parameters can follow, so https://graph.microsoft.com/v1.0/users/delta?$select=id also enables delta mode. Because delta endpoints do not support $filter date-range queries, the Date range start and Date range end settings are ignored while delta mode is active, and not all Microsoft Graph endpoints support delta queries, per the page's pointer to the delta query overview.

On the final page of each paginated response, the Source extracts the @odata.deltaLink value from the Graph API and saves it to state. On the next poll, a valid delta link in state sends the request to the delta link URL rather than the configured endpoint, fetching only changed records. Change the Endpoint to a different delta-enabled path and the first collection run performs a full sync, with incremental polling resuming on the second run. The state expressions are set automatically and not configurable, per the source page:

State update expression: null
State merge expression: (newState && "deltaLink" in newState) ? newState : prevState

If Microsoft returns an HTTP 410 Gone response, the delta token has expired: the Source logs a warning, clears the saved state, and performs a full re-sync on the next poll, after which incremental polling resumes automatically. The Source also uses internal, or meta, fields that are not part of an event but that Functions can use to make processing decisions: __final, __inputId, __isBroken, and __source.

Setting up the source

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. The page points to Microsoft's Graph-based message trace API onboarding guide for registering an app, configuring the ExchangeMessageTrace.Read.All application permission, granting admin consent, and provisioning the required Service Principal. Appropriate roles for message tracking and mail flow reporting are also required in Exchange Online and Microsoft Entra ID; because roles and permissions can vary by environment and Microsoft cloud, the page says to scope the account or application to your tenant and compliance requirements and confirm that all required Graph application permissions have admin consent granted.

To use any of the three OAuth methods, configure an Application and its associated Service Principal within Microsoft Entra ID as part of your Microsoft 365 setup. In the Microsoft Azure portal, create a Microsoft Entra ID App Registration for Cribl Stream, which automatically creates the corresponding Service Principal. Under API permissions, select Add a permission; on the Microsoft APIs tab, select Microsoft Graph and grant the Application permission ExchangeMessageTrace.Read.All. Then assign the Service Principal a Microsoft Entra ID role that enables it to access the Graph-based Message Trace data.

In Cribl Stream, select Products, then Cribl Stream, and under Worker Groups select a Worker Group. The page gives two paths: QuickConnect (Routing > QuickConnect, then Add Source with Select Existing or Add New) or Routes (Data > Sources, then Add Source). In the New Source modal, configure General Settings: Input ID (a unique name; cloning adds -CLONE to the original), optional Description, and Endpoint (the Microsoft Graph API endpoint URL), for example, copied from the Microsoft Graph source page:

https://graph.microsoft.com/v1.0/admin/exchange/tracing/messageTraces

Poll interval is how often, in minutes, to run the report; the value must divide evenly into 60 minutes to create a predictable schedule, or Save will fail, and the default of 60 runs the collection job every 60 minutes.

Under Authentication, the methods are OAuth (the default), OAuth (text secret), and OAuth Certificate, all relying on the OAuth 2.0 protocol. The default OAuth method exposes required fields: Client secret (client_secret), Tenant identifier (the Directory ID in Microsoft Entra ID), Client ID (client_id), and Resource, defaulting to https://graph.microsoft.com. OAuth (text secret) exposes the same controls except the Client secret is entered by reference: select an existing stored client_secret from the drop-down, or store a new, reusable secret with the adjacent Create button.

OAuth Certificate, available in Cribl Stream 4.1.3 and newer, exposes the Tenant identifier and Client ID controls plus controls for the certificate used to authenticate; all fields are required except the optional Passphrase (only if the private key requires it to decrypt). Select an existing Certificate, or store a new, reusable one with the adjacent Create button. Private key path and Certificate path take PEM-format files and can reference $ENV_VARS. Subscription Plan options include Microsoft 365 Enterprise, Microsoft 365 GCC, Microsoft 365 GCC High, and Microsoft 365 DoD.

Under Optional Settings, Date range start and Date range end specify the time window for data collection, which the page says helps compensate for delays and gaps; use a relative format like -3h@h for ongoing collection or an exact epoch value like 1720536960 to backfill gaps. Log level sets the collection runtime log to debug, info, warn, or error, defaulting to info. Tags optionally filter and group Sources in the Cribl Stream UI and are not added to processed events; separate tag names with a tab or hard return.

Under Processing, you can define new fields or modify existing ones with JavaScript expressions similar to Eval; Pre-Processing selects a single existing Pipeline or Pack before the data goes through the Routes. Under Retries, the defaults are the Backoff algorithm, an initial interval of 1000 ms, a retry limit of 5, a backoff multiplier of 2, and retry on HTTP codes 429, 500, and 503; the 200 series is not retried. Under Advanced Settings, the request timeout (seconds) defaults to 300 and Time to live defaults to 4h for job artifacts kept on disk and in Job Inspector.

For Connected Destinations, select Send to Routes for conditional routing, filtering, and cloning via the Routing table, or QuickConnect for independent, direct connections to one or more Destinations. If you need to proxy HTTP/S requests, the page points to the System Proxy Configuration documentation. Finally, select Save, then Commit & Deploy.

What the docs flag

• Microsoft has announced deprecation of the legacy Message Trace API and Reporting Web Service endpoint; the page says to plan the migration to this Source before the April 8, 2026 deprecation date to avoid data loss.
• Cribl Stream uses the _time field as the canonical timestamp for events, and for this Source _time is not taken from any Graph payload field by default. It is populated at ingest using each event's import time, keeping the Source safe to use with any Microsoft Graph endpoint, including resources that do not expose a receivedDateTime field. To get _time from a specific field such as receivedDateTime, the page directs you to a Pipeline, such as an Auto Timestamp step in a pre-processing Pipeline.
• Scheduled jobs can occasionally fail but keep running for a long time ("stuck", "orphaned", or "zombie" jobs), causing missing events downstream and HTTP timeouts in logs. To reduce risk, the page suggests lowering Request timeout (secs) below the default 300 seconds and setting Job timeout so stuck jobs terminate automatically.
• If a job fails with HTTP 401, check for incorrect or missing Microsoft Graph permissions, expired or invalid OAuth access tokens, and misconfigured Resource or scope values.

Frequently asked questions

What does the Microsoft Graph Source in Cribl Stream collect?

It pulls Microsoft 365 Message Trace data via the Microsoft 365 Graph Source. It is a Pull-type source with TLS support and Event Breaker support, and the data can be used to detect and report on malicious activity, including bulk emails, spoofed-domain emails, and data exfiltration.

How often does the Microsoft Graph Source in Cribl Stream run its collection jobs?

It runs one collection task for every Poll interval; the default of 60 means the job runs every 60 minutes. The data is paginated, so the Worker might make multiple calls, and the interval must divide evenly into 60 minutes or Save fails.

How does token authentication work on the Microsoft Graph Source in Cribl Stream?

The default OAuth method takes a client secret, a Tenant identifier, a Client ID, and a Resource, and every OAuth option relies on the OAuth 2.0 protocol. OAuth (text secret) selects an existing stored secret from a drop-down, and OAuth Certificate, available in Cribl Stream 4.1.3 and newer, uses a PEM certificate and private key.

What happens when the delta token expires on the Microsoft Graph Source in Cribl Stream?

If Microsoft returns an HTTP 410 Gone response, the delta token has expired. The Source logs a warning, clears the saved state, and performs a full re-sync on the next poll, and incremental polling resumes automatically after that.