O365 Management API

Integration version: 9.0

Use Cases

Get activity events from Microsoft 365.

Configure O365 Management API to work with Google Security Operations SOAR

Product Permission

For more information, see 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.

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 Security Operations SOAR

For detailed instructions on how to configure an integration in Google Security Operations SOAR, see 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 Security Operations SOAR 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.

Actions

Ping

Description

Test connectivity to the O365 Management API service with parameters provided at the integration configuration page in the Google Security Operations Marketplace tab.

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!"

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)

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.

Parameters

Parameter Display Name Type Default Value Is Mandatory 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)

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 Security Operations SOAR

For detailed instructions on how to configure a connector in Google Security Operations SOAR, see Configuring the connector.

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

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 Security Operations SOAR 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 Security Operations SOAR 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 Security Operations SOAR 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.