Google Workspace Integration

8/2022 - rev 2

Overview

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.

Goal

The goal of this document is to serve as a guide to set up a Google Workspace integration in Oort so that the Oort Cloud service can ingest authentication events and user directory information.   

Audience

This document is meant for the CISO to share with their teams to set up the integration with Google Workspace that Oort will use to provide analysis on user identities.

Next Steps

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.

Google Workspace Integration

Google Workspace has different activity log types which each contain different sets of information.

• Directory - User and group information
• Activity - User sign-in and application activity

Google Workspace Log Availability

Activity logs are available for the past 30 days.

On subsequent log collections, Oort will ingest only the latest logs.

High-level Setup Steps

There are 3 high-level steps you need to go through to set up your Google Workspace infrastructure and then connect it to Oort.

1. Create a Service account in GCP
2. Obtain a JSON key for the Service account just created in GCP
3. Determine an Admin account for the Service account to impersonate in Google Workspaces.
4. Configure domain-wide delegation and assign the necessary scopes in Google Workspaces
5. Configure the Google Workspace integration with the Admin account and key in the Oort console.

Detailed Configuration Steps - Google Cloud

1. Create a Service account in the Google Cloud Platform (GCP) for the purposes of the integration.

   

2. 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

3. In Google Workspace, create a new or choose an existing administrator account for the Service account to impersonate. In order to collect device data along with user account and activity data, this administrator account must have the Super Admin Role.

   Note - This account will only be used to delegate access to read specific metadata only, as determined by the specific scopes below.

4. Delegate domain-wide authority to the service account as explained in
   
   https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority
   In the OAuth scopes (comma-delimited) field, add the following:

   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

Detailed Configuration Steps - Oort Platform

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 administrator account that the service account is impersonating.

5. Upload the JSON key file created for the service account in the steps above.

6. Click Save.

   

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.

   

Updating Google Service Account Keys

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.