# Integrate Microsoft Entra ID with
Google SecOps

This document provides guidance on how to integrate Microsoft Entra ID with
Google Security Operations.

This integration uses one or more open source components.
You can download a zipped copy of the full source code of this integration from
the [Cloud Storage
bucket](https://storage.googleapis.com/csoar_public_integrations/AzureActiveDirectory.zip).

> [!NOTE]
> **Note:** Azure Active Directory was renamed to Microsoft Entra ID. In the Google SecOps platform, the integration for Microsoft Entra ID is called *Azure Active Directory*.

## Use cases

Integrating Microsoft Entra ID with Google SecOps can
help you solve the following use cases:

- **User account management:** Automate the disabling and enabling of user accounts in
  Microsoft Entra ID based on security events, such as suspected compromise or
  employee offboarding.

- **Password reset:** Orchestrate password resets for compromised accounts or users locked out of
  their accounts. Resetting passwords can help you streamline the password
  recovery process and reduce help desk tickets.

- **Group management:** Automate creating, modificating, and deleting Microsoft
  Entra ID groups.

- **Conditional access policy enforcement:** Use Microsoft Entra ID
  conditional access policies within Google SecOps playbooks to
  dynamically control access based on context and allow for granular control
  over access to resources based on factors like location, device, and user
  risk.

- **Security alerting and incident response:** Integrate Microsoft Entra ID
  security alerts into Google SecOps to automate incident
  response workflows.

## Before you begin

Before you configure the integration in Google SecOps, verify
that you meet the following requirements in your Microsoft environment:

- **Azure App Registration** : Register an application in the Microsoft Entra
  administrator center to obtain a **Client ID** and **Tenant ID** . For detailed
  instructions, see
  [Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).

- **API permissions and role assignments** : Grant the required
  [Microsoft Graph permissions or Microsoft Entra roles](https://docs.cloud.google.com/chronicle/docs/soar/marketplace-integrations/azure-ad.md.txt#api-permissions) based
  on the actions you plan to run and whether you require tenant-wide or
  [scoped access boundaries](https://docs.cloud.google.com/chronicle/docs/soar/marketplace-integrations/azure-ad.md.txt#permission-scoping).

- **Client secret** : Generate a client secret in the **Certificates \& secrets**
  section of your registered application. Copy the secret **Value** (not the
  **Secret ID**) immediately as Microsoft Entra ID only displays it once.

### Configure API permissions

Grant only the Microsoft Graph application permissions required for your
deployment model and grant administrator consent. For instructions, see the
Microsoft documentation to
[configure application permissions](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-configure-app-access-web-apis).

- **Read-only actions (all deployments)** : Grant `Directory.Read.All`.
- **Tenant-wide write actions (default)** : Grant the **Tenant-wide access** Microsoft Graph application permissions from the following table for the write actions you plan to run.
- **Scoped write actions (restricted to specific users or groups)** : Grant **only** the read permissions (`Directory.Read.All`, and optionally `AuditLog.Read.All`). Don't grant write application permissions. Instead, assign the **Scoped access** directory roles from the following table using an [Administrative Unit](https://docs.cloud.google.com/chronicle/docs/soar/marketplace-integrations/azure-ad.md.txt#permission-scoping).

| Capability and actions | Tenant-wide access (Microsoft Graph application permission) | Scoped access (Microsoft Entra directory role) |
|---|---|---|
| **Base directory read and enrichment** *(Required for all actions)* **Ping** , **Enrich User** , **Enrich Host** , **Get Manager Contact Details** , **Is User in Group** , **List Groups** , **List Members in the Group** , **List User's Groups Membership** , and **List Users** | `Directory.Read.All` (or `User.Read.All`, `GroupMember.Read.All`, and `Device.Read.All`) | Requires `Directory.Read.All` (or the `Directory Readers` role) at the **tenant** scope to resolve directory objects. |
| **MFA and sign-in enrichment** *(Optional)* Required only when enabling `Include MFA Details` or `Include Last Sign In Details` in **Enrich User** or **Get Manager Contact Details** | `AuditLog.Read.All` | Requires `AuditLog.Read.All` at the **tenant** scope. |
| **Account status management** **Disable Account** and **Enable Account** | `User.EnableDisableAccount.All` (or `User.ReadWrite.All`) | `Helpdesk Administrator` or `User Administrator`. |
| **Password management** **Force Password Update** and **Reset User Password** | `User-PasswordProfile.ReadWrite.All` **and** the `Password Administrator` directory role | `Password Administrator`, `Helpdesk Administrator`, or `User Administrator`. |
| **Session revocation** **Revoke User Session** | `User.RevokeSessions.All` (or `User.ReadWrite.All`) | `Authentication Administrator` or `User Administrator`. |
| **Group membership management** **Add User to a Group** and **Remove User from the Group** | `GroupMember.ReadWrite.All` (or `Group.ReadWrite.All`) | `Groups Administrator` or `User Administrator` (the Administrative Unit must contain the target groups). |

> [!NOTE]
> **Note:** No action in this integration requires `Directory.ReadWrite.All`. Avoid granting it to minimize tenant-wide privilege exposure.

#### Assign a tenant-wide role for password actions

If you use tenant-wide Microsoft Graph permissions and plan to run **Force
Password Update** or **Reset User Password** , you must also assign the
`Password Administrator` directory role to your registered application at the
tenant scope. For instructions, see the Microsoft documentation to
[assign Microsoft Entra roles](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/manage-roles-portal).

### Permission scoping and access boundaries

Google SecOps authenticates to Microsoft Graph using the OAuth
2.0 client credentials flow and doesn't filter actions by group or
organizational unit after authentication. Microsoft Entra ID enforces all
access boundaries directly:

- **`.All` application permissions are always tenant-wide** : Microsoft Graph application permissions ending in `.All` (such as `User.ReadWrite.All` or `Group.ReadWrite.All`) grant access across the entire tenant and can't be scoped to a specific group or Administrative Unit.
- **Enterprise Application user assignment doesn't restrict API scope** : Enabling **Assignment required** or assigning users and groups to an Enterprise Application only controls interactive user sign-ins. It doesn't restrict which directory objects the application's service principal can modify through Microsoft Graph.

#### Restrict write actions using an Administrative Unit

Complete these steps **only if** you want to restrict write actions to a
specific subset of users or groups instead of the entire tenant:

1. **Grant only read application permissions** : Grant only `Directory.Read.All` (and optionally `AuditLog.Read.All`) to your application registration. Remove any write `.All` application permissions (such as `User.ReadWrite.All` or `Group.ReadWrite.All`), because tenant-wide application permissions override Administrative Unit boundaries.
2. **Create and populate an Administrative Unit** : Create an [Administrative Unit in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/administrative-units) and add the target directory objects that Google SecOps is allowed to modify:
   - Add target **users** to restrict user actions (**Disable Account** , **Enable Account** , **Force Password Update** , **Reset User Password** , and **Revoke User Session**).
   - Add target **groups** to restrict group membership actions (**Add User to
     a Group** and **Remove User from the Group**). Adding a group only allows the integration to modify that group's membership. It doesn't grant permission to manage the user accounts inside that group unless those users are also added directly to the Administrative Unit.
3. **Assign scoped directory roles** : Assign the required roles from the **Scoped access** column of the [API permissions table](https://docs.cloud.google.com/chronicle/docs/soar/marketplace-integrations/azure-ad.md.txt#api-permissions) to your registered application with the scope restricted to your Administrative Unit. For instructions, see the Microsoft documentation to [assign Microsoft Entra roles](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/manage-roles-portal).

## Integration parameters

The Microsoft Entra ID integration requires the following parameters:

| Parameter | Description |
|---|---|
| `Login API Root` | *Optional* The API root used to authenticate with the Microsoft identity platform. The default value is `https://login.microsoftonline.com`. |
| `API Root` | *Optional* The API root of the Azure Active Directory instance. The default value is `https://graph.microsoft.com`. |
| `Client ID` | *Required* The application (client) ID value of your Microsoft Entra ID account. |
| `Client Secret` | *Required* The client secret value of your Microsoft Entra ID account. |
| `Directory ID` | *Required* The directory (tenant) ID value of your Microsoft Entra ID account. |
| `Verify SSL` | *Optional* If selected, the integration verifies that the SSL certificate used to connect to the Microsoft Entra ID server is valid. Selected by default. |


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

You can make changes at a later stage, if needed. After you configure an
integration instance, you can use it in playbooks. For more information about
how to configure and support multiple instances, see [Supporting
multiple instances](https://docs.cloud.google.com/chronicle/docs/soar/respond/integrations-setup/supporting-multiple-instances).

<br />

## Actions


For more information about actions, see [Respond to pending actions from your workdesk](https://docs.cloud.google.com/chronicle/docs/soar/overview-and-introduction/your-workdesk/respond-to-pending-actions-from-workdesk.md.txt) and [Run a
manual action in your case](https://docs.cloud.google.com/chronicle/docs/soar/investigate/working-with-cases/what-actions-can-you-take-on-a-case#run-manual-action).

Before running actions, make sure that you have configured the required
permissions or directory roles for each capability. For more information, see
[Configure API permissions](https://docs.cloud.google.com/chronicle/docs/soar/marketplace-integrations/azure-ad.md.txt#api-permissions) and
[Permission scoping and access boundaries](https://docs.cloud.google.com/chronicle/docs/soar/marketplace-integrations/azure-ad.md.txt#permission-scoping).

### Add User to a Group

Use the **Add User to a Group** action to add a user to the specific Microsoft
Entra ID group. This action expects you to configure the `User`
entity in the `username@domain` format.

This action runs on the Google SecOps `User` entity.

#### Action inputs

The **Add User to a Group** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Group ID` | *Required* The ID of the Microsoft Entra ID group to add the user to, such as `00e40000-1971-439d-80fc-d0e000001dbd`. |

#### Action outputs

The **Add User to a Group** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |

##### Output messages

The **Add User to a Group** action can return the following output messages:

| Output message | Message description |
|---|---|
| `Member USER_ID was added to the group GROUP_ID successfully.` `Some errors occurred. Please check the logs.` | The action succeeded. |
| `Member could not be added successfully. ` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Add User to a Group** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Disable Account

Use the **Disable Account** action to disable an account in Microsoft Entra ID.
This action expects you to configure the `User` entity in the `username@domain`
format.

This action runs on the Google SecOps `User` entity.

#### Action inputs

None.

#### Action outputs

The **Disable Account** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |

##### Output messages

The **Disable Account** action can return the following output messages:

| Output message | Message description |
|---|---|
| `User account disabled successfully.` `Some errors occurred. Please check the logs.` | The action succeeded. |
| `Disable user account was not successful.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Disable Account** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Enable Account

Use the **Enable Account** action to enable an account in Microsoft Entra ID.
This action expects you to configure the `User` entity in the
`username@domain` format.

This action runs on the Google SecOps `User` entity.

#### Action inputs

None.

#### Action outputs

The **Enable Account** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |

##### Output messages

The **Enable Account** action can return the following output messages:

| Output message | Message description |
|---|---|
| `User account was enabled successfully.` `Some errors occurred. Please check the logs.` | The action succeeded. |
| `Enable user account was not successful.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Enable Account** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Enrich Host

Use the **Enrich Host** action to enrich the Google SecOps `Host`
entity with information from Microsoft Entra ID. This action
finds a match for a provided `Host` entity using on the device `displayName`
field in Microsoft Entra ID.

This action runs on the Google SecOps `Host` entity.

#### Action inputs

None.

#### Action outputs

The **Enrich Host** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Entity enrichment table | Available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Entity enrichment table

The **Enrich Host** action supports the following entity enrichment:

| Enrichment field | Logic |
|---|---|
| `AAD_Name` | Returns if it exists in the JSON result. |
| `AAD_Enabled` | Returns if it exists in the JSON result. |
| `AAD_Property Device ID` | Returns if it exists in the JSON result. |
| `AAD_OS` | Returns if it exists in the JSON result. |
| `AAD_Version` | Returns if it exists in the JSON result. |
| `AAD_Profile Type` | Returns if it exists in the JSON result. |
| `AAD_Compliant` | Returns if it exists in the JSON result. |
| `AAD_Last Sign In` | Returns if it exists in the JSON result. |

##### JSON result

The following example shows the JSON result output received when using the
**Enrich Host** action:

```json
[
    {
        "EntityResult": {
            "deletedDateTime": "1234569",
            "complianceExpirationDateTime": "1234567",
            "profileType": "RegisteredDevice",
            "key": "007",
            "if":"889922-aaaa-123123"
        },
        "Entity": "us-lt-v13001"
    }
]
```

##### Output messages

The **Enrich Host** action can return the following output messages:

| Output message | Message description |
|---|---|
| `Host details were fetched successfully: HOSTNAME.` `Some errors occurred. Please check log.` | The action succeeded. |
| `Host details were not found.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Enrich Host** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Enrich User

Use the **Enrich User** action to enrich the Google SecOps `User`
entity with information from Microsoft Entra ID. This action
expects you to configure the `User` entity in the `username@domain` format.

This action runs on the Google SecOps `Host` entity.

#### Action inputs

The **Enrich User** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Include MFA Details` | Optional. If selected, the action returns MFA details about the user. |
| `Include Last Sign In Details` | Optional. If selected, the action retrieves the user's sign-in activity (including both interactive and non-interactive sign-in timestamps). |

#### Action outputs

The **Enrich User** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Entity enrichment table | Available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Entity enrichment table

The **Enrich User** action supports the following entity enrichment:

| Enrichment field | Logic |
|---|---|
| `AAD_Name` | Returns if it exists in the JSON result. |
| `AAD_Mobile Phone` | Returns if it exists in the JSON result. |
| `AAD_Preferred Language` | Returns if it exists in the JSON result. |
| `AAD_Job Title` | Returns if it exists in the JSON result. |
| `AAD_Username` | Returns if it exists in the JSON result. |

##### JSON result

The following example shows the JSON result output received when using the
**Enrich User** action:

```json
[
  {
    "Entity": "user@domain.com",
    "EntityResult": {
      "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
      "accountEnabled": true,
      "ageGroup": null,
      "businessPhones": [],
      "city": "New York",
      "companyName": "ExampleCorp",
      "consentProvidedForMinor": null,
      "country": "US",
      "createdDateTime": "2025-01-01T00:00:00Z",
      "creationType": null,
      "department": "Security",
      "displayName": "User Name",
      "mail": "user@domain.com",
      "employeeId": "12345",
      "employeeHireDate": null,
      "employeeType": null,
      "externalUserStateChangeDateTime": null,
      "faxNumber": null,
      "givenName": "User",
      "imAddresses": [],
      "externalUserState": null,
      "jobTitle": "Security Analyst",
      "surname": "Surname",
      "lastPasswordChangeDateTime": "2025-01-01T00:00:00Z",
      "legalAgeGroupClassification": null,
      "mailNickname": "usernickname",
      "mobilePhone": "+11234567890",
      "id": "user-id-12345",
      "officeLocation": null,
      "onPremisesSamAccountName": null,
      "onPremisesDistinguishedName": null,
      "onPremisesDomainName": null,
      "onPremisesImmutableId": null,
      "onPremisesLastSyncDateTime": null,
      "onPremisesProvisioningErrors": [],
      "onPremisesSecurityIdentifier": null,
      "onPremisesSyncEnabled": null,
      "onPremisesUserPrincipalName": null,
      "otherMails": [],
      "passwordPolicies": "None",
      "preferredDataLocation": null,
      "preferredLanguage": "en-US",
      "proxyAddresses": [],
      "signInSessionsValidFromDateTime": "2025-01-01T00:00:00Z",
      "state": "NY",
      "streetAddress": "123 Main St",
      "usageLocation": "US",
      "userPrincipalName": "user@domain.com",
      "userType": "Member",
      "postalCode": "10001",
      "deletedDateTime": null,
      "showInAddressList": null,
      "isResourceAccount": null,
      "refreshTokensValidFromDateTime": "2025-01-01T00:00:00Z",
      "employeeOrgData": null,
      "passwordProfile": null,
      "authorizationInfo": {
        "certificateUserIds": []
      },
      "mfa_details": {
        "id": "user-id-12345",
        "userPrincipalName": "user@domain.com",
        "userDisplayName": "User Name",
        "userType": "member",
        "isAdmin": false,
        "isSsprRegistered": true,
        "isSsprEnabled": true,
        "isSsprCapable": true
        "isMfaRegistered": true,
        "isMfaCapable": true,
        "isPasswordlessCapable": false,
        "methodsRegistered": [
          "email",
          "mobilePhone"
        ],
        "defaultMfaMethod": "mobilePhone",
        "isSystemPreferredAuthenticationMethodEnabled": false,
        "systemPreferredAuthenticationMethods": [],
        "userPreferredMethodForSecondaryAuthentication": "oath",
        "lastUpdatedDateTime": "2026-01-01T00:00:00Z"
      }
    }
  }
]
```

##### Output messages

The **Enrich User** action can return the following output messages:

| Output message | Message description |
|---|---|
| `User details were fetched successfully: USERNAME.` `Some errors occurred. Please check the logs.` | The action succeeded. |
| `Users list fetch was not successful.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Enrich User** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Force Password Update

Use the **Force Password Update** action to force a password update for the user.
This action requires the user to change their password on the next sign-in
attempt.

The **Force Password Update** action expects you to configure the `User` entity
in the `username@domain` format.

This action runs on the Google SecOps `User` entity.

#### Action inputs

None.

#### Action outputs

The **Force Password Update** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |

##### Output messages

The **Force Password Update** action can return the following output messages:

| Output message | Message description |
|---|---|
| `Force password update on the user was successful.` `Some errors occurred. Please check the logs.` | The action succeeded. |
| `Attempt to Force user password update was not successful.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Force Password Update** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Get Manager Contact Details

Use the **Get Manager Contact Details** action to obtain the manager contact
details for the user.

The **Get Manager Contact Details** action expects you to configure the `User`
entity in the `username@domain` format.

This action runs on the Google SecOps `User` entity.

#### Action inputs

The **Get Manager Contact Details** action requires the following parameter:

| Parameter | Description |
|---|---|
| `Fields To Return` | Optional. A comma-separated list of specific manager profile attributes to retrieve. If no value is provided, the action returns the default set of attributes defined by the API. The default value is `accountEnabled,ageGroup,assignedLicenses, businessPhones,city,companyName,consentProvidedForMinor,country, createdDateTime,creationType,department,displayName,mail,employeeId, employeeHireDate,employeeOrgData,employeeType,onPremisesExtensionAttributes, externalUserStateChangeDateTime,faxNumber,givenName,imAddresses,identities, externalUserState,jobTitle,surname,lastPasswordChangeDateTime, legalAgeGroupClassification,mailNickname,mobilePhone,id,officeLocation, onPremisesSamAccountName,onPremisesDistinguishedName,onPremisesDomainName, onPremisesImmutableId,onPremisesLastSyncDateTime, onPremisesProvisioningErrors,onPremisesSecurityIdentifier, onPremisesSyncEnabled,onPremisesUserPrincipalName,otherMails, passwordPolicies,passwordProfile,preferredDataLocation,preferredLanguage, proxyAddresses,signInSessionsValidFromDateTime,sponsors,state,streetAddress, usageLocation,userPrincipalName,userType,postalCode,authorizationInfo, deletedDateTime,showInAddressList,isResourceAccount, refreshTokensValidFromDateTime`. |
| `Include MFA Details` | Optional. If selected, the action returns MFA details about the user. |
| `Include Last Sign In Details` | Optional. If selected, the action retrieves the user's sign-in activity (including both interactive and non-interactive sign-in timestamps). |

#### Action outputs

The **Get Manager Contact Details** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Available |
| Entity enrichment table | Available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall table

The **Get Manager Contact Details** action can return the following table in
Google SecOps:

Table name: **Manager contact**

Columns:

- **Name**
- **Phone number**

##### Entity enrichment table

The **Get Manager Contact Details** action supports the following entity
enrichment:

| Enrichment field | Logic |
|---|---|
| `Display Name` | Returns if it exists in the JSON result. |
| `Mobile Phone` | Returns if it exists in the JSON result. |
| `@odata.context` | Returns if it exists in the JSON result. |
| `AAD_Job Title` | Returns if it exists in the JSON result. |
| `AAD_Username` | Returns if it exists in the JSON result. |

##### JSON result

The following example shows the JSON result output received when using the
**Get Manager Contact Details** action:

```json
[
  {
    "Entity": "user@example.com",
    "EntityResult": {
      "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
      "accountEnabled": true,
      "ageGroup": null,
      "businessPhones": [],
      "city": "Anytown",
      "companyName": "Example Corporation",
      "consentProvidedForMinor": null,
      "country": "US",
      "createdDateTime": "2025-01-01T00:00:00Z",
      "creationType": null,
      "department": "Security Operations",
      "displayName": "Internal User",
      "mail": "user@example.com",
      "employeeId": "ID-00001",
      "employeeHireDate": null,
      "employeeType": "Full-time",
      "externalUserStateChangeDateTime": null,
      "faxNumber": null,
      "givenName": "Alex",
      "imAddresses": [],
      "externalUserState": null,
      "jobTitle": "Security Lead",
      "surname": "Doe",
      "lastPasswordChangeDateTime": "2025-01-01T00:00:00Z",
      "legalAgeGroupClassification": null,
      "mailNickname": "alexdoe",
      "mobilePhone": "+1 555-0100",
      "id": "00000000-0000-0000-0000-000000000000",
      "officeLocation": null,
      "usageLocation": "US",
      "userPrincipalName": "user@example.com",
      "userType": "Member",
      "postalCode": "00000",
      "deletedDateTime": null,
      "showInAddressList": null,
      "isResourceAccount": null,
      "refreshTokensValidFromDateTime": "2025-01-01T00:00:00Z",
      "employeeOrgData": null,
      "authorizationInfo": {
        "certificateUserIds": []
      },
      "sponsors": [],
      "mfa_details": {
        "id": "00000000-0000-0000-0000-000000000000",
        "userPrincipalName": "user@example.com",
        "userDisplayName": "Internal User",
        "userType": "member",
        "isAdmin": true,
        "isSsprRegistered": false,
        "isSsprEnabled": true,
        "isSsprCapable": false,
        "isMfaRegistered": true,
        "isMfaCapable": true,
        "isPasswordlessCapable": false,
        "methodsRegistered": [
          "mobilePhone",
          "softwareOneTimePasscode"
        ],
        "defaultMfaMethod": "softwareOneTimePasscode",
        "isSystemPreferredAuthenticationMethodEnabled": true,
        "systemPreferredAuthenticationMethods": [
          "SoftwareOTP"
        ],
        "userPreferredMethodForSecondaryAuthentication": "oath",
        "lastUpdatedDateTime": "2026-01-01T00:00:00Z"
      }
    }
  }
]
```

##### Output messages

The **Get Manager Contact Details** action can return the following output
messages:

| Output message | Message description |
|---|---|
| `User manager details were fetched successfully.` `Some errors occurred. Please check the logs.` | The action succeeded. |
| `Could not fetch user manager's details successfully.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Get Manager Contact Details** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Is User in Group

Use the **Is User in Group** action to check if the user has membership in a
specific Microsoft Entra ID group. This action expects you to configure the
`User` entity in the `username@domain` format.

This action runs on the Google SecOps `User` entity.

#### Action inputs

The **Is User in Group** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Group ID` | *Required* The ID of the Microsoft Entra ID group to add the user to, such as `00e40000-1971-439d-80fc-d0e000001dbd`. |

#### Action outputs

The **Is User in Group** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### JSON result

The following example shows the JSON result output received when using the
**Is User in Group** action:

```json
[
    {
        "EntityResult": "true",
        "Entity": "user@example.com"
    }
]
```

##### Output messages

The **Is User in Group** action can return the following output messages:

| Output message | Message description |
|---|---|
| `The following user was found in the group: USER_ID.` `Some errors occurred. Please check the logs.` | The action succeeded. |
| `User was not found in the group.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Is User in Group** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### List Groups

Use the **List Groups** action to list Microsoft Entra ID groups using the
specified search criteria.

For the **List Groups** action, filtering works with the `Name` field.

This action doesn't run on Google SecOps entities.

#### Action inputs

The **List Groups** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Order By` | *Optional* The order to sort the returned groups by their name. The default value is `ASC`. The possible values are as follows: - `DESC` - `ASC` |
| `Results Limit` | *Optional* The maximum number of groups to return. |
| `Filter Logic` | *Optional* The logic to filter groups by their name. The default value is `Equal`. The possible values are as follows: - `Equal` - `Contains` |
| `Filter Value` | *Optional* The value to filter groups using the selected filter logic. This value applies to the group name. If you select `Equal`, the action attempts to find the exact match among results. If you select `Contain`, the action attempts to find results that contain the provided substring. If you don't set a value, the filter doesn't apply. |

#### Action outputs

The **List Groups** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Available |
| Entity enrichment table | Available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall table

The **List Groups** action can return the following table in
Google SecOps:

Table name: **Groups**

Columns:

- **Name**
- **ID**
- **Description**
- **Mail**
- **Created Time**
- **Group Type**

##### Entity enrichment table

The **List Groups** action supports the following entity enrichment:

| Enrichment field | Logic |
|---|---|
| `Group Type` | Returns if it exists in the JSON result. |
| `ID` | Returns if it exists in the JSON result. |
| `Name` | Returns if it exists in the JSON result. |
| `Description` | Returns if it exists in the JSON result. |
| `Created Time` | Returns if it exists in the JSON result. |

##### JSON result

The following example shows the JSON result output received when using the
**List Groups** action:

```json
[
  {
    "Group_Type": "managed",
    "Id": "1212-12312-123",
    "Name": "Group Name",
    "Description": "This group is ...",
    "Created_Time": "2019-10-24T19:10:18Z",
    "onPremisesSamAccountName": "alext"
  }
]
```

##### Output messages

The **List Groups** action can return the following output messages:

| Output message | Message description |
|---|---|
| `Groups list was fetched successfully.` `Some errors occurred. Please check the logs.` | The action succeeded. |
| `Groups list fetch was not successful.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **List Groups** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### List Members in the Group

Use the **List Members in the Group** action to list members in the specified
Microsoft Entra ID group.

The filtering logic works based on the `Filter Key` parameter value.

This action doesn't run on Google SecOps entities.

#### Action inputs

The **List Members in the Group** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Max Records To Return` | *Optional* The maximum number of records to return. The default value is 50. |
| `Group Name` | *Optional* The name of the Microsoft Entra ID group to list members. |
| `Group ID` | *Optional* The ID of the Microsoft Entra ID group to list members. If you configure both the `Group Name` and `Group ID` parameters, the action uses the `Group ID` parameter value. |
| `Filter Key` | *Optional* The field to filter group members by, such as `User Display Name`. The possible values are as follows: - `Select One` - `User Display Name` - `User Principal Name` - `User Mail Name` |
| `Filter Logic` | *Optional* The logic to apply to the filter. The possible values are as follows: - `Not Specified` - `Equal` - `Contains` |
| `Filter Value` | *Optional* The value to use for filtering group members based on the selected `Filter Key` and `Filter Logic` parameter values. If you select `Equal`, the action attempts to find the exact match among results. If you select `Contain`, the action attempts to find results that contain the provided substring. If you don't set a value, the filter doesn't apply. |

#### Action outputs

The **List Members in the Group** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Available |
| Enrichment table | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall table

The **List Members in the Group** action can return the following table in
Google SecOps:

Table name: **Available members of the group**

Columns:

- **ID**
- **User Principal Name**
- **Display Name**
- **Surname**
- **Given Name**
- **Mail**
- **Job Title**
- **Business Phones**
- **Mobile Phone**
- **Office Location**
- **Preferred Language**

##### JSON result

The following example shows the JSON result output received when using the
**List Members in the Group** action:

```json
[
  {
    "@odata.type": "#microsoft.graph.user",
    "id": "b786d3cf-e97d-4511-b61c-0559e9f4da75",
    "businessPhones": [],
    "displayName": "Alex T",
    "givenName": "Alex",
    "jobTitle": "Software Engineer",
    "mail": "alex.t@example.com",
    "mobilePhone": null,
    "officeLocation": "Building A",
    "preferredLanguage": "en-US",
    "surname": "T",
    "userPrincipalName": "alex.t@example.com"
  }
]
```

##### Output messages

The **List Members in the Group** action can return the following output
messages:

| Output message | Message description |
|---|---|
| `Successfully found members for the provided criteria in Azure AD group.` `No members were found for the provided criteria in Azure AD group.` `The filter was not applied, because parameter "Filter Value" has an empty value.` | The action succeeded. |
| `Error executing action "List Members in the Group". Reason: ERROR_REASON` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **List Members in the Group** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### List User's Groups Membership

Use the **List User's Groups Membership** action to list the Microsoft Entra ID
groups of which the user is a member.

You can provide the username as an entity or an action input parameter. If you
configure the username as both the entity and the input parameter, the action
uses the input parameter.

To configure the username, follow the `username@domain` format.

This action runs on the Google SecOps `Username` entity.

#### Action inputs

The **List User's Groups Membership** action requires the following parameters:

| Parameter | Description |
|---|---|
| `User Name` | *Optional* A comma-separated list of usernames to retrieve group memberships for, such as `username@domain`. If you don't set a value, the action uses the user identifiers from the `Username` entity. |
| `Return Only Security Enabled Groups` | *Optional* If selected, the action returns only security-enabled groups to which the user belongs. Not selected by default. |
| `Return Detailed Groups Information` | *Optional* If selected, the action returns detailed information about the Microsoft Entra ID groups. Not selected by default. |
| `Filter Key` | *Optional* The key to use for filtering groups. The default value is `Select One`. The possible values are as follows: - `Select One` - `Group Display Name` - `Group Description` |
| `Filter Logic` | *Optional* The logic to apply when filtering the groups. The default value is `Not Specified`. Possible values are as follows: - `Not Specified` - `Equal` - `Contains` |
| `Filter Value` | *Optional* The value to use for filtering groups. If you select `Equal`, the action attempts to find the exact match among results. If you select `Contain`, the action attempts to find results that contain the provided substring. If you don't set a value, the filter doesn't apply. |
| `Max Records To Return` | *Optional* The maximum number of records to return. If you don't set a value, the action returns 50 records by default. |

#### Action outputs

The **List User's Groups Membership** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Available |
| Enrichment table | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall table

The **List User's Groups Membership** action can return the following table in
Google SecOps:

Table name: **Group Memberships**

Columns:

- **ID**
- **Display Name**
- **Description**
- **Security Enabled**
- **Security Identifier**
- **Created DateTime**
- **Classification**
- **Visibility**
- **Mail**
- **Mail Enabled**
- **Mail Nickname**

##### JSON result

The following example shows the JSON result output received when using the
**List User's Groups Membership** action:

```json
{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(Edm.String)",
    "value": [
        "ID",
        "ID",
        "ID",
    ]
}
```

##### Output messages

The **List User's Groups Membership** action can return the following output
messages:

| Output message | Message description |
|---|---|
| `Successfully found groups for the provided criteria for the following entities: ENTITY_ID ` `The following entities were not found in the Azure AD: ENTITY_ID` `No groups were found in Azure Active Directory for the following entities: ENTITY_ID` `The filter was not applied, because parameter "Filter Value" has an empty value.` | The action succeeded. |
| `Error executing action "List User's Groups Membership". Reason: ERROR_REASON` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **List User's Groups Membership** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### List Users

Use the **List Users** action to list Microsoft Entra ID users using the
specified search criteria.

For the **List Users** action, filtering works with the `Username`
(`userPrincipalName`) field.

This action doesn't run on Google SecOps entities.

#### Action inputs

The **List Users** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Filter` | *Optional* The fields to include in the results. The default value is `All Fields`. The possible values are as follows: - `All Fields` - `displayName` - `userPrincipalName` - `id` - `jobTitle` - `mail` - `mobilePhone` - `preferredLanguage` - `surname` - `givenName` |
| `Order By Field` | *Optional* The field to order the results by. The default value is `displayName`. The possible values are as follows: - `displayName` - `userPrincipalName` |
| `Order By` | *Optional* The order of the results (ascending or descending). The default value is `ASC`. The possible values are as follows: - `DESC` - `ASC` |
| `Results Limit` | *Optional* The maximum number of users to return. |
| `Advanced Filter Logic` | *Optional* The logic to use for advanced filtering that applies to the `Username` (`userPrincipalName`) field. The default value is `Equal`. Possible values are as follows: - `Equal` - `Contains` |
| `Advanced Filter Value` | *Optional* The value to use in the advanced filter for the `Username` (`userPrincipalName`) field. If you select `Equal`, the action attempts to find the exact match among results. If you select `Contain`, the action attempts to find results that contain the provided substring. If you don't set a value, the filter doesn't apply. |

#### Action outputs

The **List Users** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Available |
| Entity enrichment table | Available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall table

The **List Users** action can return the following table in
Google SecOps:

Table name: **Users**

Columns:

- **Name**
- **Username**
- **ID**
- **Given name**
- **Preferred language**
- **Mail**
- **Mobile Phone**
- **Surname**
- **Job Title**

##### Entity enrichment table

The **List Users** action supports the following entity enrichment:

| Enrichment field | Logic |
|---|---|
| `Username` | Returns if it exists in the JSON result. |
| `Surname` | Returns if it exists in the JSON result. |
| `Name` | Returns if it exists in the JSON result. |
| `Job Title` | Returns if it exists in the JSON result. |
| `Mail` | Returns if it exists in the JSON result. |

##### JSON result

The following example shows the JSON result output received when using the
**List Users** action:

```json
[
    {
        "Group Type": "managed",
        "Id": "ID",
        "Name": "Example",
        "Description": "Example",
        "Created Time":"2019-10-24T19:10:18Z"
    }
]
```

##### Output messages

The **List Users** action can return the following output messages:

| Output message | Message description |
|---|---|
| `List of users was fetched successfully.` `Some errors occurred. Please check the logs.` | The action succeeded. |
| `User list fetch was not successful.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **List Users** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Ping

Use the **Ping** action to test the connectivity to Microsoft Entra ID.

This action runs on all Google SecOps entities.

#### Action inputs

None.

#### Action outputs

The **Ping** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |

##### Output messages

The **Ping** action can return the following output messages:

| Output message | Message description |
|---|---|
| `Connection established successfully.` | The action succeeded. |
| `Connection could not be established successfully.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Ping** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Remove User from the Group

Use the **Remove User from the Group** action to remove a user from the
specified group in Microsoft Entra ID.

You can provide the username as an entity or an action input parameter. If you
configure the username as both the entity and the input parameter, the action
uses the input parameter.

To configure the username, follow the `username@domain` format.

This action runs on the Google SecOps `Username` entity.

#### Action inputs

The **Remove User from the Group** action requires the following parameters:

| Parameter | Description |
|---|---|
| `User Name` | *Optional* A comma-separated string of usernames to remove from the specified group. To configure this parameter value, use the `username@domain` format. If you don't set a value, the action runs on the usernames of the user entities from an action incident. |
| `Group Name` | *Optional* The name of the group to remove the user from. |
| `Group ID` | *Optional* The ID of the group to remove the user from. If you set both the `Group Name` and `Group ID` parameters, the action prioritizes the `Group ID` value. |

#### Action outputs

The **Remove User from the Group** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |

##### Output messages

The **Remove User from the Group** action can return the following output
messages:

| Output message | Message description |
|---|---|
| `Successfully removed the following entities from the Azure AD group: ENTITY_ID` `The following entities were not found in the Azure AD: ENTITY_ID` `No usernames were removed from the Azure AD group.` | The action succeeded. |
| `Error executing action "Remove User from the Group". Reason: ERROR_REASON` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Remove User from the Group** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Reset User Password

Use the **Reset User Password** action to reset the user password to the one
that you specify in the action. This action requires the user to change their
password on the next sign-in attempt.

The **Reset User Password** action expects you to configure the `User` entity
in the `username@domain` format.

This action runs on the Google SecOps `User` entity.

#### Action inputs

The **Reset User Password** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Password` | *Required* The new password to set for the user. |

#### Action outputs

The **Reset User Password** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |

##### Output messages

The **Reset User Password** action can return the following output messages:

| Output message | Message description |
|---|---|
| `User password was reset successfully.` `Some errors occurred. Please check the logs.` | The action succeeded. |
| `User password reset was not successful.` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Reset User Password** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

### Revoke User Session

Use the **Revoke User Session** action to revoke a user session.

This action runs on the following Google SecOps entities:

- `Username`
- `Email Address`

#### Action inputs

None.

#### Action outputs

The **Revoke User Session** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### JSON result

The following examples show the JSON result outputs received when using the
**Revoke User Session** action:

- If the user exists:

  ```json
  {
      "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Edm.Boolean",
      "value": true
  }
  ```
- If the user is not found:

  ```json
  {
      "error": "User not found."
  }
  ```

##### Output messages

The **Revoke User Session** action can return the following output messages:

| Output message | Message description |
|---|---|
| `Successfully revoked sessions for the following users in Azure AD: ENTITY_ID` `Action wasn't able to find the following users in Azure AD: ENTITY_ID` `None of the provided users were found in Azure AD.` | The action succeeded. |
| `Error executing action "Revoke User Session". Reason: ERROR_REASON` | The action failed. Check the connection to the server, input parameters, or credentials. |

##### Script result

The following table lists the value for the script result output when using
the **Revoke User Session** action:

| Script result name | Value |
|---|---|
| `is_success` | `True` or `False` |

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