Google Workspace

This document provides guidance on how to integrate Google Workspace with Google Security Operations SOAR.

Integration version: 17.0

Use cases

Integrating Google Workspace with Google SecOps can help you solve the following use cases:

  • Phishing investigation and remediation: use the Google SecOps capabilities to let the Google Workspace APIs automatically search for and quarantine suspicious emails across all organizational inboxes.

  • User offboarding and account security: use the Google SecOps capabilities to trigger a workflow for revoking the Google Workspace access, suspend accounts, and forward emails for offboarded users to another employee.

  • Malware detection and response: use the Google SecOps capabilities to let the Google Workspace APIs identify the affected files, quarantine them, and analyze their contents and sharing permissions.

  • Data loss prevention (DLP): use the Google SecOps capabilities to monitor for sensitive data being shared inappropriately, revoke sharing permissions, notify the security team, and delete the shared content.

Before you begin

Before configuring the Google Workspace integration in Google SecOps, complete the following prerequisite steps:

  1. Create a service account.
  2. Create a JSON key.
  3. Create a custom role for the integration.
  4. Assign the custom role to a user.
  5. Delegate domain-wide authority to your service account.
  6. Enable the Admin SDK API for your project.

Create a service account

To create a service account, complete the following steps:

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

    Go to Credentials

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

  3. Under Service account details, enter a name in the Service account name field.

  4. Optional: Edit the service account ID.

  5. Click Create and continue. A Grant this service account access to project screen appears.

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

  7. Click Done.

Create a JSON key

To create a JSON key, complete the following steps:

  1. Select your service account and go to Keys.
  2. Click Add key.
  3. Select Create new key.
  4. For the key type, select JSON and click Create. A Private key saved to your computer dialog appears and a copy of the private key downloads to your computer.

Create a custom role for the integration

  1. In the Google Admin console, go to Account > Admin Roles.
  2. Click Create new role.
  3. Provide a name for the new custom role and click Continue.
  4. On the Select Privileges page, go to the Admin API privileges section.

  5. Under Admin API privileges, select the following privileges:

    • Organization Units
    • Users
    • Groups

  6. Click Continue.

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

Assign the custom role to a user

  1. To create a new user, go to Directory > Users page.
  2. Add a new user that is associated with the service account.
  3. Open settings for the newly created user. The user account tab opens.
  4. Click Admin roles and privileges.
  5. Click edit Edit.
  6. Select the custom role you created.
  7. For the selected role, switch the toggle to Assigned.

Delegate domain-wide authority to your service account

  1. From your domain's Google 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://mail.google.com/"
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/admin.directory.user",
"https://www.googleapis.com/auth/admin.directory.group.member",
"https://www.googleapis.com/auth/admin.directory.customer.readonly",
"https://www.googleapis.com/auth/admin.directory.domain.readonly",
"https://www.googleapis.com/auth/admin.directory.group",
"https://www.googleapis.com/auth/admin.directory.orgunit",
"https://www.googleapis.com/auth/admin.directory.user.alias",
"https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly",
"https://www.googleapis.com/auth/apps.groups.settings",
    • To use Google Forms, add the following scope to the scope list: "https://www.googleapis.com/auth/forms.responses.readonly".

  6. Click Authorize.

Enable the 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 SecOps

Use the following parameters to configure the integration:

Parameter Description
Verify SSL Optional

If selected, the integration verifies that the SSL certificate for connecting to Google Workspace is valid.

Selected by default.
User's Service Account JSON Optional

The content of the service account JSON file.
Delegated Email Optional

The email address for the integration to use.
Workload Identity Email Optional

The client email address of your service account.

You can configure either this parameter or the User's Service Account JSON parameter.

To impersonate service accounts with the Workload Identity Federation email address, grant the Service Account Token Creator role to your service account. For more details about workload identities and how to work with them, see Identities for workloads.

For more information about configuring an integration in Google SecOps, see Configure integrations.

You can make changes at a later stage, if necessary. After configuring an instance, you can use it in playbooks. For more information about configuring and supporting multiple instances, see Supporting multiple instances.

Actions

