Cloud and SaaSMicrosoft 365 through Microsoft Graph

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:

SourceWhat it contains
Security alertsMicrosoft Defender XDR alerts
IncidentsMicrosoft Defender XDR incidents
Directory auditChanges in Microsoft Entra ID, such as users, groups, roles and applications
Sign-insMicrosoft Entra ID sign-in activity
Risk detectionsMicrosoft Entra ID Protection risk detections
Risky usersUsers that Microsoft Entra ID Protection flags as at risk
Advanced hunting: EmailEventsEmail delivery events from Microsoft Defender for Office 365
Advanced hunting: UrlClickEventsLink clicks from Microsoft Defender for Office 365
Purview audit logMicrosoft 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.write permission). 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. 1

    Open Microsoft Entra ID

    Open the Azure portal and click Microsoft Entra ID.

    Microsoft Entra ID
  2. 2

    Go to App registrations

    In the left menu, click App registrations.

    App registrations
  3. 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. 4

    Create a client secret

    In the new app, go to Certificates & secrets > New client secret. Add a description, set it to expire in 730 days (24 months) and click Add.

    Client secret

    Copy the secret Value now. Microsoft shows it only once and you cannot read it again later.

Step 2: Add the Microsoft Graph permissions

  1. 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. 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.

    PermissionUsed 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. 3

    Grant admin consent

    Back in API permissions, click Grant admin consent for your organization and confirm.

  4. 4

    Copy the app IDs

    Go to the app's Overview page and copy the Application (client) ID and the Directory (tenant) ID. You also need the secret value you copied in Step 1.

    App overview

Step 3: Connect Microsoft Graph in UTMStack

Each Microsoft 365 tenant connection is a config group. You can add more than one.

  1. 1

    Open the integration

    Go to Configure > Integrations, search for Graph and open the O365 Graph card. The form is at the end of the setup guide, under Connect your Microsoft 365 tenant.

  2. 2

    Fill in the form

    FieldWhat to enter
    Config group nameA 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 SecretThe secret value from Step 1.
    Cloud Environment (optional)Leave empty for the commercial Microsoft cloud. For a government cloud, type exactly GCC, GCCHigh or DoD. Any other value is treated as the commercial cloud.
  3. 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 valueSign-in addressMicrosoft Graph addressPurview audit log
(empty) or Commerciallogin.microsoftonline.comgraph.microsoft.comRead
GCClogin.microsoftonline.comgraph.microsoft.comRead
GCCHighlogin.microsoftonline.usgraph.microsoft.usNot read
DoDlogin.microsoftonline.usdod-graph.microsoft.usNot 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:".

MessageWhat to check
client ID, client secret and tenant ID are requiredFill in all three fields.
token request failed with status 400 or 401, followed by Microsoft's explanationMicrosoft 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 statusThe 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. 1

    Open the logs in UTMStack

    Open the O365 Graph card again and click View logs. Log Explorer opens with the o365-graph data 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. 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, EmailEvents
    url-clickAdvanced hunting, UrlClickEvents
    purview-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. 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.

SymptomLikely causeFix
No o365-graph events at allAdmin 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-insReading 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 usersMicrosoft 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 eventsMicrosoft 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 recordsThe 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 arriveThe 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.