Connecting to Google Workspace using a service account

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 Service Account with READ permissions & Domain Wide Delegation to access the company's user directory and populate ControlMap people inventory.

 

The service account is scoped to have USER READ-ONLY permissions and cannot make any changes to your Google workspace. 

In addition to fetching users' data, ControlMap also checks for MFA settings and admin permission for each user in the workspace.

 

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, and why is it preferred?

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. This prevents jobs from failing if a user leaves your organization or changes roles, or no longer authorizes the application. 

 

Steps

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

Step 1. Enable the required APIs within a Google project 

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

Step 3. Create and & save critical credentials for the service account

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

Step 5. Get access to a user's email who has 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

Mbhztb2Sp_FfJigCEn8njATjcRQfg4IBoQ.png

 

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

O-14FuP3y8y50Z32pXZZBE8O5wbRoUob-Q.png

 

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

gcloud services enable admin.googleapis.com 
Generic

 

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 \
--description="ControlMap uses this service account to read users from your Google Workspace." \
--display-name="ControlMap Google Workspace User Sync Service Account" \
--format="value(email)")

 

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

 

We8mIrFn3c8122squjZa00riaNk5wdqWgA.png

 

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

pzn95syPms9vtvTxKPj5ldFWXu3TPcqm8w.png

 

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

6gDyAKqzOMOkGCv84k5OU5sdJJAR89md5g.png

 

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.

n6zbJB-dXIjBBjNnmlzr3-1xJZDZpZXcWg.png

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

bB86IB3Ox2HJGU2d0ijPC-ODwwryC9PBNA.png

 

 

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

06pSJzhrGNcGtzlGfiLB-Pq070YzM20WNA.png

 

3. Click on Add new to add a new API client

KrY2XH_ZXRFtT8ckoj0vUYiKCIacznh86g.png

 

 

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
HTML
eMkZFn7PhN0apyGETMlhhApzLguQG-p2qA.png

 

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

 

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

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

 

* The scope of the 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. 

 

pn0y6SaokDDAVGlBGjIbe5Fjs09dEvZDEg.png

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