For more information about actions, see Respond to pending actions from your workdesk and Perform a manual action.

Add Members To Group

Use the Add Members To Group action to add users to a group.

This action runs on the User entity.

The Add Members To Group action solves the following use cases:

  • Automated onboarding and offboarding.
  • Incident response by granting temporary access.
  • Dynamic project collaboration.

Action inputs

The Add Members To Group action requires the following parameters:

Parameter Description
Group Email Address Required

An email address of the group to add new members to.

User Email Addresses Optional

A comma-separated list of users to add to the group.

The action executes values that you configure for this parameter alongside the User entity.

Action outputs

The Add Members To 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
Script result Available
Script result

The following table describes the values for the script result output when using the Add Members To Group action:

Script result name Value
is_success True or False

Create Group

Use the Create Group action to create groups for your organization in the Google Admin console, Groups API, or Google Cloud Directory Sync as a Google Workspace Groups administrator.

If you use Groups for Business, you can also create groups for your organization in Google Groups.

This action runs on all Google SecOps entities.

You can use the Create Group action in the following use cases:

  • Create incident response teams.
  • Contain phishing campaigns.
  • Onboard new users and user groups.
  • Collaborate on projects.
  • Configure access control for sensitive data.

Action inputs

The Create Group action requires the following parameters:

Parameter Description
Email Address Required

An email address of the new group.
Name Optional

A name of the new group.
Description Optional

A description of the new group.

Action outputs

The Create 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
Script result Available
JSON result

The following example describes the JSON result output received when using the Create Group action:

[
   {
      "kind":"admin#directory#group",
      "id":"ID",
      "etag":"TAG/var>",
      "email":"user@example.com",
      "name":"example",
      "description":"",
      "adminCreated":"True"
   }
]
Script result

The following table describes the values for the script result output when using the Create Group action:

Script result name Value
is_success True or False

Create OU

Use the Create OU action to create a new organizational unit (OU).

This action runs on all Google SecOps entities.

You can use the Create OU action to solve the following use cases:

  • Onboard new departments.
  • Isolate compromised accounts.
  • Implement geographic-based policies for data residency.

Action inputs

The Create OU action requires the following parameters:

Parameter Description
Customer ID Required

A unique ID of the customer's Google Workspace account.

To configure the account customerId, you can also use the following placeholder: my_customer.
Name Optional

A name of the new organizational unit.
Description Optional

A description of the new organizational unit.
Parent OU Path Required

A full path to the parent OU of a new organizational unit.

Action outputs

The Create OU 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
Script result Available
JSON result

The following example describes the JSON result output received when using the Create OU action:

[
   {
      "kind":"admin#directory#orgUnit",
      "etag":"TAG",
      "name":"example",
      "orgUnitPath":"/example_folder",
      "orgUnitId":"id:ID",
      "parentOrgUnitPath":"/",
      "parentOrgUnitId":"id:ID"
   }
]
Script result

The following table describes the values for the script result output when using the Create OU action:

Script result name Value
is_success True or False

Create User

Use the Create User action to create a new user.

When you add a user to your Google Workspace account, you provide them with an email address at your business domain and an account that they can use to access the Google Workspace services.

This action runs on all Google SecOps entities.

You can use the Create User action to solve the following use cases:

  • Automate onboarding for the new users.
  • Provide temporary access for contract employees.
  • Use sandboxes for incident response.

Action inputs

The Create User action requires the following parameters:

Parameter Description
Given Name Required

The user's first name.
Family Name Required

The user's last name.
Password Required

The password of the new user.
Email Address Required

The primary email address of the user.
Phone Optional

The phone number of the user.
Gender Optional

The gender of the user.

The valid values are as follows: female, male, other, unknown.
Department Optional

The name of the user's department.
Organization Optional

The name of the user's organization.
Change Password At Next Login Optional

If selected, the system demands the user to change their password during the following login attempt.

Not selected by default.

Action outputs

The Create 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
Enrichment table Not available
JSON result Available
Script result Available
JSON result

The following example describes the JSON result output received when using the Create User action:

