Comment on page
Google Workspace Integration
Oort 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 Oort.
Once the integration is complete and the Oort platform has completed the analysis of the data, Oort will set up a review with you and your team to share insights discovered through the integration.
- Directory API - Manage your organization’s users, connected devices, and third-party applications.
- Reports API - Generate reports about customers and user usage.
There are two groups of API permissions or OAuth scopes that can be used with your Oort tenant and Google Workspace -
Remediation actions can only be taken by administrator or help desk roles in Oort and are limited to the list in the above article.
There are 3 separate sets of configurations required to connect Oort to your Google Workspace environment.
- 2.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
- 3.GCP Project - The steps below must occur within a specific GCP project. It doesn't make a difference in which project the Oort 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.
- 4.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
- 5.Type in Admin API SDK in the search bar and click the corresponding SDK box
- 6.Click Enable
- 7.Create a Service account in the Google Cloud Platform (GCP) for the purposes of the integration.
- 8.Provide a name and description for the account
- 9.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 Oort integration instance
- 10.Note the Unique ID / Oauth2 client ID for use in the next section when you delegate domain authority for the Workspace API
- 1.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.
- 2.Create a custom role via the following steps:
- 1.Navigate to Account > Admin roles > Create new role
- 2.Provide a suitable name and description
Admin console privilegescheck the following privilegesOrganizational Units > ReadUsers > ReadServices > Mobile Device Management > Manage Devices and SettingsServices > Chrome Management > Settings > Manage Chrome OS Devices > ReadSecurity > User Security ManagementSecurity > Reports
Admin API privilegescheck the following privilegesOrganizational Units > ReadUsers > ReadGroups > ReadUser Security Management
- 3.When finished, the role should look like this -Click Create Role to finish.
- 4.Assign this role to the account that was created in Workspace or the existing account.
- 5.Delegate domain-wide authority to the Google Cloud service account created in the GCP section above, as explained in https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority
- 6.Click Add New
- 7.In the OAuth scopes (comma-delimited) field,
- 1.Add the Oauth2 Client ID for the GCP service account created in the section above, which is tied to the JSON keys downloaded.
- 2.Add the following scopes using this code block below. Click Authorize.
- 8.Hit View Details for the API client created and confirm it looks as shown:
Here is the list 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 Note that the last one listed is required for Oort Remediation Actions.
- 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 user principal name of the Google Workspace administrator account that the service account is impersonating.
- 6.Click Save.
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.
If desired, the JSON keys created for the service account can be rotated or updated.
- 1.Simply create new keys for that service account in the Google Cloud console and save as a JSON file.
- 2.In the Oort console, click 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.