Microsoft 365 through Microsoft Graph
The O365 Graph integration, new in UTMStack v12, brings Microsoft 365 security events into UTMStack through Microsoft Graph: Microsoft Defender alerts and incidents, directory audit, sign-ins, risk detections, risky users, email and link-click hunting data, and Purview audit logs. You register an app in Microsoft Entra ID; nothing is installed in your Microsoft 365 tenant.
This integration is separate from the O365 integration, which reads the Office 365 Management Activity API (see Microsoft 365 (Office 365 Management Activity API)). You can use both at the same time.
What UTMStack reads
UTMStack reads these Microsoft Graph sources every 5 minutes:
| Source | What it contains |
|---|---|
| Security alerts | Microsoft Defender XDR alerts |
| Incidents | Microsoft Defender XDR incidents |
| Directory audit | Changes in Microsoft Entra ID, such as users, groups, roles and applications |
| Sign-ins | Microsoft Entra ID sign-in activity |
| Risk detections | Microsoft Entra ID Protection risk detections |
| Risky users | Users that Microsoft Entra ID Protection flags as at risk |
Advanced hunting: EmailEvents | Email delivery events from Microsoft Defender for Office 365 |
Advanced hunting: UrlClickEvents | Link clicks from Microsoft Defender for Office 365 |
| Purview audit log | Microsoft Purview audit records (Commercial and GCC clouds only) |
Events are stored with the data type o365-graph and parsed by the shipped pipeline o365_graph/o365_graph.yaml (version 2.0.0). UTMStack v12 ships 20 detection rules for this data type; see Microsoft 365 through Microsoft Graph in the Rules tab.
The first time a config group runs, UTMStack reads up to the last 24 hours of each source. After that it continues from where it stopped.
Each read stops a few minutes short of the current time, because Microsoft publishes some records late. Events therefore arrive with a short delay.
Some sources need Microsoft licences in your tenant, for example Microsoft Defender, Microsoft Entra ID P1 or P2 (sign-ins) or Microsoft Entra ID Protection (risk detections and risky users). If Microsoft refuses a source because of a missing permission or licence, UTMStack skips that source for one hour and then tries again. It keeps reading the other sources meanwhile.
Before you start
In Microsoft Entra ID, you need a role that can register applications and grant admin consent.
In UTMStack, you need the Administrator role (the
integrations.writepermission). Configuration is saved in the tenant you are working in.The UTMStack server must be able to reach Microsoft over HTTPS (outbound port 443).
Step 1: Register an app in Microsoft Entra ID
- 1
Open Microsoft Entra ID
Open the Azure portal and click Microsoft Entra ID.
- 2
- 3
Register a new app
Click New registration. Enter a name, for example UTMStack Graph, select Accounts in this organizational directory only (Single tenant) and click Register.
- 4
Step 2: Add the Microsoft Graph permissions
- 1
Open the Microsoft Graph permissions
In the same app, go to API permissions > Add a permission, select Microsoft Graph and then Application permissions.
- 2
Add the permissions
Add these application permissions. The first four are the ones the UTMStack setup guide lists; the others match the Microsoft Graph sources in the table above.
Permission Used for SecurityEvents.Read.AllListed by the UTMStack setup guide Directory.Read.AllDirectory audit and sign-ins AuditLog.Read.AllDirectory audit and sign-ins IdentityRiskEvent.Read.AllRisk detections SecurityAlert.Read.AllSecurity alerts SecurityIncident.Read.AllIncidents IdentityRiskyUser.Read.AllRisky users ThreatHunting.Read.AllAdvanced hunting ( EmailEvents,UrlClickEvents)AuditLogsQuery.Read.AllPurview audit log - 3
Grant admin consent
Back in API permissions, click Grant admin consent for your organization and confirm.
- 4
Step 3: Connect Microsoft Graph in UTMStack
Each Microsoft 365 tenant connection is a config group. You can add more than one.
- 1
Open the integration
Go to Configure > Integrations, search for
Graphand open the O365 Graph card. The form is at the end of the setup guide, under Connect your Microsoft 365 tenant. - 2
Fill in the form
Field What to enter Config group name A name for this connection, for example acme-prod. It cannot be changed later, and it becomes the data source name on the Data Sources page.Tenant ID (Directory ID) The Directory (tenant) ID from Step 2. Client ID (Application ID) The Application (client) ID from Step 2. Client Secret The secret value from Step 1. Cloud Environment (optional) Leave empty for the commercial Microsoft cloud. For a government cloud, type exactly GCC,GCCHighorDoD. Any other value is treated as the commercial cloud. - 3
Save
Click Add config group. UTMStack signs in to Microsoft with the app's credentials before it saves them. When sign-in works, you see "Config group created successfully."
The save checks that UTMStack can sign in. It does not stop you when a permission or licence is missing: in that case the config group is saved anyway. After saving, check that events arrive (see below), and review the permissions if some sources stay empty.
| Cloud Environment value | Sign-in address | Microsoft Graph address | Purview audit log |
|---|---|---|---|
(empty) or Commercial | login.microsoftonline.com | graph.microsoft.com | Read |
GCC | login.microsoftonline.com | graph.microsoft.com | Read |
GCCHigh | login.microsoftonline.us | graph.microsoft.us | Not read |
DoD | login.microsoftonline.us | dod-graph.microsoft.us | Not read |
If the save fails
The check signs in to Microsoft and then asks Microsoft Graph for one security alert. When sign-in fails, the config group is not saved and the message starts with "credential verification failed: o365_graph:".
| Message | What to check |
|---|---|
| client ID, client secret and tenant ID are required | Fill in all three fields. |
| token request failed with status 400 or 401, followed by Microsoft's explanation | Microsoft rejected the sign-in. Read the explanation: it names the problem, for example a wrong secret (paste the secret Value, not the Secret ID), an expired secret, or an app that does not exist in that tenant. |
| token request failed, without a status | The UTMStack server cannot reach the Microsoft sign-in address on port 443, or the Cloud Environment value is wrong. |
| alerts_v2 probe failed with status ... | Microsoft Graph answered with an unexpected error. Try again later. |
When sign-in works but the alert request is refused because of a missing permission or licence, the config group is saved anyway. Check the permissions and licences if some sources stay empty.
Check that events arrive
- 1
Open the logs in UTMStack
Open the O365 Graph card again and click View logs. Log Explorer opens with the
o365-graphdata type for the last 24 hours. UTMStack reads new events every 5 minutes, and the first read brings in up to 24 hours of earlier events, so sign-ins and directory changes from today usually appear within 10 minutes. - 2
Check which sources arrive
The pipeline tags every event with the Graph source it came from, in the field
log.graphSource. In Log Explorer, switch to Chart and chart that field to count events per source. The values are:log.graphSourceGraph source security-alertsSecurity alerts security-incidentsIncidents directory-auditDirectory audit sign-insSign-ins risk-detectionsRisk detections risky-userRisky users huntingAdvanced hunting, EmailEventsurl-clickAdvanced hunting, UrlClickEventspurview-auditPurview audit log A source you expected but do not see usually lacks a permission or a licence. Sources only produce events when there is activity: a tenant with no Defender alerts today shows no
security-alerts. - 3
Check the data source
Go to Configure > Data Sources and open the Integrations tab. Your config group is listed by its name. The row is created when you save, and turns Live after the first events are counted, which can take up to 20 minutes.
Troubleshooting
Errors that happen after the config group is saved, for example a refused source, do not appear in the web interface. They are written to the logs of the UTMStack event processor on the server, where the integration runs.
| Symptom | Likely cause | Fix |
|---|---|---|
No o365-graph events at all | Admin consent was not granted, or the secret is wrong or expired. | In API permissions, check that every permission shows as granted. Create a new secret if needed and update the config group. |
| Directory audit arrives, but no sign-ins | Reading sign-ins needs a Microsoft Entra ID P1 or P2 licence. | Assign the licence, or accept that sign-ins are not collected. |
| No risk detections or risky users | Microsoft Entra ID Protection is not licensed, or IdentityRiskEvent.Read.All / IdentityRiskyUser.Read.All is missing. | Add the permission and grant admin consent. Within an hour UTMStack tries the source again. |
| No alerts, incidents or email events | Microsoft Defender is not licensed, or SecurityAlert.Read.All, SecurityIncident.Read.All or ThreatHunting.Read.All is missing. | Add the permission and grant admin consent. |
| No Purview audit records | The Cloud Environment is GCCHigh or DoD (not read there), or AuditLogsQuery.Read.All is missing. | For Commercial and GCC tenants, add the permission and grant admin consent. |
| The Integrations row shows Offline although events arrive | The data source's "last seen" time is updated from the ingestion counts, which can take up to about 20 minutes. | Wait 20 minutes and click Refresh. |
Manage config groups
Add more connections: save one config group per Microsoft 365 tenant.
Edit: click the pencil icon next to a config group. The name cannot be changed. The client secret shows a masked value; leave it as it is to keep the stored secret. Click Update config group.
Delete: click the bin icon. The config group is deleted at once, without a confirmation, and collection stops. The data source it created stays on the Data Sources page; delete it there if you no longer need it.
Renew the secret: the client secret expires after the period you chose in Step 1. Before it expires, create a new secret in Microsoft Entra ID, then edit the config group and paste the new value.