[
   {
      "kind":"admin#directory#user",
      "id":"ID",
      "etag":"TAG",
      "primaryEmail":"example@example.com",
      "name":{
         "givenName":"FIRST_NAME",
         "familyName":"LAST_NAME"
      },
      "isAdmin":"False",
      "isDelegatedAdmin":"False",
      "creationTime":"2020-12-22T13:44:29.000Z",
      "organizations":[
         {
            "name":"ExampleOrganization"
         }
      ],
      "phones":[
         {
            "value":"(800) 555‑0175"
         }
      ],
      "gender":{
         "type":"male"
      },
      "customerId":"ID",
      "orgUnitPath":"/",
      "isMailboxSetup":"False"
   }
]
Script result

The following table describes the values for the script result output when using the Create User action:

Script result name Value
is_success True or False

Delete Group

Use the Delete Group action to delete a Google Workspace directory group.

This action doesn't run on Google SecOps entities.

You can use the Delete Group action to solve the following use cases:

  • Automate the offboarding of users.
  • Remediate security incidents.
  • Perform cleanups for stale groups.

Action inputs

The Delete Group action requires the following parameters:

Parameter Description
Group Email Address Required

An email address of the group to delete.

Action outputs

The Delete 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 Delete Group action provides the following output messages:

Output message Message description

Google Workspace group GROUP_EMAIL deleted.

Action was not able to find Google Workspace group for deletion.

The action succeeded.
Failed to connect to the Google Workspace! Error is ERROR_DESCRIPTION

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Delete Group action:

Script result name Value
is_success True or False

Delete OU

Use the Delete OU action to delete an organizational unit.

You cannot 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.

This action runs on all Google SecOps entities.

You can use the Delete OU action to solve the following use cases:

  • Automate the offboarding of users.
  • Remediate security incidents.
  • Manage project resources and perform project cleanups.

Action inputs

The Delete OU action requires the following parameters:

Parameter Description
Customer ID Required

A unique ID of the customer's Google Workspace account.

To configure the account customerId, you can also use the following placeholder: my_customer.
OU Path Required

A full path to the organizational unit.

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

Action outputs

The Delete OU 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
Script result Available
Script result

The following table describes the values for the script result output when using the Delete OU action:

Script result name Value
is_success True or False

Delete User

Use the Delete User action to delete user accounts.

After you delete a user, they cannot access or use any Google Workspace services for your organization.

You can use the Delete User action to solve the following use cases:

  • Offboard departing employees.
  • Remediate compromised accounts.
  • Automate the cleanup of temporary accounts.

This action runs on all Google SecOps entities.

Action inputs

The Delete User action requires the following parameters:

Parameter Description
Email Address Required

An email address of the user to delete.

Action outputs

The Delete 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
Enrichment table Not available
JSON result Not available
Script result Available
Script result

The following table describes the values for the script result output when using the Delete User action:

Script result name Value
is_success True or False

Enrich Entities

Use the Enrich Entities action to enrich Google SecOps entities with information from Google Workspace.

This action runs on the User entity.

You can use the Enrich Entities action to solve the following use cases:

  • Investigate users.
  • Analyze phishing emails.
  • Investigate data exfiltration attempts.
  • Detect malware.

Action inputs

None.

Action outputs

The Enrich Entities 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
Script result Available
Entity enrichment

The Enrich Entities action support the following entity enrichment:

Enrichment field name Enrichment logic
Phones Returns if it exists in a JSON result.
isDelegatedAdmin Returns if it exists in a JSON result.
suspended Returns if it exists in a JSON result.
id Returns if it exists in a JSON result.
nonEditableAliases Returns if it exists in a JSON result.
archived Returns if it exists in a JSON result.
isEnrolledIn2Sv Returns if it exists in a JSON result.
includeInGlobalAddressList Returns if it exists in a JSON result.
Relations Returns if it exists in a JSON result.
isAdmin Returns if it exists in a JSON result.
etag Returns if it exists in a JSON result.
lastLoginTime Returns if it exists in a JSON result.
orgUnitPath Returns if it exists in a JSON result.
agreedToTerms Returns if it exists in a JSON result.
externalIds Returns if it exists in a JSON result.
ipWhitelisted Returns if it exists in a JSON result.
kind Returns if it exists in a JSON result.
isEnforcedIn2Sv Returns if it exists in a JSON result.
isMailboxSetup Returns if it exists in a JSON result.
emails Returns if it exists in a JSON result.
organizations Returns if it exists in a JSON result.
primaryEmail Returns if it exists in a JSON result.
name Returns if it exists in a JSON result.
gender Returns if it exists in a JSON result.
creationTime Returns if it exists in a JSON result.
changePasswordAtNextLogin Returns if it exists in a JSON result.
customerId Returns if it exists in a JSON result.
JSON result

