Google Workspace

Integration version: 14.0

Prerequisites

Before configuring the Google Workspace integration in Google Security Operations SOAR, make sure to complete all the prerequisite steps.

1. Create service account credentials

  1. In the Google Cloud console, go to the Credentials page.

    Go to Credentials

  2. From the Create credentials menu, select Service account.

  3. Enter a name in the Service account name field.

  4. Optional: Edit the service account ID.

  5. Click Create. A Service account permissions screen appears.

  6. Click Continue. A Grant users access to this service account screen appears.

  7. Click Create key and click Done. A Private key saved to your computer dialog appears and a copy of the private key downloads to your computer.

  8. Click Close.

2. Create a custom role for the integration

  1. Go to the Google Admin portal.
  2. Go to Admin Roles.
  3. Provide a name for the new custom role name and click Next.
  4. On the Select Privileges page, go to the Admin API privileges section.

  5. Select the following privileges:

    • Whole Organization Units
    • Whole Users
    • Whole Groups

  6. Click Continue.

  7. To create a new custom role, click Create Role.

3. Assign the custom role to a user

  1. To create a new user, open the Users page.
  2. Add a new user that is associated with the service account.
  3. Open settings for the newly created user and click Assign roles.
  4. Assign the new custom role to the new user.
  5. Click Authorize.

4. Delegate domain-wide authority to your service account

  1. From your domain's Admin console, go to Main menu > Security > Access and data control > API controls.
  2. In the Domain wide delegation pane, select Manage Domain Wide Delegation.
  3. Click Add new.
  4. In the Client ID field, enter the client ID obtained from the preceding service account creation steps.
  5. In the OAuth Scopes field, enter the following comma-delimited list of the scopes required for your application:
    • https://www.googleapis.com/auth/admin.directory.user
    • https://www.googleapis.com/auth/admin.directory.customer.readonly
    • https://www.googleapis.com/auth/admin.directory.user.readonly
    • https://www.googleapis.com/auth/cloud-platform
    • https://mail.google.com/
    • https://www.googleapis.com/auth/gmail.modify
    • https://www.googleapis.com/auth/admin.directory.domain.readonly
    • https://www.googleapis.com/auth/admin.directory.group
    • https://www.googleapis.com/auth/admin.directory.group.member
    • https://www.googleapis.com/auth/admin.directory.orgunit
    • https://www.googleapis.com/auth/admin.directory.user.alias
    • https://www.googleapis.com/auth/gmail.compose
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.send
    • https://www.googleapis.com/auth/gmail.labels
    • https://www.googleapis.com/auth/gmail.settings.basic
    • https://www.googleapis.com/auth/apps.alerts

5. Enable Admin SDK API for your project

  1. In the Google Cloud console, go to APIs & Services.

    Go to APIs & Services

  2. Click Enable APIs and Services.

  3. Enable the Admin SDK API for your project.

Integrate Google Workspace 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
Client ID String N/A Specify the Client ID value to use for OAuth-based authentication.
Client Secret Password N/A Specify the Client Secret value to use for OAuth-based authentication.
Refresh Token Password N/A If OAuth-based (not based on service account) authentication is used, specify the Refresh Token that is generated with related integration actions.
Verify SSL Checkbox Checked If enabled, the server-side certificate used for connection is validated.
User's Service Account JSON String N/A

For the service account based authentication, specify the user service account JSON file.

Provide the full content of the service account JSON file.
Delegated Email String N/A Specify the email that integration should use.

Integration can be configured with either the User's Service Account and Delegated Email (preferred option) or Client ID, Client Secret and Refresh Token parameters.

If the User's Service Account JSON and Delegated Email parameters are provided, the Client ID, Client Secret and Refresh Token parameters are ignored, and the other way around.

Actions

Add Members To Group

Description

Add members to a group.

Parameters

Parameter Type Default Value Is Mandatory Description
Group Email Address String N/A Yes Email of the group to add the members to.

Run On

This action runs on the User entity.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success:False
JSON Result
N/A
Entity Enrichment

N/A

Insights

N/A

