Google Workspace Integration

11/2023

Cisco Identity Intelligence can analyze data from Google Workspace (formerly G Suite) and Google Cloud Platform (GCP) to provide insights into user identities and application activity. This document will walk you through the process of setting up the CII Google Workspace integration.

Note: This integration uses both a Google Workspace admin user (required for access to Google Workspace Admin APIs), and a GCP service account (required for access to view service accounts and logs in GCP). To avoid confusion, please note the bolded terms used throughout these instructions and make sure you're using the right one.

Overview

These are the steps to connect Identity Intelligence to your Google Workspace environment. The steps summarized here are explained in more detail in the linked sections below.

  1. Configure a Google Workspace admin user and role for CII to use. This is required for directory access and Google Workspace audit logs.

  2. Configure a GCP service account with Security Reviewer, Log Viewer, Private Log Viewer, and Browser roles at the org level. Configure Domain-Wide-delegation for this service account for the required scopes (documented below) so that it can access the Google Workspace admin user created in Step 1. Generate a key for this service account for CII to use. This allows CII to monitor service account activity within your google projects.

  3. Create a Google Workspace integration in your CII tenant using your Google Workspace customer ID as well as the email of the Google Workspace admin user from step 1 and the GCP service account key from step 2.

  4. Configure GCP Audit Logging at the project, folder, or organization level in GCP to start generating logs for CII to monitor.

If you are unsure, refer to the configuration checklist at the end of this page.

Configure a Google Workspace Admin User and Role

This is where you will set up the Google Workspace admin user. For this step you will need administrator access to your Google Workspace account.

  1. In the Google Workspace Admin console, create a new account for the Service account to impersonate. Save this user's email for use in the following steps and in the CII setup section. Use this user email whenever these instructions refer to the Google Workspace admin user.

  2. In the Google Workspace Admin console, create a custom role:

    1. Navigate to Account > Admin roles > Create new role

    2. Provide a name and description

    3. Under Admin console privileges check the following privileges 

      Organizational Units > Read
Users > Read
Services > Mobile Device Management > Manage Devices and Settings
Services > Chrome Management > Settings > Manage Chrome OS Devices > Read
Security > User Security Management

    4. Under Admin API privileges check the following privileges 

      Reports
Organizational Units > Read
Users > Read
Groups > Read
User Security Management

  3. When all the permissions have been added, select Create Role to finish.

  4. Assign this role to the Google Workspace admin user.

Configure a GCP service account

In this step you will configure the GCP service account. For this step you will need admin access to your GCP organization.

  1. Login to the GCP console for your organization. Using the project selector, choose or create a project to host the service account that CII will use for access.

  2. Navigate to the APIs and Services tool under Google Cloud -> APIs and Services -> Enable APIs and Services

  3. Search for Admin API SDK and select Enable.

  1. Also enable the Cloud Resource Manager API, the Cloud Logging API and the Identity and Access Management (IAM) API.

  2. Create a GCP service account for CII to use. Navigate to IAM > Service Accounts > Create Service Account.

  1. Provide a name and description for the account

  1. Choose Add Key > Create New Key on the GCP service account you just made. Store the downloaded key file somewhere safe; you will need to upload it to CII when you set up the integration in CII.

  1. Note the Unique ID / OAuth2 client ID for use in the next section when you delegate domain authority for the Workspace API

  2. Delegate domain-wide authority to the Google Cloud service account created in the GCP section above, as explained in the following Google docs: https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority

  3. Click Add New

  4. In the OAuth scopes (comma-delimited) field,

    1. Add the Client ID for the GCP service account created in the section above, which is tied to the JSON keys downloaded.

    2. Add the scopes in the code block below. Click Authorize. 

    https://www.googleapis.com/auth/admin.directory.group.member.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,https://www.googleapis.com/auth/admin.directory.orgunit.readonly,https://www.googleapis.com/auth/admin.directory.device.mobile.readonly,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/logging.read

Below are links for reference:

https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly, https://www.googleapis.com/auth/admin.directory.orgunit.readonly, https://www.googleapis.com/auth/admin.directory.device.mobile.readonly, https://www.googleapis.com/auth/admin.reports.audit.readonly, https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly, https://www.googleapis.com/auth/admin.directory.user.security, https://www.googleapis.com/auth/logging.read (for collecting Logging data) Note that the admin.directory.user.security scope that is listed is required to use Remediation Actions for Google accounts within Identity Intelligence.

  1. Navigate to the IAM panel on the sidebar, and use the project selector to select the organization (top-level) context. Note that on the project picker it says "Organization" in the Type column for the correct resource. When you are on the right page you should see that it says "Permissions for organization <your organization>".

  1. Click Grant Access at the top of the table.

  2. In the access form, enter the email address of the GCP service account in the New principals field, and assign the roles Logs Viewer, Private Logs Viewer, Security Reviewer and Browser. Click Save.

Create a Google Workspace integration in your Identity Intelligence tenant

  1. From the Integrations page, click Add Integration and select Google Workspace

  2. Enter a name for the integration, such as Google-customername

  3. Enter your unique Google Workspace or Cloud customer ID. Note - You can find this ID in your Admin console: Account > Account settings > Profile

  4. Enter the email Google Workspace admin user that the service account is impersonating

  5. Upload the JSON key file created for the GCP service account.

  6. Select Save. This will trigger an initial connectivity test.

Test the Configuration

To test the configuration and start the initial data collection -

  1. Click the 3 dots at the right of the new Google integration and select Test Connectivity

  2. Once successful, click the 3 dot menu again and select Collect Now. Collection may take some time, depending on the size of the Google environment

Enable GCP Audit Logging

Not all service account activity is logged by default in GCP. Refer to the GCP documentation to configure your audit logging according to your needs at the project, folder, or organization level. CII uses these logs as indicators of service account activity.

Updating Google Service Account Keys

If desired, the JSON keys created for the service account can be rotated or updated.

  1. Create new keys for the GCP service account.

  2. In the Identity Intelligence console, select the 3 dot menu for the Google integration and select Edit Settings

  3. Select Reset Credentials. Then upload the new JSON file and click Save

  4. Test connectivity to ensure a successful connection

Configuration Checklist

If you are not seeing data or account activity that you expect to see, these are the things to check:

GCP Service Account

  1. The GCP service account has been created in a GCP project.

  2. The GCP service account has been given the Security Reviewer, Browser, Private Logs Viewer, and Logs Viewer roles at the organization level in IAM in GCP.

  3. The key for the GCP service account that CII is using is still present and enabled in GCP IAM for its project.

  4. The GCP service account has been given Domain-Wide-Delegation with the scopes listed above.

  5. The Cloud Resource Manager API, the Cloud Logging API and the Identity and Access Management (IAM) API have been enabled in the project that hosts the GCP service account.

Google Workspace admin user

  1. The Google Workspace admin user has been created.

  2. The Google Workspace admin role has been created and has the permissions listed above.

  3. The Google Workspace admin role has been assigned to the Google Workspace admin user.

CII Configuration

  1. The Google Customer ID has been entered correctly. Note that there can only be one integration per Google Customer ID in a CII tenant.

  2. The email of the Google Workspace admin user has been entered correctly and exactly matches the user currently intended.

  3. The service account key for the GCP service account that CII is using is currently enabled in GCP. If in any doubt, generate a new key in the GCP console and upload it to CII.

GCP Audit Logging

  1. GCP Audit Logging has been configured at the desired level of the GCP organizational hierarchy (organization, folder, or project) and at the desired level of detail.

PreviousGithubNextJamf

Last updated