The following example describes the JSON result output received when using the Enrich Entities action:

[{
    "Phones":
       [{
          "customType": "",
          "type": "custom",
          "value": "(800) 555‑0175"
       }],
   "isDelegatedAdmin": false,
   "suspended": false,
   "id": "ID",
   "nonEditableAliases": ["user@example.com"],
   "archived": false,
   "isEnrolledIn2Sv": true,
   "includeInGlobalAddressList": true,
   "Relations":
        [{
          "type": "manager",
          "value": "user@example.com"
        }],
   "isAdmin": false,
   "etag": "E_TAG_VALUE",
   "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": "user@example.com"
        },
        {
          "address": "user@example.com"
        }],
    "organizations":
        [{
           "department": "R&D",
           "customType": "", "name": "Company"
         }],
     "primaryEmail": "user@example.com",
     "name":
         {
            "fullName": "NAME SURNAME",
            "givenName": "NAME",
            "familyName": "SURNAME"
         },
     "gender": {"type": "male"},
     "creationTime": "2017-10-26T06:57:13.000Z",
     "changePasswordAtNextLogin": false,
     "customerId": "CUSTOMER_ID"
}]
Script result

The following table describes the values for the script result output when using the Enrich Entities action:

Script result name Value
is_success True or False

Get Group Details

Use the Get Group Details action to retrieve information about a group in Google Workspace.

This action doesn't run on Google SecOps entities.

Action inputs

The Get Group Details action requires the following parameters:

Parameter Description
Group Email Addresses Required

A comma-separated list of group emails to examine.

Action outputs

The Get Group Details 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 describes the JSON result output received when using the Get Group Details action:

{
        "Entity": "group@example.com",
        "EntityResult": {
            "kind": "groupsSettings#groups",
            "email": "group@example.com",
            "name": "GROUP_NAME",
            "description": "DESCRIPTION",
            "whoCanJoin": "CAN_REQUEST_TO_JOIN",
            "whoCanViewMembership": "ALL_MEMBERS_CAN_VIEW",
            "whoCanViewGroup": "ALL_MEMBERS_CAN_VIEW",
            "whoCanInvite": "ALL_MANAGERS_CAN_INVITE",
            "whoCanAdd": "ALL_MANAGERS_CAN_ADD",
            "allowExternalMembers": "false",
            "whoCanPostMessage": "ANYONE_CAN_POST",
            "allowWebPosting": "true",
            "primaryLanguage": "en_US",
            "maxMessageBytes": 26214400,
            "isArchived": "false",
            "archiveOnly": "false",
            "messageModerationLevel": "MODERATE_NONE",
            "spamModerationLevel": "MODERATE",
            "replyTo": "REPLY_TO_IGNORE",
            "includeCustomFooter": "false",
            "customFooterText": "",
            "sendMessageDenyNotification": "false",
            "defaultMessageDenyNotificationText": "",
            "showInGroupDirectory": "true",
            "allowGoogleCommunication": "false",
            "membersCanPostAsTheGroup": "false",
            "messageDisplayFont": "DEFAULT_FONT",
            "includeInGlobalAddressList": "true",
            "whoCanLeaveGroup": "ALL_MEMBERS_CAN_LEAVE",
            "whoCanContactOwner": "ANYONE_CAN_CONTACT",
            "whoCanAddReferences": "NONE",
            "whoCanAssignTopics": "NONE",
            "whoCanUnassignTopic": "NONE",
            "whoCanTakeTopics": "NONE",
            "whoCanMarkDuplicate": "NONE",
            "whoCanMarkNoResponseNeeded": "NONE",
            "whoCanMarkFavoriteReplyOnAnyTopic": "NONE",
            "whoCanMarkFavoriteReplyOnOwnTopic": "NONE",
            "whoCanUnmarkFavoriteReplyOnAnyTopic": "NONE",
            "whoCanEnterFreeFormTags": "NONE",
            "whoCanModifyTagsAndCategories": "NONE",
            "favoriteRepliesOnTop": "true",
            "whoCanApproveMembers": "ALL_MANAGERS_CAN_APPROVE",
            "whoCanBanUsers": "OWNERS_AND_MANAGERS",
            "whoCanModifyMembers": "OWNERS_AND_MANAGERS",
            "whoCanApproveMessages": "OWNERS_AND_MANAGERS",
            "whoCanDeleteAnyPost": "OWNERS_AND_MANAGERS",
            "whoCanDeleteTopics": "OWNERS_AND_MANAGERS",
            "whoCanLockTopics": "OWNERS_AND_MANAGERS",
            "whoCanMoveTopicsIn": "OWNERS_AND_MANAGERS",
            "whoCanMoveTopicsOut": "OWNERS_AND_MANAGERS",
            "whoCanPostAnnouncements": "OWNERS_AND_MANAGERS",
            "whoCanHideAbuse": "NONE",
            "whoCanMakeTopicsSticky": "NONE",
            "whoCanModerateMembers": "OWNERS_AND_MANAGERS",
            "whoCanModerateContent": "OWNERS_AND_MANAGERS",
            "whoCanAssistContent": "NONE",
            "customRolesEnabledForSettingsToBeMerged": "false",
            "enableCollaborativeInbox": "false",
            "whoCanDiscoverGroup": "ALL_IN_DOMAIN_CAN_DISCOVER",
            "defaultSender": "DEFAULT_SELF"
        }
    }
Output messages

The Get Group Details action provides the following output messages:

Output message Message description

Successfully enriched the following groups using information from Google Workspace: GROUPS

Action wasn't able to enrich the following group using information from Google Workspace: GROUPS

None of the groups were enriched.

 The action succeeded.
Error executing action "Get Group Details". Reason: ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Get Group Details action:

Script result name Value
is_success True or False

List Group Members

Use the List Group Members action to list the members of a Google Workspace group.

This action runs on all Google SecOps entities.

You can use the List Group Members action to solve the following use cases:

  • Automate user onboarding and offboarding.
  • Perform a security audit.
  • Respond to incidents.
  • Support the dynamic resource access.

Action inputs

The List Group Members action requires the following parameters:

Parameter Description
Group Email Address Required

An email address of the group.
Include Derived Membership Optional

If selected, the action lists indirect memberships of users in the group.

Selected by default.

Action outputs

The List Group Members 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
Script result Available
JSON result

The following example describes the JSON result output received when using the List Group Members action:

{
   "status": "ACTIVE",
   "kind": "admin#directory#member",
   "email": "user1@example.com",
   "etag": "E_TAG_VALUE",
   "role": "MEMBER",
   "type": "USER",
   "id": "ID"
  },{
   "status": "ACTIVE",
   "kind": "admin#directory#member",
   "email": "user2@example.com",
   "etag": "E_TAG_VALUE",
   "role": "MEMBER",
   "type": "USER", "id": "ID"
}
Script result

The following table describes the values for the script result output when using the List Group Members action:

Script result name Value
members True or False

List Group Privileges

Use the List Group Privileges action to list roles and privileges that are related to the Google Workspace group.

This action doesn't run on Google SecOps entities.

Action inputs

The List Group Privileges action requires the following parameters:

Parameter Description
Group Email Addresses Optional

A comma-separated list of groups to examine.
Check Roles Optional

A comma-separated list of roles to check that are related to the group.
Check Privileges Optional

A comma-separated list of permissions that to check that are related to the group.