Create Group

Description

As a Google Workspace Groups administrator, you can create groups for your organization in the Google Admin console, the Groups API, or Google Cloud Directory Sync (GCDS). If you turn on Groups for Business, you can also create groups for your organization in Google Groups (groups.google.com).

Parameters

Parameter Type Default Value Is Mandatory Description
Email Address String N/A Yes Email address of the new group.
Name String N/A No Display name of the new group.
Description String N/A No Description of the new group.

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
JSON Result
[
   {
      "kind":"admin#directory#group",
      "id":"XXXXXX",
      "etag":"XXXXXXXXXXX",
      "email":"XXXXXXXX@XXXXXXXX.com",
      "name":"XXXXXXXXXXXXXX",
      "description":"",
      "adminCreated":"True"
   }
]
Entity Enrichment

N/A

Insights

N/A

Create OU

Description

Create a new organizational unit.

Parameters

Parameter Type Default Value Is Mandatory Description
Customer ID String N/A Yes

The unique ID for the customer's Google Workspace account.

The 'my_customer' alias can also be used to represent your account's customerId.

To find Customer ID, from the Google Workspace Admin console Home page, go to Account settings and then Profile.
Name String N/A No Display name of the new OU.
Description String N/A No Description name of the new OU.
Parent OU Path String N/A Yes The full path to the organizational unit's parent OU.

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
JSON Result
[
   {
      "kind":"admin#directory#orgUnit",
      "etag":"XXXXXXXXXXXX",
      "name":"XXXXX",
      "orgUnitPath":"/XXXXX",
      "orgUnitId":"id:XXXXXXXXXX",
      "parentOrgUnitPath":"/",
      "parentOrgUnitId":"id:XXXXXXXXXX"
   }
]
Entity Enrichment

N/A

Insights

N/A

Create User

Description

Create a new user. When you add a user to your Google Workspace account, you give them an email address at your business domain and an account they can use to access G Suite services.

Parameters

Parameter Type Default Value Is Mandatory Description
Given Name String N/A Yes The user's first name.
Family Name String N/A Yes The user's last name.
Password Password N/A Yes The password of the new user.
Email Address String N/A Yes The user's primary email address.
Phone String N/A No The phone number of the user.
Gender String N/A No The gender of the user. Valid values: female, male, other, unknown.
Department String N/A No The name of the department of the user.
Organization String N/A No The name of the organization of the user.
Change Password At Next Login Checkbox Unchecked No Whether to force the user to change his password on next login.

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
JSON Result
[
   {
      "kind":"admin#directory#user",
      "id":"XXXXXXXXXXX",
      "etag":"XXXXXX",
      "primaryEmail":"first@XXX.com",
      "name":{
         "givenName":"XXXXXX",
         "familyName":"XXXXXXX"
      },
      "isAdmin":"False",
      "isDelegatedAdmin":"False",
      "creationTime":"2020-12-22T13:44:29.000Z",
      "organizations":[
         {
            "name":"MyOrg"
         }
      ],
      "phones":[
         {
            "value":"XXXXXXXX"
         }
      ],
      "gender":{
         "type":"male"
      },
      "customerId":"XXXXXX",
      "orgUnitPath":"/",
      "isMailboxSetup":"False"
   }
]
Entity Enrichment

N/A

Insights

N/A

Delete OU

Description

Delete an organizational unit. You can't delete an organization if it has users, devices, or child organizations. Before deleting an organization, move any users and devices to other organizations, and remove any child organizations.

Parameters

Parameter Type Default Value Is Mandatory Description
is_success String N/A Yes

The unique ID for the customer's Google Workspace account.

The 'my_customer' alias can also be used to represent your account's customerId.
OU Path String N/A Yes

The full path to the organizational unit.

If organizational unit is located under root (/) path, provide just organizational unit name, without path.

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
JSON Result
N/A
Entity Enrichment

N/A

Insights

N/A

Delete User

Description

When a user leaves your organization, you can delete their account. If you delete a user, they cannot access any of your organization's Google Workspace services.

Parameters

