The primary integration is used for the unified Directory User profile including name and email address, manager relationships, employee IDs, and lifecycle timestamps when a user is provisioned and deprovisioned as an employee or contractor.Additional integrations are used for enriching Directory Attributes and having user metadata for each vendor for group or resource membership assignment.The first integration that you create is your primary integration and cannot be changed later. Please use your Identity Provider (IdP) as your primary source of truth for Directory Users.If you already have an Okta integration, then that is your primary integration.
Is Okta your Identity Provider (IdP)? Please stop here and create the Okta integration first before creating your Google Workspace integration.
Is your Identity Provider (IdP) Google Workspace? If yes, then you’re in the right place.
Provisionr uses OAuth2 Domain-Wide Delegation to authenticate with the Google API using a service account in your Google Cloud Platform (GCP) project that has been granted the necessary scopes in Google Workspace using domain-wide delegation. This allows Provisionr to securely access your Google Workspace data without needing to store user passwords or use less secure authentication methods.
Learn more about the Google OAuth2 scopes needed and architecture for how Provisionr syncs with the Google API in the Google Authentication docs.
We encourage you to use a Provisionr-managed service account if you are just getting started. This allows you to get up and running quickly without needing to manage your own GCP project and service account.You have full control of what the service account has access to with domain-wide delegation of authority and you can revoke access at any time from the Google Workspace Admin UI.You can always switch to a customer managed service account later if you need more control.
1
Create Workspace Integration
Use the Provisionr CLI to create a new Google Workspace integration in your workspace.
prv google-integration:create
Your integration is created in a staged state. Your Provisionr workspace automatically generates a Google service account in Provisionr’s GCP organization that we will manage on your behalf.In the upcoming steps, you will grant this service account the necessary OAuth2 scopes using domain-wide delegation of authority to access your Google Workspace data.After you complete the steps below in the Google Workspace Admin UI, you will return here to activate the integration.
2
Workspace Super Admin Role
You will need to have access to a Google Workspace account with the Super Admin role in order to grant a service account scopes using domain-wide delegation of authority.Please contact your Google Workspace administrator to perform these steps if you do not have permission. You will need to share the integration metadata from the previous step.
3
Grant 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.You can learn more about the scopes in the Google Authentication Architecture documentation.Follow the vendor instructions to grant your service account the domain-wide delegation scopes listed below.You will need the Client ID of your service account which you can see in the Provisionr CLI output when you created your integration in the first step.
Use the Provisionr CLI to activate your Google Workspace integration now that you have granted the necessary OAuth2 scopes.
prv google-integration:activate
This command will validate that the service account can successfully authenticate and has the necessary permissions to access your Google Workspace data.If successful, the integration will be activated and start the initial sync of your Google Workspace users, groups, and organization units into Provisionr.Please refer to the Google Integration Documentation to learn more about how Provisionr syncs with Google Workspace and manages your users and groups.
If you want to manage your own Google Cloud Platform (GCP) service account for your Google Workspace integration, follow the steps below to create a new GCP project and service account with the appropriate permissions.These steps are for system administrators and can be complex and confusing. There are some nuances and peculiarities with how the Google API works. We’ve tried to simplify it and we’ll take it one step at a time to guide you through the process to get your API credentials.
We encourage you to use a Provisionr-managed service account if you are just getting started. This allows you to get up and running quickly without needing to manage your own GCP project and service account. You can always switch to a customer managed service account later if you need more control.
1
Create Workspace Integration
Use the Provisionr CLI to create a new Google Workspace integration in your workspace.
prv google-integration:create
Your integration is created in a staged state and generate a unique integration ID that you will use when creating your GCP project and service account.After you complete the steps below, you will return to Provisionr to add your credentials and activate the integration.
2
Workspace Super Admin Role
You will need to have access to a Google Workspace account with the Super Admin role in order to grant a service account scopes using domain-wide delegation of authority.Please contact your Google Workspace administrator to perform these steps if you do not have permission. You will need to share the integration metadata from the previous step.
3
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 are not already a GCP organization administrator, it is likely that they will want to perform these steps for you instead of granting you access.You can provide the link to this page as reference documentation if you need to open an issue or ticket.
Option B: 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.
Find your Workspace ID
Your Workspace ID is included in the integration metadata that was displayed when you created the integration using the CLI in the first step.
Project Name Conventions
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 provisionr so it needs to be unique to your organization.When you create the service account, it will have an email address of {service-name}@{project-id}.iam.gserviceaccount.com so choose a project name that is easy to identify as belonging to your organization.
Reusing an Existing GCP Project
It is best practice to create a new GCP project (it’s free!) in your organization (in any folder). You may break your compliance or security best practices if you re-use an existing project.We do not recommend reusing an existing GCP project unless your organization has an existing project where IT and Security service accounts are created. In other words, you should not reuse a project that is used for other purposes (ex. staging, production, random, sandbox, shared, or test projects).Although Provisionr is a production service, an existing production project is likely to have other services running in it (ex. your company product) that are unrelated to Provisionr and you should maintain separate of concerns.If you have a GCP administrator and they have a preference, we defer to their preference.
There is no technical impact to Provisionr if you reuse an existing GCP project for your service account, as long as the APIs that Provisionr needs are enabled in the project.
Project Creation Permissions
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.You can create the project using the Web UI, CLI, Terraform, or any other method that your organization uses to create GCP projects.
The project can be placed in any folder based on your company naming standards.If your GCP organization is empty and does not have any (or many) projects, you can create it at the top-level of the organization. You can always move it later if needed.
Multiple GCP Organizations
If you’re not sure what this some of this means, assume that you only have one organization.Each Google Cloud organization has a 1:1 relationship with a Google Workspace organization.If you have a complex architecture with multiple GCP organizations (different domains), then your project can be created in whichever organization that your Infrastructure or Platform Engineer chooses.Having secondary or alias domains in Google Workspace does not mean that you have multiple organizations in GCP.The service account email address and OAUTH2 client ID will need to be granted domain-wide delegation in the Google Workspace organization that has the domain name that matches the email addresses of your employees.
Behind the scenes, this is how Provisionr-managed service accounts are created for customers using our Provisionr organization and granting access to your Google Workspace through OAuth2 client ID that is globally unique across all Google customer organizations.
5
Enable GCP Billing
Follow the vendor docs to add your GCP project to your existing billing account.
Budget and Costs
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.
6
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 below.
Enabling these APIs is equivalent to powering up the servers that have the API endpoints that Provisionr needs to use. Activating an API does not grant Provisionr permission to use those endpoints until you authorize the scopes for the service account in later steps.
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.
This is used for viewing, creating, updating, and deprovisioning Google Groups, Group Members, Organization Units, and Users.Provisionr does not have access until you grant OAuth2 scopes with delegated domain authority. You can restrict Provisionr to be in read-only mode by only granting Directory API OAuth2 scopes that end with *.readonly in the upcoming steps.
When a Google Group is created by Provisionr, this allows us to modify the insecure default policies for who can post, view conversations, and join the group. This also allows Provisionr 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 Provisionr.
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. provisionr-a1b2c3-d4e5@provisionr-a1b2c3-svc.gserviceaccount.com) has been invited to as a contributor 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.
We use this API to manage sharing permissions for Google Shared Drives, folders, uploaded files, Docs, Sheets, and Slides.Provisionr does not read the contents of your Google Drive files. We only read the metadata (directory listing, titles, and members) to show you which file or folder that you are managing the sharing permissions for.In a future release, Provisionr will support creating a shared drive or folder for each team, department, or other custom attribute.
7
Enable Cloud Management APIs
Skip to the next step if you do not plan to use Provisionr to manage Cloud Identity Groups or assign roles to GCP folders or projects when it is released in 2H 2026.You can always enable these APIs later if you decide to use those features in the future.
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.
This allows Provisionr to view the GCP folders and projects in your organization to show you what you are granting users access to.Remember: Provisionr does not have access until you assign the service account email address specific roles at the organization or folder level in later steps.
This is used for viewing the IAM roles and policies for GCP folders and projects in your organization and assigning roles to users for your folders and projects based on the access control policies that you create in Provisionr.
8
Create Service Account
Follow the vendor docs to create a service account in your GCP project.Use the metadata from the integration that you created in the first step to name your service account (ex. provisionr-a1b2c3-d4e5).
Name:provisionr-{workspaceId}-{integrationId}
ID:provisionr-{workspaceId}-{integrationId}
Description:This service account is configured as an integration in Provisionr.
Do not grant any access or users to the service account.
9
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 Provisionr. You can leave this in your ~/Downloads folder for now.Some administrators or security teams prefer storing service account keys in a secure password manager or secrets manager, however Provisionr will not need to access it again from your computer or secrets manager after you upload it using the CLI in the next step, so this is purely for reference on your end.
It is best practice to not reuse this service account or key for any other purpose. Please create a new service account that for future automation or API access needs.
10
Upload JSON Key to Provisionr
Use the Provisionr CLI to upload your JSON key for the integration that you created in the first step.
prv google-integration:rotate-key
We store your credentials securely using AWS Secret Manager in the same region as your Provisionr workspace.Once you upload the key, you will be prompted to delete the JSON key file from your computer.
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.If your organization has a policy of rotating service account keys every X days or after an incident, you can use this command to upload a new JSON key when needed.
If you do not want to manage key rotations, Provisionr-managed service account keys are rotated automatically every 90 days and after a security incident.
11
Grant 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.You can learn more about the scopes in the Google Authentication Architecture documentation.Follow the vendor instructions to grant your service account the domain-wide delegation scopes listed below.You will need the Client ID of your service account which you can see in the Provisionr CLI output after you uploaded your JSON key.
Use the Provisionr CLI to activate your Google Workspace integration now that you have uploaded your service account key and granted the necessary OAuth2 scopes.
prv google-integration:activate
This command will validate that the service account can successfully authenticate and has the necessary permissions to access your Google Workspace data.If successful, the integration will be activated and start the initial sync of your Google Workspace users, groups, and organization units into Provisionr.Please refer to the Google Integration Documentation to learn more about how Provisionr syncs with Google Workspace and manages your users and groups.
You are using a customer-managed service account. Please set a calendar reminder to rotate your key based on your organization’s security policies.You can always switch to a Provisionr-managed service account later if you want us to handle key rotations and management for you.
