Access Google Cloud from HCP Terraform with workload identity

Storing long-lived service account keys in HCP Terraform poses a significant security risk. If compromised, these account keys could give an attacker access to your Google Cloud environment. Not only is leaking the key a risk, but many organizations have a policy to block creation of such keys. Fortunately, in many cases, you can authenticate with more secure alternatives to service account keys. One such alternative is workload identity federation, which uses identity and access management (IAM) to grant external identities (such as HCP Terraform) the ability to impersonate service accounts.

HCP Terraform’s dynamic provider credentials allow Terraform runs to impersonate a service account through native OpenID Connect (OIDC) integration and obtain a short-lived OAuth 2.0 access token for each run. This short-lived access token lets you call any Google Cloud APIs that the service account has access to at runtime, making your HCP Terraform runs much more secure.

Using HashiCorp Terraform, you have the ability to create a Google Cloud workload identity pool and provider, which HCP Terraform uses to request a federated token. This token is then passed to the Google Terraform provider, which impersonates a service account to obtain temporary credentials to plan or apply Terraform.

The above diagram illustrates the authentication sequence for accessing Google Cloud using dynamic provider credentials and workload identity federation.

Below is an example to configure workload identity federation in Google Cloud. This approach assumes you have a pre-existing method to authenticate with your Google Cloud project. If you don’t, you can create the temporary service account outlined below.

»Set up the workload identity pool and provider

To get started, create a temporary service account along with a JSON key. Safely store this key within your HCP Terraform workspace variables to grant temporary access to your Google Cloud project. This less-secure access method will only be used for initial setup. Remember to delete the temporary service account key once you’ve transitioned to workload identity federation using the steps below.

To set up the HCP Terraform pool and provider for workload identity federation, update the local google_project_id and organization_name values in the locals{} block:

Once the HCP Terraform pool and provider are created, create a service account that HCP Terraform will impersonate at runtime:

»Delegating access to another workspace

For improved security and scalability, consider using a separate HCP Terraform workspace to set up and configure your workload identity federation. From this workspace, using HCP Terraform variable sets, you can share the service account and identity federation configuration, allowing you to securely delegate access to Google Cloud from one workspace to another.

Below is an example configuration that creates a variable set and shares it with another HCP Terraform workspace.

Create the required environment variables below and associate them with the variable set. HCP Terraform uses these to obtain the short-lived OAuth 2.0 access token, which it uses to impersonate a service account at runtime that can call any Google Cloud APIs that the service account has access to:

»Using workload identity federation

When using workload identity federation, you don't need to define anything within the provider itself. By sharing the variable set — which includes the service account and identity federation configuration — with another HCP Terraform workspace, you automatically gain access to Google Cloud within the shared workspace.

HCP Terraform does this by impersonating the service account at runtime, using the environment variables from the shared variable set. This approach allows you to securely scale access management within HCP Terraform by delegating access from one workspace to another while precisely restricting Google Cloud access to only what the service account needs.

Using the service account created earlier, which has been assigned only the cloud storage admin role, you can immediately create a bucket within the shared workspace without having to configure anything else:

»Learn more about workload identity federation

If you want to learn more about keyless Google Cloud access from HCP Terraform, check out the dynamic provider credentials and workload identity federation documentation. You can find all the code used in this post on GitHub in the keyless-auth-gcp-hcp-terraform repository.