Adding Google Workspace as a Directory Source

To access Google Workspace Users and Groups using the API, we authenticate using Google’s implementation of OAuth2 using Service Accounts created in Google Cloud Platform (GCP) IAM. There are some nuances and peculiarities with how the Google API works so we’ve distilled it as simply as we can for you.

You can learn more about the process in the Google Workspace API Guide.

There is a lot of complexity with the concepts here, so let’s just focus on performing the steps below to get your API credentials.

Steps

1. Company Infrastructure Standards

Please ask the IT, Infrastructure, or Security team that manages your GCP infrastructure for your company practices on which GCP project that service accounts for Google Workspace should be created in. If you need to open an issue or ticket, you can provide the link to this page as reference documentation.

2. Create GCP Project

Follow the vendor docs to create a GCP project.

• Project Name:
  • Option A. accessctl-{orgShortId}-svc (ex. accessctl-z2w7bc-svc)
  • Option B. accessctl-{org-name}-svc (ex. accessctl-acme-svc)
  • Option C. Another unique name of your choosing that is less than 30 characters that complies with your company naming standards.
• Project ID: The same value as the Project Name. Do not accept the default generated name.

Project FAQ	Answer
Org ID?	Your org ID is available using the CLI with accessctl debug or accessctl dir:create-source and in the UI when trying to create a new directory source after you have chosen the Google Workspace option.
Generic Name?	Remember that GCP project names are globally unique across all customers and you will encounter problems if you try to use a generic name like accessctl so it needs to be unique to your organization.
Existing Project?	It is a best practice to create a new GCP project in your organization (in any folder) instead of reusing an existing project unless that project is intended for IT/Security service accounts. Do not choose an existing staging, production, random, sandbox, shared, or test GCP project.
Permission Issues?	A GCP project is free to create, however it requires the cloudresourcemanager.projects.create permission so your IT, Infrastructure, or Security team may need to create it for you. The following GCP roles have permission to create projects. For security reasons, it is better to ask someone who already has permissions to create it than request permissions yourself. Assured Workloads Administrator roles/assuredworkloads.admin Assured Workloads Editor roles/assuredworkloads.editor Cloud Deployment Manager Service Agent roles/clouddeploymentmanager.serviceAgent Project Creator (most common) roles/resourcemanager.projectCreator
Folder?	The project does not need to be at the top-level of the organization and can be placed in any folder based on your company naming standards.
Multiple Organizations?	If you have a complex architecture with multiple GCP organizations (different domains), then your project needs to be created in the organization with the domain name that matches the email addresses of your employees. Each Google Cloud organization has a 1:1 relationship with a Google Workspace organization. If you're not sure what this means, assume that you only have one organization.

3. Enable GCP Billing

Follow the vendor docs to add your GCP project to your existing billing account.

Billing FAQ	Answer
Budget?	You will not encounter any significant charges on this GCP project (a few cents maybe?). This is just the nature of how GCP projects work.
Permissions?	Your IT, Infrastructure, or Security team responsible for infrastructure management should be able to perform this step for you. If you don't already have access, it's unlikely that you will be granted access. You may also need to contact your Finance team if they are the billing account administrators.

4. Enable Workspace APIs

Google uses a microservice approach and you need to enable the APIs for each of the microservice APIs that you want to access from the service account that you will be creating in your project.

Follow the vendor docs to enable each of the APIs using the activation links in the table below.

API Name	How It's Used
Service Usage API 📖 Vendor API Docs 🚀 Activation Page	This allows the service account to get metadata for the APIs and services that are enabled. This is required for baseline functionality of using Google's API to handle quota limits.
Admin SDK API 📖 Vendor API Docs 🚀 Activation Page	This is used for viewing, creating, updating, and deprovisioning Google Groups, Group Members, Organization Units, and Users. Access Control does not have access until you grant OAuth2 scopes with delegated domain authority. You can restrict Access Control to be in read-only mode by only granting Directory API OAuth2 scopes that end with *.readonly in the upcoming steps.
Groups Settings API 📖 Vendor API Docs 🚀 Activation Page	When a Google Group is created by Access Control, this allows us to modify the insecure default policies for who can post, view conversations, and join the group. This also allows Access Control to see the settings for existing groups and provide the option for you to update them to comply with the policies that you create in Access Control.
Google Sheets API 📖 Vendor API Docs 🚀 Activation Page	This does not grant access to organization-wide or user's data. This is used for exporting CSV data to specific sheets or specific folders that the service account's email address (ex. accessctl@accessctl-{orgShortId}-svc.gserviceaccount.com) has been invited as a contributor to with Editor permissions. This provides a better user experience and data loss protection (DLP) by pushing the data directly to a Google Sheet instead of needing to download a CSV or XLS file onto your computer and upload it into Google Sheets or Excel.