This parameter requires you to select the Expand Privileges parameter. If you configured the Check Roles parameter, the action checks the privileges only for the roles that you listed.
Expand Privileges Optional

If selected, the action returns information about all unique privileges that are related to the group.
Max Roles To Return Required

The maximum number of roles that are related to the group to return.

The default value is 100.
Max Privileges To Return Required

The maximum number of privileges that are related to the group to return.

The default value is 100.

Action outputs

The List Group Privileges 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 describes the JSON result output received when using the List Group Privileges action:

{
    "Entity": "user@example.com",
    "EntityResult": {
        "roles": [
            "Role1",
            "_GROUPS_EDITOR_ROLE",
            "example-role"
        ],
        "unique_privileges": [
            "VIEW_SITE_DETAILS",
            "ACCESS_EMAIL_LOG_SEARCH",
            "ACCESS_ADMIN_QUARANTINE",
            "ACCESS_RESTRICTED_QUARANTINE",
            "ADMIN_QUALITY_DASHBOARD_ACCESS",
            "MANAGE_DLP_RULE",
            "DASHBOARD_ACCESS",
            "MANAGE_GSC_RULE",
            "VIEW_GSC_RULE",
            "SECURITY_HEALTH_DASHBOARD_ACCESS",
            "SIT_CALENDAR_VIEW_METADATA",
            "SIT_CHAT_VIEW_METADATA",
            "SIT_CHROME_VIEW_METADATA",
            "SIT_DEVICE_UPDATE_DELETE",
            "SIT_DEVICE_VIEW_METADATA",
            "SIT_DRIVE_UPDATE_DELETE"
        ]
    }
}
Output messages

The List Group Privileges action provides the following output messages:

Output message Message description

Successfully fetched information for the following groups using information from Google Workspace: GROUPS

Action wasn't able to fetch information for the following groups using information from Google Workspace: GROUPS

None of the specific roles/privileges were found for the following groups in Google Workspace: GROUPS

None of the specific roles/privileges were found for the provided groups in Google Workspace.

No information was found for the provided groups in Google Workspace.

 The action succeeded.
Error executing action "List Group Privileges". Reason: ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the List Group Privileges action:

Script result name Value
is_success True or False

List OU of Account

Use the List OU of Account action to list organizational units of an account.

This action runs on all Google SecOps entities.

You can use the List OU of Account action to solve the following use cases:

  • Automate user offboarding.
  • Perform a targeted security auditing.
  • Automate a group membership management.
  • Streamline user provisioning.
  • Automate compliance reporting and auditing.

Integration inputs

The List OU of Account action requires the following parameters:

Parameter Description
Customer ID Required

A unique ID of the customer Google Workspace account.

To represent the customerId value of the account, use the my_customer placeholder.

Action outputs

The List OU of 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 Available
Script result Available
JSON result

The following example describes the JSON result output received when using the List OU of Account action:

[{
   "kind": "admin#directory#orgUnit",
   "parentOrgUnitPath": "/",
   "name": "OU-1",
   "etag": "E_TAG_VALUE",
   "orgUnitPath": "/OU-1",
   "parentOrgUnitId": "id:1455",
   "blockInheritance": false,
   "orgUnitId": "id:123",
   "description": ""
}]
Script result

The following table describes the values for the script result output when using the List OU of Account action:

Script result name Value
organizational_units True or False

List User Privileges

Use the List User Privileges action to list roles and privileges that are related to the user in Google Workspace.

This action runs on the Google SecOps User entity.

Action inputs

The List User Privileges action requires the following parameters:

Parameter Description
User Email Addresses Optional

A comma-separated list of users to examine.

The action executes values that you configure for this parameter alongside the User entity.
Check Roles Optional

A comma-separated list of roles to check that are related to the user.
Check Privileges Optional

A comma-separated list of permissions that to check that are related to the user.

This parameter requires you to select the Expand Privileges parameter. If you configured the Check Roles parameter, the action checks the privileges only for the roles that you listed.
Include Inherited Roles Optional

If selected, the action additionally returns user roles that are inherited from groups.
Expand Privileges Optional

