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.

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.

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.

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 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 configuration parameters
• Office 365 Management API Audit General Events Connector configuration 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 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.