5. Enable Cloud Management APIs

Optional: You only need to enable these APIs if you will be using Access Control to provision GCP projects and assign users to roles.

Follow the vendor docs to enable each of the APIs using the activation links in the table below.

API Name	How It's Used
Cloud Resource Manager API 📖 Vendor API Docs 🚀 Activation Page	This allows Access Control to view, create, and deprovision GCP folders and projects in your organization. Access Control does not have access until you assign the service account email address specific roles at the organization or folder level in later steps.
Identity and Access Management (IAM) API 📖 Vendor API Docs 🚀 Activation Page	This is used for viewing, creating, updating, and deprovisioning Google Groups, Group Members, Organization Units, and Users. Access Control does not have access until you grant OAuth2 scopes with delegated domain authority. You can restrict Access Control to be in read-only mode by only granting Directory API OAuth2 scopes that end with *.readonly in the upcoming steps.
Cloud Identity 📖 Vendor API Docs 🚀 Activation Page	Cloud Identity provides users and group management for IAM principals that are not managed with Google Workspace. When using infrastructure tools such as Terraform, Cloud Identity Groups are used instead of Google Workspace groups. This allows us to use the APIs for the appropriate IAM endpoints when granting access to GCP projects and resources.

6. Create Service Account

Follow the vendor docs to create a service account in your GCP project.

• Name: Access Control
• ID: accessctl
• Description: This service account is configured as a Directory Source in Access Control.
• You do not need to grant any access or users to the service account.

7. Create JSON Key

Follow the vendor docs to create a JSON key for your service account.

You will use this JSON key when you create the Directory Source in Access Control. You can leave this in your ~/Downloads folder for now.

8. Create Workspace Admin Role

Follow the vendor docs to create a new custom admin role in Google Workspace.

• Name: Access Control
• Description: This is a custom role with least privilege permissions for Access Control Directory Source
• Admin API privileges

  You will need to scroll down a long way (approximately 2/3 down the page) to the Admin API privileges section. Do not enable checkboxes in the Admin Console Privileges section at the top of the page. If you are just getting started with Access Control and are not ready to grant read-write access, you can grant read-only permissions to provide visibility into your organization and audit your existing configuration with minimal risk. The expected changes will be shown and you can enable read-write permissions when you’re ready.

  • Groups > Create
  • Groups > Delete
  • Groups > Read (read-only)
  • Groups > Update
  • Manage locked label on groups resources
  • Add security label on groups resource
  • Organization Units > Create
  • Organization Units > Delete
  • Organization Units > Read (read-only)
  • Organization Units > Update
  • Schema Management
  • Schema Read (read-only)
  • Users > Create
  • Users > Delete
  • Users > Read (read-only)
  • Users > Update Custom Attributes
  • Users > Update > * (all checkboxes)

9. Assign Service Account to Role

Follow the vendor docs to assign your service account to the new custom admin role in Google Workspace.

10. Create Directory Source

Does Your Primary Source Exist?

The first Directory Source that you create is your primary source and cannot be changed later. If Google Workspace is not your primary source, stop here and create your primary source first (ex. Okta) before coming back to this step.

CLI

Run the accessctl dir:create-source command. You will be prompted to choose the JSON key in your ~/Downloads folder.

Web UI

Navigate to Directory Sources and create a new source. You will be prompted to upload your JSON key file after choosing Google Workspace.

11. Move your JSON Key

Your JSON key should be saved in your password manager or secrets manager based on your organization’s standards for where service account credentials are saved at. Do not reuse this service account key for any other purpose.

Behind the Scenes

We use the Provisionesta Google API Client to access the API client. This provides an easy-to-use interface that handles all of the complex authentication, error handling, and pagination logic. We simply need to provide an endpoint, the credentials array, and we get the result back without any headaches.