Google Authentication

Learn more about the architecture for how Provisionr syncs with the Google API for each managed group or resource.

This document provides an overview of how Provisionr integrates with Google APIs behind the scenes to satisfy compliance and security requirements.

For detailed instructions on setting up your Google integration, please refer to the Launchpad Connect to Google Workspace guide.

Concepts

API Client

We use the Provisionesta Google API Client to access the API client that was released by our founder as an open source project in 2021.

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.

Secrets Storage

We securely store your Google service account credentials using AWS Secrets Manager in the same region as your Provisionr workspace.

When you upload your service account JSON key using the Provisionr CLI, it is transmitted securely over TLS to AWS Secrets Manager and stored encrypted at rest.

Key Rotation

Provisionr-managed Service Accounts: We handle automatic key rotation for service accounts that we create on your behalf for each integration. Every customer integration uses a different service account. Keys are rotated every 90 days, and after every security incident.

Customer-Managed Service Accounts: You are responsible for managing the lifecycle of service account key rotations for your customer-managed service account. Provisionr will continue using this key as long as it is valid, even if it never expires. You can rotate the key at any time using the Provisionr CLI command:

prv google-integration:rotate-key

OAuth2 Domain-Wide Delegation

These concepts can be complex and confusing. There are many nuances and peculiarities with how the Google API works since each Google service is a microservice with a separate API that we need to grant Provisionr access to. We’ve tried to simplify it as much as possible.

Google Workspace is tightly integrated with GCP and each Google Workspace organization has a corresponding GCP organization.

To access Google Workspace Users and Groups using the API, we authenticate using Google’s implementation of OAuth2 using Google Cloud Platform (GCP) Service Accounts.

The service account in GCP is used for authentication with the Google API. Keep in mind that a service account does not have any permissions by default.

Each Google Cloud service account has a unique OAuth2 Client ID (ex. 111234567890123456789) that is used to reference the service account in Google Workspace.

In order to access Google Workspace data, we need to use domain-wide delegation of authority. This acts as the authorization layer with underlying roles and permissions for Google Workspace that allows you to grant the service account various API scopes to access different parts of your Google Workspace data.

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

OAuth2 Scopes

Provisionr requires the following OAuth2 scopes to be granted to the service account for domain-wide delegation of authority in order to read Google Workspace Users and manage Groups and Group Members.

In future releases, we will be adding support for managing additional resources. You can proactively grant the additional scopes now or wait until those features are released to use that functionality.

The scopes below are color coded to indicate which functionality they provide.

• Read-Only Functionality
• Read-Write Full Functionality
• Read-Write Restricted Functionality

We follow the principle of least privilege and only request the minimum OAuth2 scopes that are required for each feature that we implement.

If your team has security concerns, Provisionr supports starting with read-only scopes first. You do not need to grant read-write scopes until you are ready to sync group members or create new groups from Provisionr.

Easy Button Scopes

This is the list of scopes to grant if you want to use all of the functionality that Provisionr currently supports for your Google integration.

Initial Testing

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

Core Functionality

Import User Identities

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

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

Provisionr can read your Google Workspace users and their attributes to build your organizational directory structure. This is required for any functionality in Provisionr to work with Google Workspace.

If a user is created or deactivated in Google Workspace, the Provisionr sync process will pick up those changes during the next sync.

Read the Docs to learn more.

https://www.googleapis.com/auth/admin.directory.orgunit.readonly

This scope is optional iand is not required.

2026-Q2 Provisionr can read your Google Workspace organizational units to create a dimension for Organization Units and an attribute for each organization unit that users are assigned to.

This is useful if your Google users are already assigned to organizational units that you want to use for access control policies in Provisionr.

Read the Docs to learn more.

Google Workspace Groups

Read the Docs to learn more.

Manage Groups and Members

https://www.googleapis.com/auth/admin.directory.group

https://www.googleapis.com/auth/admin.directory.group.readonly

Provisionr can read your existing Google Workspace groups and their users to start building group-based access control policies.

You can also use this scope to audit their existing access without granting Provisionr permission to make any changes.

https://www.googleapis.com/auth/admin.directory.group.member

Provisionr cannot create new groups or delete groups based on custom attributes without the admin.directory.group scope.

With this restrictive scope, Provisionr can add and remove users from existing Google Workspace groups to sync group membership based on the access control policies that you create in Provisionr.

https://www.googleapis.com/auth/admin.directory.group

Provisionr can create, update, and delete Google Workspace groups. This is key feature of Provisionr to automatically create a group for each department, team, project, or other attribute in the Provisionr Directory.

Provisionr can also sync users to new and existing groups based on the access control policies that you create in Provisionr.

