Connecting to Google Workspace using a service account

Connecting ControlMap to Google Workspace




* 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


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. 



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



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 


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" \


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




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






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 a new API client




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


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,


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: (12/4/2021)