Federate workload identity with GCP

This page describes how to set up workload identity federation to authenticate from GCP workloads. Authenticated workloads can interact with HCP services without storing any HCP service principal keys.

Prerequisites

You must complete the following steps before configuring a workload identity provider for GCP:

You must have the Admin role on the HCP project.
Create a service principal in the desired project and grant it access to the HCP resources your workload requires.
Have access to the GCP account to federate access to HCP from.
Install the HCP CLI or use the HCP Terraform Provider based on your desired configuration workflow.

GCP configuration prerequisites

To federate workload identity with GCP, you need to create a Service Account in your GCP Project and then attach it to your workload, such as a VM you created or a Cloud Run Service. After you configure the workload identity provider to trust Service Account, your GCP workloads can retrieve GCP access tokens and exchange them for HCP access tokens.

Complete the following steps to prepare your GCP environment for workload identity federation:

Create a GCP Service Account. After you create it, go the "Service account details" page and make note of the Service Account’s Unique ID. You need this value when you configure the workload identity provider.
Assign the managed identity to a virtual machine or another resource where your application runs.

Configure an external workload identity provider for GCP

To create an HCP workload identity provider for GCP, you must provide the following configuration values:

The Unique ID of the Service Account you created.
A conditional access statement.

Conditional access statement

When federating workload identity, one of the requirements is a conditional access statement. This statement is a boolean expression that has access to the identity claims and restricts which external identities are allowed.

When exchanging a GCP token for access to HCP, the conditional access statement has access to all the claims in the token with the jwt_claims. prefix. For most scenarios, we recommend using the sub claim that matches the Unique ID of the Service Account attached to the workload. For more information, refer to the access token claim reference in the GCP documentation.

The following example conditional access statement restricts access to HCP services to GCP workloads assigned the Service Account whose Unique ID is 106356042740441904560.

`jwt_claims.sub == "106356042740441904560"`

For a complete list of claims you can reference, complete the following steps:

Create a VM that has the Service Account assigned to it.
SSH to the VM.

Obtain an identity token using the metadata server. The following example uses hcp for its AUD claim, and specifies full for the format.

curl -H "Metadata-Flavor: Google" \
'http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=hcp&format=full'

To view the claims, copy the access token and paste it into a browser-based token decoder. The claims listed are values available when creating the conditional access statement.

Create the workload identity provider

After you gather the information you need, create the workload identity provider for GCP.

Use the hcp iam workload-identity-providers create-oidc command.

$ hcp iam workload-identity-providers create-oidc <PROVIDER_NAME> \
  --service-principal=<SP_RESOURCE_NAME> \
  --issuer=https://accounts.google.com \
  --conditional-access=<CONDITION> \
  --description=<DESCRIPTION>

This command requires the following information that is specific to your HCP and GCP accounts:

<PROVIDER_NAME>: The name of workload identity provider to create.
<SP_RESOURCE_NAME>:The service principal’s resource name, in the format iam/project/<PROJECT_ID>/service-principal/<NAME>.
<CONDITION>: The conditional access statement that restricts access to the specified GCP workload.
<DESCRIPTION>: An optional description for the provider.

The following example creates a workload identity provider named gcp-example. This provider configures HCP to restrict access to external workloads by requiring that their JWT token have 106356042740441904560 as a sub claim. Workloads that are granted access to HCP services use the my-app-runtime service principal.

$ hcp iam workload-identity-providers create-oidc gcp-example \
  --service-principal=iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-runtime \
  --issuer=https://accounts.google.com \
  --conditional-access='jwt_claims.sub == "106356042740441904560"' \
  --description="Allow my-app Service Account on GCP to act as my-app-runtime service principal"

Use the hcp_iam_workload_identity_provider resource.

# Replace with an existing service principal if created ahead of time.
resource "hcp_service_principal" "workload_sp" {
  name = "my-app-runtime"
}

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "gcp-example"
  service_principal = hcp_service_principal.workload_sp.resource_name
  description       = "Allow my-app Service Account on GCP to act as my-app-runtime service principal"

  oidc {
    issuer_uri = "https://accounts.google.com"
  }

  conditional_access = "<CONDITION>"
}

This configuration requires the following information that is specific to your GCP account:

<CONDITION>: The conditional access statement that restricts access to the specified GCP workload.

# Replace with an existing service principal if created ahead of time.
resource "hcp_service_principal" "workload_sp" {
  name = "my-app-runtime"
}

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "gcp-example"
  service_principal = hcp_service_principal.workload_sp.resource_name
  description       = "Allow my-app Service Account on GCP to act as my-app-runtime service principal"

  oidc {
    issuer_uri = "https://accounts.google.com"
  }

  conditional_access = "jwt_claims.sub == `106356042740441904560`"
}

Authenticate the workload's credentials

You can use the HCP CLI, HCP Terraform Provider, or HCP Go SDK to automatically retrieve external credentials and exchange them for an HCP access token. This process uses a credential file that contains the information required to obtain external credentials and the workload identity provider to exchange them with.

For more information, refer to credential files.

Create the credential file for GCP

Use the hcp iam workload-identity-providers create-cred-file command.

$ hcp iam workload-identity-providers create-cred-file <PROVIDER_NAME> \
  --gcp \
  --output-file=credentials.json

This command requires the following information that is specific to your HCP account:

<PROVIDER_NAME>: The name of workload identity provider to exchange credentials with, in the format iam/project/<PROJECT_ID>/service-principal/<SP_NAME>/workload-identity-provider/<PROVIDER_NAME>.

The following example creates a credentials.json file using the gcp-example provider, which is associated with the my-app-runtime service principal.

$ hcp iam workload-identity-providers create-cred-file \
  iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-runtime/workload-identity-provider/gcp-example \
  --gcp \
  --output-file=credentials.json

Ensure the credential file exists in the runtime environment. Because the credential file contains no secret values, you can store the credential file in the VM image. Alternatively, you can generate it at runtime.

To use the credential file to authenticate, you can use the HCP CLI, the HCP Terraform provider, or the HCP Go SDK. Refer to use a credential file to authenticate for more information.