Parameter Type Default Value Is Mandatory Description
Email Address String N/A Yes The email address of the user to delete.

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
JSON Result
N/A
Entity Enrichment

N/A

Insights

N/A

Enrich Entities

Description

Enrich Google Security Operations SOAR User entities with information from Google G Suite.

Parameters

N/A

Run On

This action runs on the User entity.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success:False
JSON Result
[{
    "Phones":
       [{
          "customType": "",
          "type": "custom",
          "value": "123456780"
       }],
   "isDelegatedAdmin": false,
   "suspended": false,
   "id": "111",
   "nonEditableAliases": ["john@domain.com.test-google-a.com"],
   "archived": false,
   "isEnrolledIn2Sv": true,
   "includeInGlobalAddressList": true,
   "Relations":
        [{
          "type": "manager",
          "value": "john_doe@example.com"
        }],
   "isAdmin": false,
   "etag": "\\\"GPUJN6YVAOElesyqxtgGs7jrFWY/f0qlzlJyOmYnDPZ9yd_UYbb3N-k\\\"",
   "lastLoginTime": "2019-02-11T12:24:41.000Z",
   "orgUnitPath": "/OU-1",
   "agreedToTerms": true,
   "externalIds": [{"type": "organization",
                    "value": ""}],
   "ipWhitelisted": false,
   "kind": "admin#directory#user",
   "isEnforcedIn2Sv": true,
   "isMailboxSetup": true,
   "emails":
       [{
          "primary": true,
          "address": "john_doe@example.com"
        },
        {
          "address": "john_doe@example.com"
        }],
    "organizations":
        [{
           "department": "R&D",
           "customType": "", "name": "Company"
         }],
     "primaryEmail": "john_doe@example.com",
     "name":
         {
            "fullName": "John Doe",
            "givenName": "John",
            "familyName": "Doe"
         },
     "gender": {"type": "male"},
     "creationTime": "2017-10-26T06:57:13.000Z",
     "changePasswordAtNextLogin": false,
     "customerId": "C0123ka"
}]
Entity Enrichment
Enrichment Field Name Logic - When to apply
Phones Returns if it exists in JSON result
isDelegatedAdmin Returns if it exists in JSON result
suspended Returns if it exists in JSON result
id Returns if it exists in JSON result
nonEditableAliases Returns if it exists in JSON result
archived Returns if it exists in JSON result
isEnrolledIn2Sv Returns if it exists in JSON result
includeInGlobalAddressList Returns if it exists in JSON result
Relations Returns if it exists in JSON result
isAdmin Returns if it exists in JSON result
etag Returns if it exists in JSON result
lastLoginTime Returns if it exists in JSON result
orgUnitPath Returns if it exists in JSON result
agreedToTerms Returns if it exists in JSON result
externalIds Returns if it exists in JSON result
ipWhitelisted Returns if it exists in JSON result
kind Returns if it exists in JSON result
isEnforcedIn2Sv Returns if it exists in JSON result
isMailboxSetup Returns if it exists in JSON result
emails Returns if it exists in JSON result
organizations Returns if it exists in JSON result
primaryEmail Returns if it exists in JSON result
name Returns if it exists in JSON result
gender Returns if it exists in JSON result
creationTime Returns if it exists in JSON result
changePasswordAtNextLogin Returns if it exists in JSON result
customerId Returns if it exists in JSON result
Insights

N/A

Generate Token

Description

Get an access token using the authorization URL received in the previous step.

Parameters

Parameter Type Default Value Is Mandatory Description
Redirect URL String N/A Yes Use the redirect URL you registered to request an authorization.
Authorization URL String N/A Yes Use the authorization URL received in the previous step to request an access token.

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
is_connected True/False is_connected:False
JSON Result
N/A
Entity Enrichment

N/A

Insights

N/A

Get Authorization

Description

Run the action and browse to the received URL.

Parameters

Parameter Type Default Value Is Mandatory Description
Redirect URL String N/A Yes Use the redirect URL you registered to request an authorization.

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
is_connected True/False is_connected:False
JSON Result
N/A
Entity Enrichment

