Cloud and SaaSMicrosoft 365 (Office 365 Management Activity API)

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.SharePoint and DLP.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 o365 and parsed by the shipped pipeline office365/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.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.

    Office365
  2. 2

    Go to App registrations

    In the left menu, click App registrations.

    Office365
  3. 3

    Register a new app

    Click New registration. Name it UTMStack O365 Agent, select Accounts in this organizational directory only (Single tenant) and click Register.

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

    Office365

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

Step 2: Add the API permissions

  1. 1

    Add Office 365 Management API permissions

    In the same app, go to API permissions > Add a permission and search for Office 365 Management APIs.

    Office365
  2. 2

    Grant the ActivityFeed permissions

    Select Application permissions and add ActivityFeed.Read and ActivityFeed.ReadDlp. Click Grant admin consent for your organization and confirm.

    Office365
  3. 3

    Add Microsoft Graph permissions

    Back in Add a permission, click Microsoft Graph.

    Office365
  4. 4

    Add the delegated SecurityAlert permissions

    Select Delegated permissions and add SecurityAlert.Read.All and SecurityAlert.ReadWrite.All. Click Grant admin consent for your organization and confirm.

    Office365
  5. 5

    Add the application SecurityAlert permissions

    Select Application permissions and add SecurityAlert.Read.All and SecurityAlert.ReadWrite.All. Click Grant admin consent for your organization and confirm.

    Office365

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.

  1. Sign in to the Microsoft Purview portal and open the Audit solution.

  2. If auditing is not turned on, a banner asks you to start recording user and admin activity. Select it.

  3. 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 $true

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

Office365

Step 5: Connect Microsoft 365 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 O365 and open the O365 card. The form is at the end of the setup guide, under Connect your Microsoft 365 tenant.

    O365 setup guide in UTMStack, showing How it works and the first app registration step: open Microsoft Entra ID

    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. 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 4.
    Client ID (Application ID)The Application (client) ID from Step 4.
    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 checks the credentials by signing in to Microsoft before it saves them. When the check passes, you see "Config group created successfully."

Cloud Environment valueSign-in addressManagement API address
(empty) or Commerciallogin.microsoftonline.commanage.office.com
GCClogin.microsoftonline.commanage-gcc.office.com
GCCHighlogin.microsoftonline.usmanage.office365.us
DoDlogin.microsoftonline.usmanage.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.

MessageWhat 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 SecretThe 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 requiredClick 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 APIThe UTMStack server cannot reach Microsoft on port 443.

Check that events arrive

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

    Open the logs in UTMStack

    Open the O365 card again and click View logs. Log Explorer opens with the o365 data 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. 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.

SymptomLikely causeFix
The save failsSee If the save fails above.Fix the value the message names.
Saved, but no o365 events after 12 hoursAudit 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 workingThe client secret expired.Create a new secret, then edit the config group and paste the new Value.
DLP events arrive without the matched sensitive dataThe app has ActivityFeed.Read but not ActivityFeed.ReadDlp.Add ActivityFeed.ReadDlp and grant admin consent.
Defender alerts, sign-in details or risk detections are missingThis integration reads the audit log only.Add the Microsoft 365 through Microsoft Graph integration.
A government tenant does not connectThe 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.