# O365 Management API

This document provides guidance on how to integrate O365 Management API with
Google SecOps.

## Use Cases

Get activity events from Microsoft 365.

## Configure O365 Management API to work with Google Security Operations

### Product Permission

For more information, see
[Get started with Office 365 Management APIs](https://docs.microsoft.com/en-us/office/office-365-management-api/get-started-with-office-365-management-apis).

Before you can access data through the Office 365 Management Activity APIs, you
must enable unified audit logging for your Office 365 organization. You do this
by turning on the Office 365 audit log. For instructions, see [Turn auditing on or off](https://docs.microsoft.com/en-us/office365/securitycompliance/turn-audit-log-search-on-or-off).

As for account configuration, procedure is similar to other Azure-based products
(Defender, Sentinel etc). You need to register an app in Azure Active
Directory and give it the following permissions:

- Delegated `User.Read` permissions from Microsoft Graph
- Application `ActivityFeed.ReadDlp` permissions from Office 365 Management Activity APIs

## Configure O365 Management API integration in Google SecOps

For detailed instructions on how to configure an integration in
Google SecOps, see [Configure
integrations](https://docs.cloud.google.com/chronicle/docs/soar/respond/integrations-setup/configure-integrations).

### Integration parameters

Use the following parameters to configure the integration:

| Parameter Display Name | Type | Default Value | Is Mandatory | Description |
|---|---|---|---|---|
| Instance Name | String | N/A | No | Name of the Instance you intend to configure integration for. |
| Description | String | N/A | No | Description of the Instance. |
| Api Root | String | https://manage.office.com | Yes | Api root url to use with integration. |
| Azure Active Directory ID | String | N/A | Yes | Azure Active Directory Tenant ID, can be viewed in Active Directory \> App Registration \> \<Application you configured for your integration\> Directory (tenant) ID. Example: k48f52ca-0000-4708-8ed0-0000a20a40a |
| Client ID | String | N/A | Yes | Client (Application) ID that was added for the app registration in Azure Active Directory for this integration. Eg, 29bf818e-0000-0000-0000-784fb644178d |
| Client Secret | Password | N/A | No | Secret that was entered for Azure AD app registration. Example: XF00000Qc0000000\[UZSW7-0?qXb6Qx\] |
| Verify SSL | Checkbox | Checked | Yes | Specify whether remote API endpoint SSL certificate should be validated. |
| Run Remotely | Checkbox | Unchecked | No | Check the field in order to run the configured integration remotely. Once checked, the option appears to select the remote user (agent). |
| Certificate Path | String | N/A | No | If authentication based on certificates is used instead of client secret, specify path to the certificate on Google SecOps server. |
| Certificate Password | Password | N/A | No | Optional, if certificate is password-protected, specify the password to open the certificate file. |
| OAUTH2 Login Endpoint Url | String | https://login.microsoftonline.com | Yes | Specify the URL connector that should be used for OAUTH2 Login Endpoint Url. |

> [!NOTE]
> **Note:** You can make changes at a later stage if needed. Once configured, the Instances can be used in Playbooks. For detailed information on configuring and supporting multiple instances, please see [Supporting multiple instances](https://docs.cloud.google.com/chronicle/docs/soar/respond/integrations-setup/supporting-multiple-instances).

## Actions

### Ping

#### Description

Test connectivity to the O365 Management API service with parameters provided at
the integration configuration page in the Google SecOps Content Hub page.

#### Parameters

N/A

#### Run On

This action runs on all entities.

#### Action Results

##### Script Result

| **Script Result Name** | **Value Options** | **Example** |
|---|---|---|
| success | True/False | success:False |

##### Case Wall

| Result Type | Value / Description | Type |
|---|---|---|
| Output message\* | **The action should not fail nor stop a playbook execution:** - if successful: print "Successfully connected to the O365 Management API with the provided connection parameters!" <br /> **The action should fail and stop a playbook execution:** - if critical error, like wrong credentials or lost connectivity: print "Failed to connect to the O365 Management API! Error is {0}".format(exception.stacktrace) | General |

### Start a Subscription

#### Description

Start a subscription to a chosen Office 365 Management API content type.

#### Parameters

| Parameter Display Name | Type | Default Value | Is Mandatory | Description |
|---|---|---|---|---|
| Start a Subscription for | DDL | Select content type, Audit.General | Yes | Specify for which content type to start a subscription. |

#### Run On

This action runs on all entities.

#### Action Results

##### Script Result

| **Script Result Name** | **Value Options** | **Example** |
|---|---|---|
| is_success | True/False | is_success:False |

##### Case Wall

| Result Type | Value / Description | Type |
|---|---|---|
| Output message\* | **The action should not fail nor stop a playbook execution:** - if successful: print "Successfully created O365 Management API subscription for the {0} content type!".format(content_type) <br /> **The action should fail and stop a playbook execution:** - if critical error, like wrong credentials or lost connectivity: print "Failed to execute command! Error is {0}".format(exception.stacktrace) | General |

### Stop a Subscription

#### Description

Stop a subscription to a chosen Office 365 Management API content type.

> [!NOTE]
> **Note:** When a subscription is stopped, you will no longer receive notifications and you will not be able to retrieve available content. If the subscription is later restarted, you will have access to new content from that point forward. You will not be able to retrieve content that was available between the time the subscription was stopped and restarted.

#### Parameters

| Parameter Display Name | Type | Default Value | Is **M**andatory | Description |
|---|---|---|---|---|
| Stop a Subscription for | DDL | Select content type, Audit.General | Yes | Specify for which content type to stop a subscription. |

#### Run On

This action doesn't run on entities.

#### Action Results

##### Script Result

| **Script Result Name** | **Value Options** | **Example** |
|---|---|---|
| is_success | True/False | is_success:False |

##### Case Wall

| Result Type | Value / Description | Type |
|---|---|---|
| Output message\* | **The action should not fail nor stop a playbook execution:** - if successful: print "Successfully stopped O365 Management API subscription for the {0} content type!".format(content_type) <br /> **The action should fail and stop a playbook execution:** - if critical error, like wrong credentials or lost connectivity: print "Failed to connect to execute command! Error is {0}".format(exception.stacktrace) | General |

## Connectors

### Configure Office 365 Management API connectors in Google SecOps

For detailed instructions on how to configure a connector in
Google SecOps, see [Configuring the
connector](https://docs.cloud.google.com/chronicle/docs/soar/ingest/connectors/ingest-your-data-connectors).

To configure the selected connector use the connector-specific parameters listed
in the following tables:

- [Office 365 Management API DLP Events Connector configuration parameters](https://docs.cloud.google.com/chronicle/docs/soar/marketplace-integrations/ms-o365#office-dlp-events-connector-parameters)
- [Office 365 Management API Audit General Events Connector configuration
  parameters](https://docs.cloud.google.com/chronicle/docs/soar/marketplace-integrations/ms-o365#office-audit-general-events-connector-parameters)

### Office 365 Management API DLP Events Connector

#### Description

Fetch DLP events from Office 365 Management API.

#### Connector parameters

Use the following parameters to configure the connector:

| Parameter Display Name | Type | Default Value | Is Mandatory | Description |
|---|---|---|---|---|
| Product Field Name | String | Product Name | Yes | Enter the source field name in order to retrieve the Product Field name. |
| Event Field Name | String | Operation | Yes | Enter the source field name in order to retrieve the Event Field name. |
| Environment Field Name | String | "" | No | Describes the name of the field where the environment name is stored. If the environment field isn't found, the environment is the default environment. |
| Environment Regex Pattern | String | .\* | No | A regex pattern to run on the value found in the "Environment Field Name" field. Default is .\* to catch all and return the value unchanged. Used to allow the user to manipulate the environment field via regex logic. If the regex pattern is null or empty, or the environment value is null, the final environment result is the default environment. |
| Script Timeout (Seconds) | Integer | 180 | Yes | Timeout limit for the python process running the current script. |
| Api Root | String | https://manage.office.com | Yes | Api root url to use with integration. |
| Azure Active Directory ID | String | N/A | Yes | Azure Active Directory Tenant ID, can be viewed in Active Directory \> App Registration \> \<Application you configured for your integration\> Directory (tenant) ID. Example: k48f52ca-0000-4708-8ed0-0000a20a40a |
| Client ID | String | N/A | Yes | Client (Application) ID that was added for the app registration in Azure Active Directory for this integration. Example: 29bf818e-0000-0000-0000-784fb644178d |
| Client Secret | Password | N/A | No | Secret that was entered for Azure AD app registration. Example: XF00000Qc0000000\[UZSW7-0?qXb6Qx\] |
| Verify SSL | Checkbox | Checked | Yes | Specify whether remote API endpoint SSL certificate should be validated. |
| Type of Operation Filter | String | N/A | No | The following operation types are available for DLP events: DlpRuleMatch, DlpRuleUndo, DlpInfo. Parameter works as a blacklist. By default if nothing is specified in this parameter - ingest all possible operation types. If operation type is specified in this parameter - event with this operation type will not be ingested. Parameter accepts multiple values as a comma separated string. |
| Type of Policy Filter | String | N/A | No | Parameter can be used to specify policy name that if present in event, event will not be ingested. Parameter works as a blacklist. By default if nothing is specified - ingest all possible policy types. Parameter accepts multiple values as a comma separated string. |
| Mask findings? | Checkbox | Unchecked | No | Specify whether the connector should mask sensitive findings that triggered DLP policies hits. |
| Max events to fetch | Integer | 50 | Yes | How many events to process per one connector iteration. |
| Fetch Max Hours Backwards | Integer | 8 | Yes | Amount of hours from where to fetch events. Note that O365 Management API allows to return events for the last 7 days, not older. |
| Fetch Backwards Time Interval (minutes) | Integer | 240 | Yes | Time interval connector should use to fetch events from max hours backwards. If O365 tenant is busy, it could return a lot of event blobs. Because of this, this parameter in minutes can be used to split max hours backwards on smaller segments and process them individually. Time interval can't be bigger than 24 hours in total. |
| Events Padding Period (minutes) | Integer | 60 | Yes | Event Padding Period in minutes specifies a minimum time interval that will be used by connector to check new events. |
| Use whitelist as a blacklist | Checkbox | Unchecked | Yes | If enabled, whitelist will be used as a blacklist. |
| Proxy Server Address | String |   | No | The address of the proxy server to use. |
| Proxy Username | String |   | No | The proxy username to authenticate with. |
| Proxy Password | Password |   | No | The proxy password to authenticate with. |
| Certificate Path | String |   | No | If authentication based on certificates is used instead of client secret, specify path to the certificate on Google SecOps server. |
| Certificate Password | Password |   | No | Optional, if certificate is password-protected, specify the password to open the certificate file. |
| OAUTH2 Login Endpoint Url | String | https://login.microsoftonline.com | Yes | Specify the url connector should use for OAUTH2 Login Endpoint Url |

#### Connector rules

##### Whitelist / Blacklist

The connector has whitelist/blacklist support.

##### Proxy support

The connector supports proxy.

### Office 365 Management API Audit General Events Connector

#### Description

Fetch Audit.General events from Office 365 Management API. Please make sure that
first you enabled subscription for Audit.General events by running "Start a
Subscription" action.

For Office 365 Management API Audit General Events Connector the following
permissions are required:

- Delegated `User.Read`, `email`, and `profile` permissions from Microsoft Graph
- Application `ActivityFeed.ReadDlp` and `ActivityFeed.Read` permissions from Office 365 Management Activity APIs

#### Connector parameters

Use the following parameters to configure the connector:

| Parameter Display Name | Type | Default Value | Is Mandatory | Description |
|---|---|---|---|---|
| Product Field Name | String | Product Name | Yes | Enter the source field name in order to retrieve the Product Field name. |
| Event Field Name | String | Operation | Yes | Enter the source field name in order to retrieve the Event Field name. |
| Environment Field Name | String | "" | No | Describes the name of the field where the environment name is stored. If the environment field isn't found, the environment is the default environment. |
| Environment Regex Pattern | String | .\* | No | A regex pattern to run on the value found in the "Environment Field Name" field. Default is .\* to catch all and return the value unchanged. Used to allow the user to manipulate the environment field via regex logic. If the regex pattern is null or empty, or the environment value is null, the final environment result is the default environment. |
| Script Timeout (Seconds) | Integer | 180 | Yes | Timeout limit for the python process running the current script. |
| Api Root | String | https://manage.office.com | Yes | Api root url to use with integration. |
| Azure Active Directory ID | String | N/A | Yes | Azure Active Directory Tenant ID, can be viewed in Active Directory \> App Registration \> \<Application you configured for your integration\> Directory (tenant) ID. Example: k48f52ca-0000-4708-8ed0-0000a20a40a |
| Client ID | String | N/A | Yes | Client (Application) ID that was added for the app registration in Azure Active Directory for this integration. Example: 29bf818e-0000-0000-0000-784fb644178d |
| Client Secret | Password | N/A | No | Secret that was entered for Azure AD app registration. Example: XF00000Qc0000000\[UZSW7-0?qXb6Qx\] |
| Certificate Path | String | N/A | No | If authentication based on certificates is used instead of client secret, specify path to the certificate on Google SecOps server. |
| Certificate Password | Pasword | N/A | No | Optional, if certificate is password-protected, specify the password to open the certificate file. |
| OAUTH2 Login Endpoint Url | String | https://login.microsoftonline.com | No | Specify the url connector should use for OAUTH2 Login Endpoint Url |
| Verify SSL | Checkbox | Checked | Yes | Specify whether remote API endpoint SSL certificate should be validated. |
| Type of Operation Filter | String | N/A | No | In audit.general schema there could be different operation types:SearchAirBatch, SearchCustomTag and so on. By default if nothing is specified in this parameter - ingest all possible operation types. If operation type is specified in this parameter - event with this operation type will not be ingested. Parameter accepts multiple values as a comma separated string. |
| Status Filter | String | N/A | No | Parameter can be used to specify status that if present in event, event will not be ingested. Parameter works as a blacklist. By default if nothing is specified - ingest all possible status types. Parameter accepts multiple values as a comma separated string. |
| Use operation and status filters as whitelist | Checkbox | Unchecked | Yes | If enabled, operation and status filters will work as a whitelist, by default it's a blacklist. |
| Entity Keys to Create Additional Events | CSV | N/A | No | Specify keys that if seen in the Audit.General entities section of data, related subsection should be taken to create an additional Google SecOps event. |
| Max events to fetch | Integer | 50 | Yes | How many events to process per one connector iteration. |
| Fetch Max Hours Backwards | Integer | 8 | Yes | Amount of hours from where to fetch events. Note that O365 Management API allows to return events for the last 7 days, not older. |
| Fetch Backwards Time Interval (minutes) | Integer | 240 | Yes | Time interval connector should use to fetch events from max hours backwards. If O365 tenant is busy, it could return a lot of event blobs. Because of this, this parameter in minutes can be used to split max hours backwards on smaller segments and process them individually. Time interval can't be bigger than 24 hours in total. |
| Events Padding Period (minutes) | Integer | 60 | Yes | Event Padding Period in minutes specifies a minimum time interval that will be used by connector to check new events. |
| Use whitelist as a blacklist | Checkbox | Unchecked | Yes | If enabled, whitelist will be used as a blacklist. |
| Proxy Server Address | String |   | No | The address of the proxy server to use. |
| Proxy Username | String |   | No | The proxy username to authenticate with. |
| Proxy Password | Password |   | No | The proxy password to authenticate with. |

#### Connector rules

##### Whitelist / Blacklist

The connector has whitelist/blacklist support.

##### Proxy support

The connector supports proxy.

**Need more help?** [Get answers from Community members and Google SecOps professionals.](https://security.googlecloudcommunity.com/)