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 lay the foundation to allow teams to safely self-manage workspaces, while enabling organization admins to maintain centralized control and enforce guardrails within a single Terraform Cloud or Terraform Enterprise organization.
To allow for scoping workload identity permissions to the project level on various cloud platforms the current format for the sub claim in the workload identity token will be changing from:
organization:[org name]:workspace:[workspace name]:run_phase:[run phase]to a format which includes the project name as shown below:
organization:[org name]:project:[project name]:workspace:[workspace name]:run_phase:[run phase]This document gives a quick overview of how users can prepare for projects in AWS, Vault, GCP, or Azure, while still maintaining compatibility with the current subject format.
Note: the default project name is Default Project which should be handled at a minimum for any subject comparisons that use the full subject value.
Required Changes
AWS
For example, an existing policy with conditions of:
"Condition": {
"StringEquals": {
“app.terraform.io:aud": "aws.workload.identity"
},
"StringLike": {
"app.terraform.io:sub":
"organization:my-org:workspace:my-ws:run_phase:*"
}
}
might become:
"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:*"
]
}
}
which will accept either the old or new format.
Vault
Vault allows for multiple values for bound claims which is also supported in the Vault provider. You will need to adjust the sub format in your bound_claims to handle the new format as appropriate.
For example, if you have something like the following for your bound claims in Terraform:
bound_claims_type = "glob"
bound_claims = {
sub = "organization:my-org:workspace:my-ws:run_phase:*"
}
you will need to change to:
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:*"
}
which will accept either the old or new format.
GCP
GCP allows for multiple checks via CEL conditions so you can reuse existing resources.
For example if you have something like the following attribute condition in Terraform:
attribute_condition =
"assertion.sub.startsWith(\"organization:my-org:workspace:my-workspace\")"
you will need to update this to something like:
attribute_condition =
"assertion.sub.startsWith(\"organization:my-org:workspace:my-workspace\") || assertion.sub.startsWith(\"organization:my-org:project:my-proj:workspace:my-workspace\")"
which will accept either the old or new format.
Azure
New federated identity credentials should be created for each existing set of federated identity credentials which use the new subject format instead of the old subject format.
For example, if you have something like the following 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 will also need to create a new federated credential of the form:
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"
}
Additional Information:
-
If additional support is needed, please contact HashiCorp Support.