The Google Workspace provider provides resources to interact with Google Workspace.
# 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
]
}
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:
Enable domain-wide delegation to impersonate a user that has super administrator privileges. You cannot directly grant super administrator privileges to service accounts.
Assign specific administrator roles directly to the service account.
Terraform uses a GCP service account to manage resources created by the provider. To create the service account and generate a service account key:
GOOGLEWORKSPACE_CREDENTIALS
environment variable to the path of that file. Terraform will now use that key for authentication.
GOOGLEWORKSPACE_CLOUD_KEYFILE_JSON
or GOOGLE_CREDENTIALS
(>= 0.2.0)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.
oauth_scopes
granted to
the googleworkspace
provider.More information about scopes is below.
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.
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.
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
.
access_token
(String) A temporary [OAuth 2.0 access token] obtained from the Google Authorization server, i.e. the Authorization: Bearer
token used to authenticate HTTP requests to Google Admin SDK APIs. This is an alternative to credentials
, and ignores the oauth_scopes
field. If both are specified, access_token
will be used over the credentials
field.credentials
(String) Either the path to or the contents of a service account key file in JSON format you can manage key files using the Cloud Console). If not provided, the application default credentials will be used.customer_id
(String) The customer id provided with your Google Workspace subscription. It is found in the admin console under Account Settings.impersonated_user_email
(String) The impersonated user's email with access to the Admin APIs can access the Admin SDK Directory API. impersonated_user_email
is required for all services except group and user management.oauth_scopes
(List of String) The list of the scopes required for your application (for a list of possible scopes, see Authorize requests)service_account
(String) The service account used to create the provided access_token
if authenticating using the access_token
method and needing to impersonate a user. This service account will require the GCP role Service Account Token Creator
if needing to impersonate a user.