Connecting ControlMap to Google Workspace


Overview


If you are unfamiliar with your Google cloud and workspace settings, please send these instructions to your Google Cloud and  Workspace administrator.


ControlMap uses a Google Cloud Service Account created by you and domain-wide delegation to access your company's workspace and READ user information to populate ControlMap personnel inventory. 

The service account is scoped to have READ ONLY permissions on the user data and cannot make changes to your domain. In addition to fetching users' data, ControlMap also checks for MFA settings and admin access to the google workspace for users in your account.


Please read more about limitations and recommendations from Google here

https://developers.google.com/admin-sdk/directory/v1/guides/delegation

 


What is a service account?

A service account belongs to the application and not to a user. In enterprise applications service accounts enable access to data without manual user authorization part. This prevents jobs from failing if a user leaves your organization or changes roles.


Steps

At a high level here are the steps you will need to complete to make the connection between ControlMap and Google Workspace

1. Enable the required APIs within a Google project 

2. Create a service account and record the client ID for domain-wide delegation.

3. Create and & save key credentials for the service account

4. Configure google workspace admin to enable domain-wide delegated access for the service account

5. Get access to a user's email who have admin access or at-least read-only access to all users in the company's domain


Step 1: Enable required APIs in your project.

1. Login to your Google Cloud Console

2. Browse to the APIs & Services > Credentials page

 

3. Make sure that the correct Google project is selected. Activate Cloud Shell from your Google Cloud Console. 

4. Run the following command in the cloud shell to enable Admin APIs.

gcloud services enable admin.googleapis.com 


STEP 2. Create a service account & record the client ID for domain-wide delegation.

ControlMap creates a service account in your project and uses this service account to impersonate a user in your Google Workspace to access and sync google workspace data. 

 

1. Select the right project, open the Cloud Shell and create a service account using the command below.

sa=$(gcloud iam service-accounts create controlmap-workspace-user-sync \
--display-name "ControlMap Google Worspace User Sync Service Account" \
--description "ControlMap uses this service account to read users from your Google Workspace." \
--format="value(email)")


2. After the command runs successfully, wait for about a minute to refresh the page. You will see the service account display under the Service Accounts Section


 

3. Click on the service account and then advanced setting to view the Client Id.


4. You will be able to see the client ID once you expand the advanced settings


MAKE A NOTE OF THE CLIENT ID. IT WILL BE USED LATER TO CONFIGURE THE GOOGLE WORKSPACE ADMIN 



Step 3. Create a credentials JSON file and save it securely. 

1. Once you have recorded the client ID, click on the Keys tab and Add a new KEY. ControlMap uses this credential file to connect to your Google Workspace.

2. Download and save the JSON file. You will need this file to connect ControlMap to your Google Domain.



STEP 4. Enable domain delegation access to the service account's client ID

1. Login to Google Admin

2. Navigate to Security  > Access and Data Control > API Controls > Manage Domain Wide Delegation


3. Click on Add new to add new API client


4. Enter the Client ID ** recorded earlier in Step 2 and the scope as 

https://www.googleapis.com/auth/admin.directory.user.readonly,
https://www.googleapis.com/auth/admin.reports.usage.readonly


STEP 5 - Ensure you have access to google workspace admin's email ID 


Service account requires an email address/user account to impersonate in order to call Admin APIs in Google workspace. 


An email address of an active admin is the best and easiest option.


* The scope of service account is always limited to the following scope 

https://www.googleapis.com/auth/admin.directory.user.readonly,

https://www.googleapis.com/auth/admin.reports.usage.readonly


We recommend that you use a non-person email account for this purpose. This is what Google has to say about domain-wide delegation for service accounts. 


Source: https://developers.google.com/admin-sdk/directory/v1/guides/delegation (12/4/2021)