Google Workspace

About this document

This document gives you the step-by-step procedure to configure Google Workspace in SAFE.

Prerequisites

To configure Google Workspace integration with SAFE, the user needs to provide the service account key.

Configuring and Assessing Google Workspace

Step 1: Creating a Project

1. Login to the GCP console at https://console.cloud.google.com.
   
2. Click on the dropdown menu on the top left of the page, located between the “Google Cloud Platform” label and the search bar.
3. The system lists the hierarchical structure of the organization and all the existing folders and projects within it. Here, click the New Project button to create a new project.
   
4. Add a name for the new Project (for example: GW SAFE Security).
   
   

Step 2: Enabling API Services on the Project

1. On the Project’s dashboard, click the options menu icon available at the top left corner and then scroll down to click on APIs & Services.
   
2.  On the APIs and Services dashboard, click on Enable APIs and Services at the top of the page, to go to the APIs Library page.
3.  Search for Admin SDK API in the API Library search bar. Click on the link of the Admin SDK API in the search results.
   
4. Click the Enable button. Once the process is complete, it can be verified by revisiting the above page. Now there should be a label reading API Enabled.
   
5. Repeat the previous two steps to enable the following APIs:
   1. Google Calendar API
   2. Gmail API
   3. Groups Settings API
6. Verify that all the required APIs have been enabled.
   

Step 3: Creating a Service Account

1. From the Project’s dashboard, click on the left navigation and scroll down to click on IAM & Admin.
   
2. Click the Service Accounts option and then click the CREATE SERVICE ACCOUNT button.
3.  Enter a name for the service account and click on CREATE AND CONTINUE.
   
4. Choose the Viewer role and the Security Reviewer role to assign at least reader permissions to the service account.
   
5. Click Continue and then click Done.
6. Under Service Accounts, click the Created Service Account button. From the Actions column, click the Manage Keys or Create key option.
   
   
7. Click on the Keys tab.
8. Click on ADD KEY and then on Create new key.
   
9. Select the Key type JSON.
10. Click the CREATE button, and keep the file downloaded in a file on your system.
    

Step 5: Granting domain-wide access to the Service Account

Note- This step needs to be carried out by a Google Workspace administrator of the domain.

1. Sign in to the Google Workspace Admin portal at https://admin.google.com.
2. Go to Main menu > Security > Access and data control >  API Controls.
   
3. In the Domain-wide delegation page, select Manage Domain-Wide Delegation.
4. Click Add New.
   
5. Go to GCP > Enter the service account's Client ID. You can find your service account's client ID on the Service Accounts page.
   
6. In the OAuth scopes (comma-delimited) field, Add the following:
   1. https://www.googleapis.com/auth/calendar,
   2. https://www.googleapis.com/auth/admin.directory.group.readonly,
   3. https://www.googleapis.com/auth/admin.directory.user.readonly,
   4. https://www.googleapis.com/auth/admin.directory.user.security,
   5. https://www.googleapis.com/auth/gmail.readonly,
   6. https://www.googleapis.com/auth/apps.groups.settings

Configuring the Google Workspace integration

1. Sign in to SAFE and navigate to integrations.
2. Click the Google Workspace card and go to the configuration page.
3. Enter the connection details:
   1. Organization Domain - This is the organization's domain from which to sync the data.
   2. Client Email - This is the client email ID of the service account.
   3. Private Key - The private key of the service account (All the text in the private key field)
   4. Super Admin Email - The email ID of the super admin of the organization (This administrator account must have the Super Admin Role. Note - This account will only be used to delegate access to read specific metadata only)
4. If required, mark the "Auto Onboard New Users" and the "Update Existing Users Metadata" checkboxes.
5. Click the Test Connection button.
6. Once the connection is verified, click the Save button to save the configuration.
7. Click the Sync Now button available at the bottom-right corner of the screen.

View Results

Finding View and Asset Views are availabe on the integration page.

Findings View: This tab displays all the findings details pulled from the Google Workspace.

Assets View: This tab displays all the assets pulled from Google Workspace.

FAQs

How can I check the Sync status for Google Workspace Integration?

To view the information related to any saved configuration GET /integrations/:instance_id can be used. It will return all config fields except the fields which are encrypted using the "sensitiveFields" array. It will also return the information regarding the config state and the current Sync status.

What are the possible values of the state of Google Workspace sync?

The following are the possible values for the sync stage:

What is the use of the Auto Onboard New Users flag?

The "Auto Onboard New Users" flag facilitates the automatic inclusion of users from Google Workspace. Furthermore, the retrieval of findings from both the Calendar API and Gmail API occurs exclusively when this flag is enabled. Conversely, if the flag remains unchecked, the retrieval findings related to these APIs are bypassed.