Google Workspace Integration
11/2023
Overview
Identity Intelligence can analyze data from Google Workspace (formerly G Suite) to provide insights into user identities and application activity in that platform.
This document will walk you through the process of setting up API access from Google Workspace and Google Cloud Platform (GCP) to Identity Intelligence.
Next Steps
Once the integration is complete and the Identity Intelligence platform has completed the analysis of the data, Identity Intelligence will set up a review with you and your team to share insights discovered through the integration.
Google Workspace Integration
Google Workspace has two APIs in use for this integration -
Directory API - Manage your organization’s users, connected devices, and third-party applications.
Reports API - Generate reports about customers and user usage.
Understanding Identity Intelligence Read and Write API Permissions
There are two groups of API permissions or OAuth scopes that can be used with your Identity Intelligence tenant and Google Workspace -
Read-only - used for data ingestion and analysis only
Read/write (which includes the first set of read-only scopes) - read/write permissions are used for the defined list of Identity Intelligence Remediation Actions.
Remediation actions can only be taken by administrator or help desk roles in Identity Intelligence and are limited to the list in the above article.
High-level Setup Steps
There are 3 separate sets of configurations required to connect Identity Intelligence to your Google Workspace environment.
Google Cloud (GCP) configuration
Google Workspace configuration
Identity Intelligence integration setup and testing
Google Cloud (GCP) - Detailed Configuration Steps
Login to the GCP console for your organization.
NOTE - the GCP admin account you use for these steps must have permissions to the Project you want to use (see steps 3-6 below) AND it must have the
iam.serviceAccountKeys.create
permission.
GCP Project - The steps below must occur within a specific GCP project. It doesn't make a difference in which project the Identity Intelligence integration service account and Admin API SDK are enabled, as long as the steps below in this section can be completed. If you prefer for the Admin API SDK to be enabled in it's own project, then create a new, specific project in GCP for this integration. Otherwise, simply select an existing project.
If the Google Admin API SDK is not enabled for your tenant, please enable it. For information, see this Google Cloud article. This is found under Google Cloud -> APIs and Services -> Enable APIs and Services
Search for Admin API SDK via the search bar, find the corresponding SDK box and select Enable
If Google Cloud Projects are not already enabled for your tenant, please enable it to ensure that Identity Intelligence can collect and report on GCP Service Account data. To do so, you will need to enable 2 additional APIs:
Search for Cloud Logging API via the search bar. Find the corresponding SDK box and select Enable
Search for Identity and Access Management (IAM) API via the search bar. Find the corresponding SDK box and select Enable
Create a Service account in the Google Cloud Platform (GCP) for the purposes of the integration
Provide a name and description for the account
From the Service Account that was created in GCP, create keys, which are downloaded as a JSON file when created. Save this JSON file, as it will be added to the Identity Intelligence integration instance
Note the Unique ID / OAuth2 client ID for use in the next section when you delegate domain authority for the Workspace API
Google Workspace - Detailed Config Steps
In Google Workspace (admin.google.com), create a new account or choose an existing administrator account for the Service account to impersonate Note - if you elect to use an existing account in Workspace, you will need to be able to give it the role you create below
Create a custom role via the following steps:
Navigate to Account > Admin roles > Create new role
Provide a suitable name and description
Under
Admin console privileges
check the following privilegesOrganizational 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 Security > Reports
Under
Admin API privileges
check the following privilegesOrganizational Units > Read Users > Read Groups > Read User Security Management
When all the roles have been added, select Create Role to finish.
Assign this role to the account that was created above in Workspace or the existing account.
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
Click Add New
In the OAuth scopes (comma-delimited) field,
Add the Oauth2 Client ID for the GCP service account created in the section above, which is tied to the JSON keys downloaded.
Add the following scopes using this 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/iam, 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/iam (for collecting service accounts)
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.
Identity Intelligence Integration - Detailed Configuration Steps
Once you have completed the steps above, you can configure the Google Integration within Identity Intelligence
From the Integrations page, click Add Integration and select Google Workspace
Enter a name for the integration, such as Google-customername
Enter your unique Google Workspace or Cloud customer ID. Note - You can find this ID in your Admin console: Account > Account settings > Profile
Enter the user principal name of the Google Workspace administrator account that the service account is impersonating
Upload the JSON key file created for the service account in the step 8 of the Google Cloud (GCP) - Detailed Configuration Steps section above
Select Save
Test the Configuration
To test the configuration and start the initial data collection -
Click the 3 dots at the right of the new Google integration and select Test Connectivity
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
Updating Google Service Account Keys
If desired, the JSON keys created for the service account can be rotated or updated.
Simply create new keys for that service account in the Google Cloud console and save as a JSON file
In the Identity Intelligence console, select the 3 dot menu for the Google integration and select Edit Settings
Select Reset Credentials. Then upload the new JSON file and click Save
Test connectivity to ensure a successful connection
Last updated