Microsoft 365 (Office 365 Management Activity API)
The O365 integration brings Microsoft 365 audit activity into UTMStack through the Office 365 Management Activity API. You register an app in Microsoft Entra ID, and UTMStack uses it to read audit and security events from Exchange, SharePoint, OneDrive, Teams and Microsoft Entra ID. Nothing is installed in your Microsoft 365 tenant.
To also collect Microsoft Defender alerts and incidents, sign-ins and risk detections, use the separate Microsoft 365 through Microsoft Graph integration. You can use both integrations at the same time.
How it works
UTMStack signs in with the app's client ID and secret (OAuth, the standard way an app gets a time-limited access token from Microsoft) and reads the Office 365 Management Activity API every 5 minutes.
It starts the API subscriptions for these content types itself, so you do not need to:
Audit.AzureActiveDirectory,Audit.Exchange,Audit.General,Audit.SharePointandDLP.All.It reads the audit content that Microsoft publishes from the moment collection starts (with a 5-minute margin). Content published before that is not imported.
Events are stored with the data type
o365and parsed by the shipped pipelineoffice365/o365.yaml(version 1.4.2). UTMStack v12 ships 73 detection rules for this data type; see Office 365 in the Rules tab.
Microsoft does not publish audit records instantly. According to Microsoft, after a subscription is first created it can take up to 12 hours before the first content is available. After that, records usually arrive with a delay of minutes to a few hours, depending on the workload.
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
- 4
Step 2: Add the API permissions
- 1
- 2
- 3
- 4
- 5
The steps above follow the setup guide in the product. In UTMStack v12.0.2 this integration reads only the Office 365 Management Activity API, which needs ActivityFeed.Read (and ActivityFeed.ReadDlp to include the sensitive data details of DLP events). The Microsoft Graph SecurityAlert permissions are not used by this integration. If your policy allows only the permissions an app really uses, you can leave them out. Microsoft Defender alerts are collected by the Microsoft 365 through Microsoft Graph integration instead.
Step 3: Make sure audit logging is on
The Office 365 Management Activity API returns events only when audit logging is turned on for your organization.
Sign in to the Microsoft Purview portal and open the Audit solution.
If auditing is not turned on, a banner asks you to start recording user and admin activity. Select it.
The change can take up to 60 minutes to take effect.
You can also check and turn it on with Exchange Online PowerShell:
Get-AdminAuditLogConfig | Format-List UnifiedAuditLogIngestionEnabled
Set-AdminAuditLogConfig -UnifiedAuditLogIngestionEnabled $trueThe first command shows True when auditing is on.
Step 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.
Step 5: Connect Microsoft 365 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
O365and open the O365 card. The form is at the end of the setup guide, under Connect your Microsoft 365 tenant.The guide says no write permissions are requested, but its steps add SecurityAlert.ReadWrite.All, which this integration does not use (see the note above).
- 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 4. Client ID (Application ID) The Application (client) ID from Step 4. 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 checks the credentials by signing in to Microsoft before it saves them. When the check passes, you see "Config group created successfully."
| Cloud Environment value | Sign-in address | Management API address |
|---|---|---|
(empty) or Commercial | login.microsoftonline.com | manage.office.com |
GCC | login.microsoftonline.com | manage-gcc.office.com |
GCCHigh | login.microsoftonline.us | manage.office365.us |
DoD | login.microsoftonline.us | manage.protection.apps.mil |
If the save fails
UTMStack signs in to Microsoft with the app and then lists the app's Management Activity API subscriptions. When either fails, the config group is not saved and a message starting with "credential verification failed:" explains why.
| Message | What to check |
|---|---|
| Invalid Client Secret. Please verify the Client Secret value (not the Secret ID) is correct and has not expired. | Paste the secret Value, not the Secret ID. If the secret expired, create a new one. |
| Invalid Client ID or Client Secret | The Client ID or the secret is wrong. |
| Client ID was not found in the tenant ... | The Client ID belongs to another tenant, or the Tenant ID is wrong. |
| Admin consent is required | Click Grant admin consent for your organization in API permissions. |
| Invalid Tenant ID ... | Copy the Directory (tenant) ID again from the app's Overview page. |
| The application does not have permission to access the Office 365 Management API (HTTP 403) | Add ActivityFeed.Read under Office 365 Management APIs > Application permissions and grant admin consent. |
| Office 365 Management API endpoint not found (HTTP 404) | The Tenant ID or the Cloud Environment value does not match your tenant. |
| Cannot connect to Microsoft login service / Cannot connect to the Office 365 Management API | The UTMStack server cannot reach Microsoft on port 443. |
Check that events arrive
- 1
Create some activity
Sign in to Outlook on the web or SharePoint with a test user, or change a setting in the Microsoft 365 admin center.
- 2
Open the logs in UTMStack
Open the O365 card again and click View logs. Log Explorer opens with the
o365data type for the last 24 hours. UTMStack asks Microsoft for new content every 5 minutes, but Microsoft itself publishes audit records with a delay. On a new connection, allow up to 12 hours for the first events. - 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.
Troubleshooting
Errors that happen after the config group is saved, for example an expired secret, 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 |
|---|---|---|
| The save fails | See If the save fails above. | Fix the value the message names. |
Saved, but no o365 events after 12 hours | Audit logging is off for the organization, so Microsoft has no content to return. | Turn on auditing (Step 3) and wait up to 60 minutes for the change, then up to 12 hours for content. |
| Events stopped after months of working | The client secret expired. | Create a new secret, then edit the config group and paste the new Value. |
| DLP events arrive without the matched sensitive data | The app has ActivityFeed.Read but not ActivityFeed.ReadDlp. | Add ActivityFeed.ReadDlp and grant admin consent. |
| Defender alerts, sign-in details or risk detections are missing | This integration reads the audit log only. | Add the Microsoft 365 through Microsoft Graph integration. |
| A government tenant does not connect | The Cloud Environment value is wrong. Any value other than GCC, GCCHigh or DoD is treated as the commercial cloud. | Type the value exactly as shown, with the same capital letters. |
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.