Azure AD Identity Protection

Integration version: 3.0

Use cases

Enrich entities.
Ingest alerts.

Prerequisites

Before configuring the integration in the Google Security Operations SOAR platform, make sure to complete the following prerequisite steps:

Create the Microsoft Entra app.
Configure the API permissions for your app.
Create a client secret.

Create Microsoft Entra app

Sign in to the Azure portal as a user administrator or a password administrator.
Select Microsoft Entra ID.
Go to App registrations > New registration.
Enter the name of the app.
Click Register.
Save the Application (client) ID and Directory (tenant) ID values to use them later when configuring the integration parameters.

Configure API permissions

Go to API Permissions > Add a permission.
Select Microsoft Graph.
In the Select Permissions section, select the following permissions:
- IdentityRiskEvent.Read.All
- IdentityRiskyUser.ReadWrite.All
Click Add permissions.
Click Grant admin consent for YOUR_ORGANIZATION_NAME.

When the Grant admin consent confirmation dialog appears, click Yes.

Create client secret

Navigate to Certificates and secrets > New client secret.
Provide a description for a client secret and set its expiration deadline.
Click Add.
Save the value of the client secret (not the secret ID) to use it as the Client Secret parameter value when configuring the integration. The client secret value is only displayed once.

Integrate Azure AD Identity Protection with 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
API Root	String	https://graph.microsoft.com	Yes	API root of the Microsoft Entra ID Protection instance.
Tenant ID	String	N/A	Yes	Tenant ID of the Microsoft Entra ID Protection account.
Client ID	String	N/A	Yes	Client ID of the Microsoft Entra ID Protection account.
Client Secret	Password	N/A	Yes	Client Secret of the Microsoft Entra ID Protection account.
Verify SSL	Checkbox	Checked	Yes	If enabled, verifies that the SSL certificate for the connection to the Microsoft Entra ID Protection server is valid.

Actions

Ping

Test connectivity to Microsoft Entra ID Protection with parameters provided at the integration configuration page in the Google Security Operations Marketplace tab.

Parameters

N/A

Run On

The action doesn't run on entities, nor has mandatory input parameters.

Action Results

Script Result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

Case Wall

Result type	Value/Description	Type (Entity \ General)
Output message*	The action should not fail nor stop a playbook execution: If successful: "Successfully connected to the Azure AD Identity Protection server with the provided connection parameters!" The action should fail and stop a playbook execution: If not successful: "Failed to connect to the Azure AD Identity Protection server! Error is {0}".format(exception.stacktrace)	General

Result type

Value/Description

Type (Entity \ General)

Output message*

The action should not fail nor stop a playbook execution:

If successful: "Successfully connected to the Azure AD Identity Protection server with the provided connection parameters!"

The action should fail and stop a playbook execution:

If not successful: "Failed to connect to the Azure AD Identity Protection server! Error is {0}".format(exception.stacktrace)

General

Enrich Entities

Enrich entities using information from Microsoft Entra ID Protection. Supported entities: Username, Email Address (user entity that matches email regular expression pattern).

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Create Insight	Checkbox	Checked	No	If enabled, the action creates an insight containing all of the retrieved information about the entity.

Run On

This action runs on the Username entity.

Action Results

Script Result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON Result

{
    "id": "2600d017-84a1-444f-94ba-4bebed30b09e",
    "isDeleted": false,
    "isProcessing": false,
    "riskLevel": "none",
    "riskState": "remediated",
    "riskDetail": "userPerformedSecuredPasswordChange",
    "riskLastUpdatedDateTime": "2021-09-02T14:10:48Z",
    "userDisplayName": "user_1",
    "userPrincipalName": "user_1@example.com"
}

Entity Enrichment

Enrichment Field Name	Logic - When to apply
is_deleted	When available in JSON
is_processing	When available in JSON
risk_level	When available in JSON
risk_state	When available in JSON
risk_detail	When available in JSON
risk_updated	When available in JSON
display_name	When available in JSON
principal_name	When available in JSON

Case Wall

Result type	Value/Description	Type (Entity \ General)
Output message*	The action should not fail nor stop a playbook execution: If data is available for one entity (is_success=true): "Successfully enriched the following entities using information from Azure AD Identity Protection: {entity.identifier}". If data is not available for one entity (is_success=true): "Action wasn't able to enrich the following entities using information from Azure AD Identity Protection: {entity.identifier}". If data is not available for all entities (is_success=false): "None of the provided entities were enriched." The action should fail and stop a playbook execution: If a fatal error, like wrong credentials, no connection to the server, other is reported: "Error executing action "Enrich Entities". Reason: {0}''.format(error.Stacktrace)	General
Case Wall Table	Table Name: {entity.identifier} Table Columns: Key Value	Entity

