Updating Workload Identity for Projects

Steps

Overview

A project is an abstraction layer between the organization and workspace that provides the ability to organize and govern workspaces and future infrastructure processes. Projects allow teams to safely self-manage workspaces, while enabling organization administrators to maintain centralized control and enforce guardrails within a single HCP Terraform or Terraform Enterprise organization.

To scope workload identity permissions to the project level on various cloud platforms, the format for the sub claim in the workload identity token is changing.

The current format is:

organization:[org name]:workspace:[workspace name]:run_phase:[run phase]

The new format includes the project name:

organization:[org name]:project:[project name]:workspace:[workspace name]:run_phase:[run phase]

This guide provides procedures to prepare for this change in AWS, Vault, GCP, and Azure, while maintaining compatibility with the current subject format.

Note: The default project name is Default Project. You must handle this name in any subject comparisons that use the full subject value.

Procedure

This section details the required configuration changes for each platform.

Option 1: AWS

AWS allows for multiple values for conditions in its trust policies. You must add the new subject format to your existing trust relationship document.

For example, update an existing policy condition by adding the new format to the app.terraform.io:sub array.

Before:

"Condition": {
  "StringEquals": {
    "app.terraform.io:aud": "aws.workload.identity"
  },
  "StringLike": {
    "app.terraform.io:sub": "organization:my-org:workspace:my-ws:run_phase:*"
  }
}

After:

"Condition": {
  "StringEquals": {
    "app.terraform.io:aud": "aws.workload.identity"
  },
  "StringLike": {
    "app.terraform.io:sub": [
      "organization:my-org:workspace:my-ws:run_phase:*",
      "organization:my-org:project:Default Project:workspace:my-ws:run_phase:*"
    ]
  }
}

This change allows the policy to accept either the old or new format.

Option 2: Vault

Vault allows multiple values for bound claims, which is also supported in the Vault provider. Adjust the sub format in your bound_claims to handle the new format.

For example, update your bound_claims in your Terraform configuration.

Before:

bound_claims_type = "glob"
bound_claims = {
  sub = "organization:my-org:workspace:my-ws:run_phase:*"
}

After:

bound_claims_type = "glob"
bound_claims = {
  sub = "organization:my-org:workspace:my-ws:run_phase:*,organization:my-org:project:my-proj:workspace:my-ws:run_phase:*"
}

This change allows the role to accept tokens with either the old or new format.

Option 3: GCP

GCP allows for multiple checks using CEL conditions. You can update your existing resources to check for both formats.

For example, update the attribute_condition in your Terraform configuration.

Before:

attribute_condition = "assertion.sub.startsWith(\"organization:my-org:workspace:my-workspace\")"

After:

attribute_condition = "assertion.sub.startsWith(\"organization:my-org:workspace:my-workspace\") || assertion.sub.startsWith(\"organization:my-org:project:my-proj:workspace:my-workspace\")"

This change allows the condition to accept either the old or new format.

Option 4: Azure

For Azure, you must create new federated identity credentials for each existing set of credentials, where the new credentials use the new subject format.

For example, if you have the following resource defined in Terraform:

resource "azuread_application_federated_identity_credential" "example_plan" {
  # ...
  issuer  = "https://app.terraform.io"
  subject = "organization:my-org:workspace:my-workspace:run_phase:plan"
}

You must create an additional federated credential resource that includes the project name in the subject.

resource "azuread_application_federated_identity_credential" "example_project_plan" {
  # ...
  issuer  = "https://app.terraform.io"
  subject = "organization:my-org:project:my-project:workspace:my-workspace:run_phase:plan"
}