Google Cloud Identity Groups

Although some API endpoints allow using the cloud-platform scope that is already used for managing other GCP resources, Provisionr specifically requests the cloud-identity.* scopes for least privilege security.

Cloud Identity Groups are used for managing IAM principals that are not managed with Google Workspace Groups. You do not need any Cloud Identity Scopes if you are only managing Google Workspace Groups.

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.

Manage Groups and Members

https://www.googleapis.com/auth/cloud-identity.groups
https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly

https://www.googleapis.com/auth/cloud-identity.groups.readonly

2026-Q2 Provisionr can read your Google Cloud Identity groups and their users to start building group-based access control policies. Users can be synced to groups when you later grant the read-write scopes.

https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly

2026-Q2 Provisionr can read the Cloud Identity User SSO metadata if your users use external identity providers besides Google Workspace for authentication.

https://www.googleapis.com/auth/cloud-identity.groups

2026-Q2 Provisionr can create, update, and delete Google Cloud Identity groups and sync users to those groups based on the access control policies that you create in Provisionr.

Google Drive and Docs

Danger, Will Robinson! Danger! These are powerful scopes that allow Provisionr full access to all files in your Google Shared Drives. This may be a concern for security-conscious teams.

Only grant this scope if you plan to use the Google Drive resource management functionality that will be released in 2026-2H.

You can wait to grant this scope until you are ready to use this functionality.

Manage Drives, Folders and Resource Members

https://www.googleapis.com/auth/drive

https://www.googleapis.com/auth/drive.readonly

2026-2H Provisionr can read the list of Google Drive resources (files, folders, shared drives) and their sharing permissions to build audit reports of who has access to what.

This is useful for compliance audits and access reviews to ensure that sensitive documents are only shared with the appropriate users and groups.

If you are just getting started with Provisionr and want to try out the Google Drive resource audit functionality first, you can grant this read-only scope initially. You can later grant the full read-write scope when you are ready to start managing resource sharing permissions.

https://www.googleapis.com/auth/drive

2026-2H Provisionr can manage the sharing permissions of specific Google Docs, Sheets, Slides, uploaded files in Google Drive, folders, or Google Shared Drives. Each of these are collectively referred to as a Google Resource in Provisionr.

Provisionr also allows you to automatically create a Google Shared Drive or Folder for departments, teams, projects, or other attributes in the Provisionr Directory, and automatically manage member access based on that attribute’s policy ruleset.

We care about your data privacy and have an opt-in model for discovering which resources that you want to manage.

Our initial discovery process only scans the list of Shared Drives to get the ID, title, and members of that Shared Drive.

For each shared drive, you need to opt-in for Provisionr to scan that drive for folders and files within that drive that you want to manage. Provisionr does not see any of the contents of the files or documents, only the metadata including the title, unique file ID, and sharing permissions.

All resources are managed individually. You opt-in to managing each resource separately, whether at the folder level that contains all files or the specific file/Doc/Sheet/Slide. Once you opt-in to managing a resource, Provisionr will scan the sharing permissions and allow you to create access control policies to manage who has access to that resource.

This allows you to enforce access control policies for broader level department or team files at the shared drive or folder level, as well as specific sensitive documents in your organization.

This feature will be released in 2026-2H and you can learn more about it in the documentation after it’s released.

Google Cloud Platform (GCP)

Provisionr can manage IAM members for GCP Folders, Projects, and Billing Accounts to ensure that only the appropriate users and groups have access to your GCP resources.

Do NOT add the https://www.googleapis.com/auth/cloud-platform scope to the Domain-Wide Delegation list of granted scopes.

Otherwise, the service account could impersonate any administrative user and would have access to all GCP resources in your organization which would be a major security risk.

When Provisionr makes API calls to GCP resources, we use the broad cloud-platform OAuth2 scope as part of the API call authentication to say that this is the “category” of endpoints I want to reach, however we have not authorized the service account to do anything yet.

Instead, we need to invite the email address of the service account to the specific GCP resources that you want to manage.

You’re probably familiar with granting IAM Roles and Permissions to users and groups in GCP projects. The same concept applies to service accounts since GCP uses the concept of Principals rather than users, so a Principal has multiple types:

• Google User ([e-mail])
• GCP Service Account ([e-mail])
• Google Workspace Group email ([e-mail])
• Google Cloud Identity Group email ([e-mail])

You need to grant the service account the appropriate IAM roles at the Organization, Folder, Project, or Billing Account level depending on which resources you want to manage, just like you would for a user or group.

This feature will be released in 2026-Q2 and you can learn more about it in the documentation after it’s released.

No additional configuration is needed today to prepare for this functionality.