Manually Generating Workload Identity Tokens
Important: If you are self-hosting Terraform Cloud Agents, ensure your agents use v1.7.0 or above. To use the latest dynamic credentials features, upgrade your agents to the latest version.
If required for custom auth workflows or to perform auth with providers that are not natively supported by dynamic credentials, you can request that Terraform Cloud inject a workload identity token into the run environment for usage in agent hooks.
Configure Terraform Cloud
Required Environment Variables
You’ll need to set the following environment variable in your Terraform Cloud workspace in order to have Terraform Cloud inject a workload identity token into the run environment. You can set this as a workspace variable, or if you’d like to inject tokens with the same audience value across multiple workspaces, you can use a variable set.
| Variable | Value | Notes |
|---|---|---|
TFC_WORKLOAD_IDENTITY_AUDIENCE | The desired value for the token’s audience. | Requires v1.7.0 or later if self-managing agents. Must be present and set or Terraform Cloud will not inject a workload identity token into the run environment. |
Generating Multiple Tokens
Important: If you are self-hosting Terraform Cloud Agents, ensure your agents use v1.12.0 or above. To use the latest dynamic credentials features, upgrade your agents to the latest version.
You can generate multiple tokens if you want distinct audience values for different consumers of your workload identity tokens. For more details, see Specifying Multiple Configurations.
You can generate multiple tokens by specifying additional variables in the following format: TFC_WORKLOAD_IDENTITY_AUDIENCE_[YOUR_TAG_HERE].
Your tag can only contain letters, numbers, and underscores and can not use reserved keywords. The following keywords are reserved: TYPE.
Each additional audience variable you specify generates an additional workload identity token that Terraform Cloud stores in variables with the format: TFC_WORKLOAD_IDENTITY_TOKEN_[YOUR_TAG_HERE].
Configure Agent Hooks
After you've set the TFC_WORKLOAD_IDENTITY_AUDIENCE variable, each plan and apply will have a TFC_WORKLOAD_IDENTITY_TOKEN variable available in the run environment, which contains a workload identity token.
You can use this environment variable in custom agent hooks to enable custom auth workflows or to perform auth with providers which are not natively supported by dynamic credentials.