If selected, the action returns information about all unique privileges that are related to the user.
Max Roles To Return Required

The maximum number of roles that are related to the user to return.

The default value is 100.
Max Privileges To Return Required

The maximum number of privileges that are related to the user to return.

The default value is 100.

Action outputs

The List User Privileges 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 describes the JSON result output received when using the List User Privileges action:

{
    "Entity": "user@example.com",
    "EntityResult": {
        "roles": [
            "Role1",
            "_GROUPS_EDITOR_ROLE",
            "example-role"
        ],
        "unique_privileges": [
            "VIEW_SITE_DETAILS",
            "ACCESS_EMAIL_LOG_SEARCH",
            "ACCESS_ADMIN_QUARANTINE",
            "ACCESS_RESTRICTED_QUARANTINE",
            "ADMIN_QUALITY_DASHBOARD_ACCESS",
            "MANAGE_DLP_RULE",
            "DASHBOARD_ACCESS",
            "MANAGE_GSC_RULE",
            "VIEW_GSC_RULE",
            "SECURITY_HEALTH_DASHBOARD_ACCESS",
            "SIT_CALENDAR_VIEW_METADATA",
            "SIT_CHAT_VIEW_METADATA",
            "SIT_CHROME_VIEW_METADATA",
            "SIT_DEVICE_UPDATE_DELETE",
            "SIT_DEVICE_VIEW_METADATA",
            "SIT_DRIVE_UPDATE_DELETE"
        ]
    }
}
Output messages

The List User Privileges action provides the following output messages:

Output message Message description

Successfully enriched the following users using information from Google Workspace: USERS

Action wasn't able to enrich the following users using information from Google Workspace: USERS

None of the specific roles/privileges were found for the following users in Google Workspace: USERS

None of the specific roles/privileges were found for the provided users in Google Workspace.

None of the provided users were enriched in Google Workspace.

The action succeeded.
Error executing action "List User Privileges". Reason: ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the List User Privileges action:

Script result name Value
is_success True or False

List Users

Use the List Users action to list users present in an account.

This action doesn't run on Google SecOps entities.

You can use the List Users action to solve the following use cases:

  • Identify potentially compromised accounts.
  • Automate offboarding processes.
  • Audit and manage user access privileges
  • Investigate suspicious activities.
  • Manage user licenses and resources.

Action inputs

The List Users action requires the following parameters:

Parameter Description
Customer ID Optional

A unique ID of the customer Google Workspace account.

If you don't provide this parameter value, the action automatically uses the my_customer placeholder to represent a customer ID of the account.
Domain Optional

A domain to search for users in.
Manager Email Optional

An email address of a user's manager.
Return Only Admin Accounts? Optional

If selected, the action returns only administrator accounts.

Not selected by default.
Return Only Delegated Admin Accounts? Optional

If selected, the action returns only delegated administrator accounts.

Not selected by default.
Return Only Suspended Users? Optional

If selected, the action returns only suspended accounts.

Not selected by default.
Org Unit Path Optional

A full path of an organization unit to retrieve the users from. The path matches all organization unit chains listed under the target unit.
Department Optional

A department within the organization to retrieve the users from.
Record Limit Optional

The maximum number of data records for the action to return.

The default value is 20.
Custom Query Parameter Optional

A custom query parameter to add to the list users search call, such as orgName='Human Resources'.

You can configure this parameter with the email field, or leave the email field empty and configure the Email Addresses parameter. If you configure both the email field and the Email Addresses parameter, the generated query fails.
Return only users without 2fa? Optional

If selected, the action only returns users that don't have the two-factor authentication (2FA) enabled.

Not selected by default.
Email Addresses Optional

A comma-separated list of email addresses to search for.

If you configure this parameter, don't configure the email field in the Custom Query Parameter parameter.

If you configure this parameter, the action ignores the Record Limit parameter.

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
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
Case wall table

The List Users action provides the following table on a Case Wall:

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
JSON result

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

