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

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

   2. SCREENSHOT

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

   4. 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^(7-8) to copy the client secret value to the clipboard⁽⁹⁾.

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 }
    

12. The redirect URL must match or be a sub-path under one of the Reply URLs configured for your application in Microsoft Entra ID.

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

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

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

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

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

  {
  "inputs": {
    "office365": {
      "id": "<short_unique_id",
      "enabled": true,
      "credentials": {
        "client_id": "<client_id_value>",
        "tenant_id": "<tenant_id_value>",
        "client_secret": "<secret_value>"
      },
    "services": {
      "azure_active_directory": {
          "start_time_in_utc": "<start_time_in_utc_value>",
          "override_tag": "<override_tag_value>",
          "override_bloom_filter_size": "<override_bloom_filter_size_value>",
          "override_bloom_filter_buffer_size": "<override_bloom_filter_buffer_size_value>"
        },
    }
   } 
  }
 }  
}

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

from devo.collectors.out 
where toktains(msg,"collector failed Connection closed by server."), 
toktains(collector_image,"office365") 
group every 5m by collector_name, job_id 
select count() as messages_unsuccessfully_processed

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