Google Workspace Provider

The Google Workspace provider provides resources to interact with Google Workspace.

Example Usage

# Auth method: Domain-wide delegation and user impersonation
provider "googleworkspace" {
  credentials             = "/Users/mscott/my-project-c633d7053aab.json"
  customer_id             = "A01b123xz"
  impersonated_user_email = "impersonated@example.com"
  oauth_scopes = [
    "https://www.googleapis.com/auth/admin.directory.user",
    "https://www.googleapis.com/auth/admin.directory.userschema",
    # include scopes as needed
  ]
}
# Auth method: Admin roles applied directly to a service account
provider "googleworkspace" {
  credentials = "/Users/mscott/my-project-c633d7053aab.json"
  customer_id = "A01b123xz"
  oauth_scopes = [
    "https://www.googleapis.com/auth/admin.directory.user",
    "https://www.googleapis.com/auth/admin.directory.userschema",
    # include scopes as needed
  ]
}

Authorization

This provider uses Admin SDK API methods to manage resources on a Workspace customer domain. There are multiple ways to set up proper authorization for a service account:

Authentication

Using Domain-Wide Delegation

Creating a Service Account and Credentials

Terraform uses a GCP service account to manage resources created by the provider. To create the service account and generate a service account key:

  1. Follow the instructions in the create service account and credentials documentation.
  2. Save the json file containing your service account key credentials locally and set the GOOGLEWORKSPACE_CREDENTIALS environment variable to the path of that file. Terraform will now use that key for authentication.

Configuring the Service Account's granted scopes in Google Workspace

To access user data on a Google Workspace domain, the service account that you created needs to be granted access by a super administrator for the domain. Follow the instructions in the delegate domain-wide authority documentation.

More information about scopes is below.

Configuring scopes requested by the provider

The provider can be configured with an oauth_scopes field containing a list of requested scopes. If oauth_scopes is _not_ set in the provider configuration, the provider will fall back to a default list of scopes, which are all the scopes needed to manage resources that can be provisioned by the provider (see default scopes for v0.6.0 here). If default scopes are used, the service account needs to be granted all of those scopes in Google Workspace.

The scopes declared in the provider's configuration need to match, or be a subset of, the scopes granted to the service account. If a provider is configured with scopes the service account isn't granted to use, the provider will receive a 401 Unauthorized response when it requests an access token.

->It's recommended to include oath_scopes in your provider configuration to make the requested scopes explicit and easier to debug issues.

Impersonating a Google Workspace User

Only users with access to the Admin APIs can access the Admin SDK Directory API, therefore your service account needs to impersonate one of those users to access the Admin SDK Directory API. This user's email must be set in the environment variable GOOGLEWORKSPACE_IMPERSONATED_USER_EMAIL or in the impersonated_user_email attribute in the provider. Additionally, the user must have logged in at least once and accepted the Google Workspace Terms of Service.

Using Specific Administrator Roles

You do not need to set up domain-wide delegation if you are granting more specific administrator roles to the service account. If the Terraform pipeline execution environment provides an appropriate token as Application Default Credentials (ADC), you can use the provider without any further setup.

To do this it's recommended that you create a custom admin role(s) with the Admin API privileges you need, as pre-built administrator roles might not cover your use case.

When using gcloud locally, you can provide the required scopes for ADC login by adding the --scopes parameter to gcloud auth application-default login. For example, you can provide additional scopes on Compute Engine. You can do this to configure access for both service accounts and end users.

provider "googleworkspace" {
  customer_id = "A01b123xz"
}

The approach outlined above does not work on Cloud Build because it does not (yet) support specifying additional scopes for service account tokens accessible during builds. Other pipeline setups use the google_service_account_access_token to impersonate a service account. This allows them to use a single identity regardless of who is initiating the execution. For these cases, set the access_token parameter to the appropriate credentials.

provider "googleworkspace" {
  customer_id  = "A01b123xz"
  access_token = data.google_service_account_access_token.default.access_token
}

You can also provide an exported service account key in the credentials parameter without specifying an impersonated_user_email.

Schema

Optional