N/A

Insights

N/A

List Group Members

Description

List the members of a group.

Parameters

Parameter Type Default Value Is Mandatory Description
Group Email Address String N/A Yes Email address of the new group.
Include Derived Membership Checkbox Checked No Whether to list indirect memberships.

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
members True/False members:True
JSON Result
​[
  {
   "status": "ACTIVE",
   "kind": "admin#directory#member",
   "email": "john_doe@example.com",
   "etag": "\\\"GPUJN6YVAOElesyqxtgGs7jrFWY/dbomsL3j2y54EOovciz6aeL0EIc\\\"",
   "role": "MEMBER",
   "type": "USER",
   "id": "145"
  },{
   "status": "ACTIVE",
   "kind": "admin#directory#member",
   "email": "john_doe@example.com",
   "etag": "\\\"GPUJN6YVAOElesyqxtgGs7jrFWY/5oJlZnuLJeQxaAf9HUx5fhMoQWA\\\"",
   "role": "MEMBER",
   "type": "USER", "id": "123"
  }
]
Entity Enrichment

N/A

Insights

N/A

List OU of Account

Description

List the organizational units of an account.

Parameters

Parameter Type Default Value Is Mandatory Description
Customer ID String N/A Yes

The unique ID for the customer's Google Workspace account.

The 'my_customer' alias can also be used to represent your account's customerId.

To find Customer ID, from the Google Workspace Admin console Home page, go to Account settings and then Profile.

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
organizational_units True/False organizational_units:False
JSON Result
[{
   "kind": "admin#directory#orgUnit",
   "parentOrgUnitPath": "/",
   "name": "OU-1",
   "etag": "\\\"GPUJN6YVAOElesyqxtgGs7jrFWY/-MtnpYp9nCMp03TEVW1UPX01zBA\\\"",
   "orgUnitPath": "/OU-1",
   "parentOrgUnitId": "id:1455",
   "blockInheritance": false,
   "orgUnitId": "id:123",
   "description": ""
}]
​
Entity Enrichment

N/A

Insights

N/A

Ping

Description

Test connectivity to Google Workspace.

Parameters

N/A

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success:True
JSON Result
N/A
Entity Enrichment

N/A

Insights

N/A

Remove Members From Group

Description

Remove members from a group.

Parameters

Parameter Type Default Value Is Mandatory Description
Group Email Address String N/A Yes Email of the group to remove the members from.

Run On

This action runs on the User entity.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success:False
JSON Result
N/A
Entity Enrichment

N/A

Insights

N/A

Update OU

Description

Update an organizational unit.

Parameters

Parameter Type Default Value Is Mandatory Description
Customer ID String N/A Yes

The unique ID for the customer's Google Workspace account.

The 'my_customer' alias can also be used to represent your account's customerId.
Name String N/A No Display name of the OU.
Description String N/A No Description of the OU.
OU Path String N/A Yes

The full path to the organizational unit.

If organizational unit is located under root (/) path, provide just organizational unit name, without path.

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
JSON Result
N/A
Entity Enrichment

N/A

Insights

N/A

Update User

Description

Update a Google Workspace Directory user.

Parameters

Parameter Type Default Value Is Mandatory Description
Email Address String N/A Yes User primary email address that is used to specify which user to update.
Given Name String N/A No The user's first name.
Family Name String N/A No The user's last name.
Password Password N/A No The password of the user.
Phone String N/A No The phone number of the user.
Gender String N/A No

The gender of the user.

Valid values: female, male, other, unknown
Department String N/A No The name of the department of the user.
Organization String N/A No The name of the organization of the user.
Change Password At Next Login Checkbox Unchecked No Whether to force the user to change his password on next login.
User Status DDL Not Changed
  • Not Changed
  • Blocked
  • Unblocked
 No Specify if user status should be updated to blocked or unblocked. By default action is no changing the user status.

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
JSON Result
N/A
Entity Enrichment

N/A

Insights

N/A

Delete Group

Description

Delete a Google Workspace Directory Group.

Parameters