{
    "kind": "admin#directory#users",
    "etag": "E_TAG_VALUE",
    "users": [
        {
            "kind": "admin#directory#user",
            "id": "ID",
            "etag": "E_TAG_VALUE",
            "primaryEmail": "user@example.com",
            "name": {
                "givenName": "NAME",
                "familyName": "SURNAME",
                "fullName": "NAME SURNAME"
            },
            "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": "user@example.com",
                    "primary": true
                },
                {
                    "address": "user@example.com"
                }
            ],
            "nonEditableAliases": [
                "user@example.com"
            ],
            "customerId": "CUSTOMER_ID",
            "orgUnitPath": "/Management",
            "isMailboxSetup": true,
            "isEnrolledIn2Sv": false,
            "isEnforcedIn2Sv": false,
            "includeInGlobalAddressList": true,
            "recoveryEmail": "email@example.com"
        }
    ]
}
Output messages

The List Users action provides the following output messages:

Output message Message description

Action successfully returned the Google Workspace Directory user list.

No users were returned.

 The action succeeded.
Failed to connect to the Google Workspace! Error is ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values 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 connectivity to Google Workspace.

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
Script result Available
Script result

The following table describes the values for the script result output when using the Ping action:

Script result name Value
is_success True or False

Remove Members From Group

Use the Remove Members From Group action to remove members from a Google Workspace group.

This action runs on the Google SecOps User entity.

You can use the List Users action to solve the following use cases:

  • Automate user offboarding.
  • Execute dynamic group management.
  • Remediate access control issues.

Action inputs

The Remove Members From Group action requires the following parameters:

Parameter Description
Group Email Address Required

An email of the group to remove the members from.

User Email Addresses Optional

A comma-separated list of users to remove from the group.

The action executes values that you configure for this parameter alongside the User entity.

Action outputs

The Remove Members From 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
Script result Available
Script result

The following table describes the values for the script result output when using the Remove Members From Group action:

Script result name Value
is_success True or False

Update OU

Use the Update OU action to update an organizational unit.

This action runs on all Google SecOps entities.

You can use the Update OU action to solve the following use cases:

  • Manage security groups.
  • Automate onboarding and offboarding of users.
  • Implement data separation policies.

Action inputs

The Update OU action requires the following parameters:

Parameter Description
Customer ID Required

A unique ID of the customer Google Workspace account.

To represent the customerId value of the account, use the my_customer placeholder.
Name Optional

A name of the organizational unit.
Description Optional

A description of the organizational unit.
OU Path Required

A full path to the organizational unit.

If the organizational unit is located under the root path, /, provide only the organizational unit name without a path.

Action outputs

The Update OU 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
Script result Available
Script result

The following table describes the values for the script result output when using the Update OU action:

Script result name Value
is_success True or False

Update User

Use the Update User action to update a Google Workspace directory user.

This action doesn't run on Google SecOps entities.

You can use the Update User action to solve the following use cases:

  • Disable a compromised account.
  • Enforce a password reset after detecting suspicious activity.
  • Update department information after completing an employee transfer.
  • Suspend inactive accounts.

Action inputs

The Update User action requires the following parameters:

Parameter Description
Email Address Required

A comma-separated list of primary email addresses that are used to identify what users to update.
Given Name Optional

The user's first name.
Family Name Optional

The user's last name.
Password Optional

The password of the new user.
Phone Optional

The phone number of the user.

The action updates the custom phone number type.
Gender Optional

The gender of the user.

The valid values are as follows: female, male, other, unknown.
Department Optional

The name of the user's department.
Organization Optional

The name of the user's organization.
Change Password At Next Login Optional

If selected, the system demands the user to change their password during the following login attempt.

Not selected by default.
User Status Optional

The user status to update to.

By default, the action doesn't change the user status.

The possible values are as follows:
  • Not Changed
  • Blocked
  • Unblocked

Action outputs

The Update 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
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Update User action provides the following output messages:

Output message Message description

Successfully updated the following users in Google Workspace: EMAIL_ADDRESSES.

Action wasn't able to update the following users in Google Workspace: EMAIL_ADDRESSES

None of the provided users were updated.

 The action succeeded.
Error executing action "Update User". Reason: ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Update User action:

Script result name Value
is_success True or False