Result type

Value/Description

Type (Entity \ General)

Output message*

The action should not fail nor stop a playbook execution:

If data is available for one entity (is_success=true): "Successfully enriched the following entities using information from Azure AD Identity Protection: {entity.identifier}".

If data is not available for one entity (is_success=true): "Action wasn't able to enrich the following entities using information from Azure AD Identity Protection: {entity.identifier}".

If data is not available for all entities (is_success=false): "None of the provided entities were enriched."

The action should fail and stop a playbook execution:

If a fatal error, like wrong credentials, no connection to the server, other is reported: "Error executing action "Enrich Entities". Reason: {0}''.format(error.Stacktrace)

General

Case Wall Table

Table Name: {entity.identifier}

Table Columns:

Key
Value

Entity

Update User State

Update state of the user in Microsoft Entra ID Protection. Supported entities: Username, Email Address (user entity that matches email regular expression pattern).

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
State	DDL	Compromised Possible Values: Compromised Dismissed	No	Specify the state for the users.

Parameter Display Name

Type

Default Value

Is Mandatory

Description

State

DDL

Compromised

Possible Values:

Compromised
Dismissed

Specify the state for the users.

Run On

This action runs on the Username entity.

Action Results

Script Result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

Case Wall

Result type	Value/Description	Type (Entity \ General)
Output message*	The action should not fail nor stop a playbook execution: If the 204 status code is reported for one user (is_success=true): "Successfully updated the state of the following users in Azure AD Identity Protection: {entity identifier}". If one user is not found (is_success=true): "The following users were not found in Azure AD Identity Protection:"{entity.identifier}" If all users are not found (is_success=true): "None of the provided users were not found in Azure AD Identity Protection." The action should fail and stop a playbook execution: If a fatal error, like wrong credentials, no connection to the server, other is reported: "Error executing action "Update User State". Reason: {0}''.format(error.Stacktrace)'	General

Result type

Value/Description

Type (Entity \ General)

Output message*

The action should not fail nor stop a playbook execution:

If the 204 status code is reported for one user (is_success=true): "Successfully updated the state of the following users in Azure AD Identity Protection: {entity identifier}".

If one user is not found (is_success=true): "The following users were not found in Azure AD Identity Protection:"{entity.identifier}"

If all users are not found (is_success=true): "None of the provided users were not found in Azure AD Identity Protection."

The action should fail and stop a playbook execution:

If a fatal error, like wrong credentials, no connection to the server, other is reported: "Error executing action "Update User State". Reason: {0}''.format(error.Stacktrace)'

General

Connectors

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

Azure AD Identity Protection - Risk Detections Connector

Pull information about risk detections from Microsoft Entra ID Protection.

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	riskEventType	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.
PythonProcessTimeout	Integer	180	Yes	Timeout limit for the python process running the current script.
API Root	String	https://graph.microsoft.com	Yes	API root of the Microsoft Entra ID Protection instance.
Tenant ID	String	N/A	Yes	Tenant ID of the Microsoft Entra ID Protection account.
Client ID	String	N/A	Yes	Client ID of the Microsoft Entra ID Protection account.
Client Secret	Password	N/A	Yes	Client Secret of the Microsoft Entra ID Protection account.
Lowest Risk Level To Fetch	String	N/A	No	The lowest risk that needs to be used to fetch alerts. Possible values: Low, Medium, High. If nothing is specified, the connector ingests risk detections with all risk levels.
Max Hours Backwards	Integer	1	No	The number of hours for which risk detections should be fetched.
Max Alerts To Fetch	Integer	100	No	The number of alerts to process per one connector iteration.
Use whitelist as a blacklist	Checkbox	Unchecked	Yes	If enabled, dynamic list is used as a blocklist.
Verify SSL	Checkbox	Checked	Yes	If enabled, verifies that the SSL certificate for the connection to the Microsoft Entra ID Protection server is valid.
Proxy Server Address	String	N/A	No	The address of the proxy server to use.
Proxy Username	String	N/A	No	The proxy username to authenticate with.
Proxy Password	Password	N/A	No	The proxy password to authenticate with.

Connector rules

The connector supports proxy.