Parameter Type Default Value Is Mandatory Description
Group Email Address String N/A Yes Email of the group to delete.

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
JSON Result
N/A
Entity Enrichment

N/A

Insights

N/A

Case Wall
Result type Value/Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful: "Google Workspace group {0} deleted".format(group email)

If not successful, for example wrong group email was provided: "Action was not able to find Google Workspace group for deletion."

Action should fail and stop playbook execution:

If a critical error, like wrong credentials or lost connectivity: "Failed to connect to the Google Workspace! Error is {0}".format(exception.stacktrace)

 General

List Users

Description

List users present in account.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Customer ID String N/A No

The unique ID for the customer's Google Workspace account.

If not provided, will be set to my_customer automatically to represent current account Customer ID.
Domain String N/A No Specify a domain to search for users in.
Manager Email String N/A No The email address of a user's manager either directly or up the management chain.
Return only Admin Accounts? Checkbox Unchecked No Specify whether to return only admin accounts.
Return only Delegated Admin Accounts? Checkbox Unchecked No Specify whether to return only delegated admin accounts.
Return only Suspended Users? Checkbox Unchecked No Specify whether to return only suspended accounts.
Org Unit Path String N/A No

The full path of an org unit to retrieve users from. This matches all org unit chains under the target.
Department String N/A No

The department within the organization to retrieve users from.
Record limit Integer 20 No Specify how many records can be returned by the action.
Custom Query Parameter String N/A No

Optional. Specify custom query parameter you want to add to the list users search call.

Example: orgName='Human Resources'

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
JSON Result
{
    "kind": "admin#directory#users",
    "etag": "\"Ef8EolXJejeywz1Ad4Um6aD7Ljw7tbB2JG38nYOLokk/MqYvteKxL6i_77gL49mVryEYzw8\"",
    "users": [
        {
            "kind": "admin#directory#user",
            "id": "117479962705715593400",
            "etag": "\"Ef8EolXJejeywz1Ad4Um6aD7Ljw7tbB2JG38nYOLokk/-8EPwDwnueuz6UDL3ZZFBom8U58\"",
            "primaryEmail": "fakeuser@smplylab.com",
            "name": {
                "givenName": "fakeuser",
                "familyName": "user",
                "fullName": "fakeuser user"
            },
            "isAdmin": true,
            "isDelegatedAdmin": false,
            "lastLoginTime": "2020-12-22T06:40:34.000Z",
            "creationTime": "2020-07-22T09:23:28.000Z",
            "agreedToTerms": true,
            "suspended": false,
            "archived": false,
            "changePasswordAtNextLogin": false,
            "ipWhitelisted": false,
            "emails": [
                {
                    "address": "fakeuser@smplylab.com",
                    "primary": true
                },
                {
                    "address": "fakeuser@smplylab.com.test-google-a.com"
                }
            ],
            "nonEditableAliases": [
                "fakeuser@smplylab.com.test-google-a.com"
            ],
            "customerId": "C038judqw",
            "orgUnitPath": "/Management",
            "isMailboxSetup": true,
            "isEnrolledIn2Sv": false,
            "isEnforcedIn2Sv": false,
            "includeInGlobalAddressList": true,
            "recoveryEmail": "lab_gcp@siemplify.co"
        }
    ]
}
Entity Enrichment

N/A

Insights

N/A

Case Wall
Result type Value/Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful: "Action successfully returned Google Workspace Directory user list"

If not successful, for example no users were found for the provided Customer ID: "No users were returned."

Action should fail and stop playbook execution:

If a critical error, like wrong credentials or lost connectivity: "Failed to connect to the Google Workspace! Error is {0}".format(exception.stacktrace)

 General
Table

Table Name: Google G Suite Users

Table Columns:

  • Id
  • Email
  • Given Name
  • Family Name
  • Is Admin?
  • Is Delegated Admin?
  • Creation Time
  • Last Login Time
  • Suspended?
  • Archived?
  • Change Password At Next Login?
  • Customer ID
  • Org Unit Path
  • Is Mailbox set?
  • Recovery Email
 General