New: Microsoft 365 Management API collector [WIP]

Key considerations to include:

• Why should I enable it

• How do I enable it

• Once it is enabled, how do I use the data for security

Purpose

An analyst wants to detect <adjective> behavior in <data source>.  Using the Microsoft 365 API collector to send <type> to Devo, the analyst will find <outcome>.  As a result, the analyst will <verb> the <entity>, preventing  them from <tactic>.

Prerequisites

• Office 365 subscription

• Azure subscription associated with your Office 365 subscription.

Data sources

Authorize It

Register your application in Microsoft Entra ID

1. Register Devo application in Microsoft Entra ID from the Azure portal:

   1. Access Microsoft Entra ID(1) > App registration(2) > New registration(3). SCREENSHOT

   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.

SCREENSHOT

Configure application properties in Microsoft Entra ID

2. Configure the application properties in Microsoft Entra ID by defining:

   1. Client ID, generated during registration.

   2. Multi-tenant application (Tenant ID): Select YES to allow tenant admins to grant consent to your app to access their data.

   3. Reply URL: Define the URL for the tenant admins to be redirected after granting consent to the application, Azure will select the first URL defined (if multiple) to match the sign-on.

   4. Click “Save” button

Generate a new key for the application

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

4. Go to Client secrets to copy the client secret value to the clipboard.

SCREENSHOT

Configure X.509 certificate to enable service-to-service calls

5. Configure an X.509 certificate to be used as client credentials when requesting app-only access tokens from Microsoft Entra ID:

   1. Use a self-signed certificate or certificated issued publicly trusted certifcate authority.

   2. Modify your application manifest to include the thumbprint and public key of your certificate (export the public key to a base64-enconded file and update the manifest App registrations > All applications > Manifest)

Specify the permissions required to access the Office 365 Management APIs

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

7. On the Microsoft APIs tab, select Office 365 Management APIs.

8. Select the Application permissions type.

9. 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).

10. Select Grant admin consent for “tenant name“.

Get Office 365 tenant admin consent

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

Request access tokens from Microsoft Entra ID

12. After admin grants consent, the application receives an authorization code as a query string parameter and redirects to the designated URL.

    1. The application will make an HTTP REST POST to Entra ID to exchange the authorization code for an access token.

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

https://learn.microsoft.com/en-us/office/office-365-management-api/get-started-with-office-365-management-apis

Run It

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

{
  "inputs": {
    "sqs_collector": {
      "id": "<FIVE_UNIQUE_DIGITS>",
      "services": {
        "<SERVICE_NAME>": {}
      },
      "credentials": {
              "aws_cross_account_role": "arn:<PARTITION>:iam::<YOUR_AWS_ACCOUNT_NUMBER>:role/<YOUR_ROLE>",
              "aws_external_id": "<EXTERNAL_ID>"
      },
      "region": "<REGION>",
      "base_url": "https://sqs.<REGION>.amazonaws.com/<YOUR_AWS_ACCOUNT_NUMBER>/<QUEUE_NAME>"
    }
  }
}

Secure It

Monitor It

Create an inactivity alert to detect interruptions of transfer of data from the source to the SQS queue using the query

from TABLE 
where toktains(hostchain,"collector-") 
select split(hostchain,"-",1) as collector_id

Set the inactivity alert to keep track of the collector_id.