Workload identity

Dynamic Provider Credentials are powered by Terraform Workload Identity, which allows HCP Terraform to present information about a Terraform workload to an external system – like its workspace, organization, or whether it’s a plan or apply – and allows other external systems to verify that the information is accurate.

You can think of it like an identity card for your Terraform runs: one that comes with a way for another system to easily verify whether the card is genuine. If the other system can confirm that the ID card is legitimate, it can trust the information the card contains and use it to decide whether to let that Terraform workload in the door.

The “identity card” in this analogy is a workload identity token: a JSON Web Token (JWT) that contains information about a plan or apply, is signed by HCP Terraform’s private key, and expires at the end of the plan or apply timeout. Other systems can use HCP Terraform’s public key to verify that a token that claims to be from HCP Terraform is genuine and has not been tampered with.

This workflow is built on the OpenID Connect protocol, a trusted standard for verifying identity across different systems.

Token Specification

Workload identity tokens contain useful metadata in their payloads, known as claims. This is the equivalent of the name and date of birth on an identity card. Once a cloud platform verifies a token using HCP Terraform’s public key, it can look at the claims in the identity token to either match it to the correct permissions or reject it.

You don't need to understand the full token specification and what every claim means in order to use dynamic credentials, but it's useful for debugging.

Workspace run token structure

The following example shows a decoded HCP Terraform workload identity token for a workspace run:

Header

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "j-fFp9evPJAzV5I2_58HY5UvdCK6Q4LLB1rnPOUfQAk"
}

Payload

{
  "jti": "1192426d-b525-4fde-9d42-f238be437bbd",
  "iss": "https://app.terraform.io",
  "aud": "my-example-audience",
  "iat": 1650486122,
  "nbf": 1650486117,
  "exp": 1650486422,
  "sub": "organization:my-org:project:Default Project:workspace:my-workspace:run_phase:apply",
  "terraform_organization_id": "org-GRNbCjYNpBB6NEH9",
  "terraform_organization_name": "my-org",
  "terraform_project_id": "prj-vegSA59s1XPwMr2t",
  "terraform_project_name": "Default Project",
  "terraform_workspace_id": "ws-mbsd5E3Ktt5Rg2Xm",
  "terraform_workspace_name": "my-workspace",
  "terraform_full_workspace": "organization:my-org:project:Default Project:workspace:my-workspace",
  "terraform_run_id": "run-X3n1AUXNGWbfECsJ",
  "terraform_run_phase": "apply"
}

This payload includes a number of standard claims defined in the OIDC spec as well as a number of custom claims for further customization.

Standard Claims

Custom claims for workspace runs

The following custom claims are included in tokens for workspace runs:

Module test run tokens

When using dynamic credentials for module testing, HCP Terraform generates workload identity tokens specifically for test runs. These tokens have a different structure and custom claims compared to workspace run tokens.

Module test token structure

The following example shows a decoded module test workload identity token:

Header

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "j-fFp9evPJAzV5I2_58HY5UvdCK6Q4LLB1rnPOUfQAk"
}

Payload

{
  "jti": "a7c3f2e1-8b9a-4d5e-9f2c-1a3b5c7d9e0f",
  "iss": "https://app.terraform.io",
  "aud": "aws.workload.identity",
  "iat": 1705334400,
  "nbf": 1705334370,
  "exp": 1705335000,
  "sub": "organization:my-org:module:terraform-aws-vpc:operation:test_run",
  "terraform_run_phase": "plan",
  "terraform_organization_id": "org-abc123xyz",
  "terraform_organization_name": "my-org",
  "terraform_run_id": "trun-KFg8DSiRz4E37mdJ"
}

Module test subject claim format

For module test runs, the subject claim has a different format than workspace runs:

organization:{ORGANIZATION_NAME}:module:{MODULE_NAME}:operation:test_run

For example: organization:my-org:module:terraform-aws-vpc:operation:test_run

This format allows you to create trust policies that scope permissions to specific organizations and modules.

Module test custom claims

In addition to standard JWT claims, tokens for module test runs include these custom claims:

Token lifetime for module tests

Module test tokens have a configurable time-to-live (TTL) separate from workspace run tokens:

• Default TTL: 10 minutes (600 seconds)
• Valid range: 5 to 30 minutes (300 to 1,800 seconds)
• Configuration: Organization owners can adjust the TTL using the Organizations API by setting the module_test_token_ttl attribute

Each token includes a 30-second clock skew mitigation (nbf is 30 seconds before iat) to account for time differences between systems.

For more information, refer to Dynamic credentials for module testing.

Configuring Trust with your Cloud Platform

When configuring the trust relationship between HCP Terraform and your cloud platform, you’ll set up conditions to validate the contents of the identity token provided by HCP Terraform against your roles and policies.

At the minimum, you should match against the following claims:

• aud - the audience value of the token. This ensures that, for example, a workload identity token intended for AWS can’t be used to authenticate to Vault.
• sub - the subject value, which includes the organization and workspace performing the run. If you don’t match against at least the organization name, any organization or workspace on HCP Terraform will be able to access your cloud resources!

You can match on as many claims as you want, depending on your cloud platform.