New: Microsoft 365 Management API collector

Purpose

An analyst wants to detect malicious behavior in Microsoft 365 related tools. Using the Microsoft 365 API collector to send activity logs to Devo, the analyst will find unauthorized accesses to organization resources. As a result, the analyst will detect and neutralize intruders access attempts, preventing them from disrupting private network services.

Prerequisites

Office 365 subscription
Azure subscription associated with your Office 365 subscription.

Example Tables

Devo table	Description

Devo table	Description
`cloud.office365.management.azure_active_directory`	This table collects logs generated by the Microsoft Entra ID services.
`cloud.office365.management.sharepoint`	This table collects logs generated by the Sharepoint tool.
`cloud.office365.management.onedrive`	This table collects logs generated by the OneDrive service.
`cloud.office365.management.exchange`	This table collects logs generated by the Exchange email service.
`cloud.office365.management.*`	This union table allows perform general auditing over the tables whose 3 first levels fit with this one. Check the list of tables

Authorize It

Register your application in Microsoft Entra ID

Register Devo application in Microsoft Entra ID from the Azure portal:
1. Access Microsoft Entra ID(1) > App registration(2) > New registration(3).
2. On the Register an application page:
  1. Assign a name for the application. Ex: devo_integration
  2. Define application use and API access
  3. Redirect URI field can be left blank.
3. Click “Register” button.

Make note of the Client ID and Tenant ID generated during this registration process.

20_Microsoft 365 Management API Collector.png

Generate a new key for the application

To exchange an authorization code for an access tokens you need to generate keys (client_secrets):
1. Access Azure portal Microsoft Entra ID > App registrations > Application
2. Upload certificates⁽¹⁾ and create a new key⁽²⁾by accessing Certificates & secrets⁽³⁾> New client secret⁽⁴⁾specifying the key description and duration⁽⁵⁾.
3. Click “Add” button⁽⁶⁾.
Go to Client secrets^(7-8) to copy the client secret value to the clipboard⁽⁹⁾.

Specify the permissions required to access the Office 365 Management APIs

From Azure portal, go to App registrations>All applications select the application and the API permissions>Add a permission to display the Request API permission.
On the Microsoft APIs tab, select Office 365 Management APIs.
Select the Application permissions type.
Enable permissions:
1. Read activity data from your organization.
2. Read service health information from your organization.
3. Read DLP policy events including detected sensitive data (only if pulling DLP.All from Management Activity).
Select Add permissions.

Get Office 365 tenant admin consent

The tenant admin must sign in to Microsoft Entra ID by using the following specially constructed URL, to review the application's requested permissions. This step is not required when using the APIs to access data from your own tenant.
HTTP
https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fmanage.office.com&client_id={your_client_id}&redirect_uri={your_redirect_url }
The redirect URL must match or be a sub-path under one of the Reply URLs configured for your application in Microsoft Entra ID.
Accept and use the authorization code from the page to access and store the Tenant ID.

http://www.mycompany.com/myapp/?code=AAABAAAAvPM1KaPlrEqdFSB...

Request access tokens from Microsoft Entra ID

After admin grants consent, the application receives an authorization code as a query string parameter and redirects to the designated URL.
The application will make an HTTP REST POST to Entra ID to exchange the authorization code for an access token.
The access token return a JWT token. Extract the tenant ID “tid“ fromt the token an store to be used ro request additional access tokens.

Request an access token by using client credentials

Now, you can make service-to-service calls which require using an X.509 certificate to create client assertion in the form of a base64-encoded, SHA256 signed JWT bearer token (See JSON example).

HEADER:

{
  "alg": "RS256",
  "x5t": "{thumbprint of your X.509 certificate used to sign the token",
}

PAYLOAD:

{
  "aud": "https://login.windows.net/{tenantid}/oauth2/token",
  "iss": "{your app client ID}",
  "sub": "{your app client ID}",
  "jti": "{random GUID}",
  "nbf": "{epoch time, before which the token is not valid}",
  "exp": "{epoch time, after which the token is not valid}"
}

Run It

In the Cloud Collector App, create a Microsoft 365 collector instance using this parameters template, replacing the values enclosed in < >.

Secure It

Microsoft 365 logs work with these Exchange Activeboards:

Devo provides compatible Alert packs:

Monitor It

Create an each alert to detect interruptions of transfer of data from the source to the Microsoft 365 Management API using the query

Set the each alert to keep track of the messages_unsuccessfully_processed ever 5n minutes.

Devo Additional Documentation