Terraform Security and Governance · Topic 2 of 3
Securing Pipeline Identities and Access
Terraform Professional (002): secure pipelines with dynamic provider credentials, scoped OIDC trust, team tokens and least privilege permissions.
- 5 min
- Includes a diagram
- Each plan and apply gets its own token and temporary credentials.
- The
subformat is organization, project, workspace and run phase. - Always match
audand at least the organization name in the trust policy.
What it is
A pipeline usually holds two identities: one to reach the cloud provider, and one to reach HCP Terraform or Terraform Enterprise. A static key stored for either one is a long-lived target that someone must rotate.
The secure pattern is short-lived credentials issued per run, trust limited to exactly the workloads that need it, and tokens tied to a team rather than a person.
How it works
Dynamic provider credentials
HCP Terraform generates an OIDC workload identity token for each plan and each apply. The cloud platform verifies the token and returns temporary credentials, which are discarded when the run ends.
For AWS, set these as environment variables in the workspace or in a variable set.
TFC_AWS_PROVIDER_AUTH=true
TFC_AWS_PLAN_ROLE_ARN=arn:aws:iam::111122223333:role/tf-plan
TFC_AWS_APPLY_ROLE_ARN=arn:aws:iam::111122223333:role/tf-apply
TFC_AWS_RUN_ROLE_ARN is the single-role option; the plan and apply variables fall back to it. Separate roles let a plan, including one triggered by a pull request, use read-only access while only the apply can make changes. Azure also needs ARM_SUBSCRIPTION_ID and ARM_TENANT_ID.
Scoping the trust
The token's subject claim has a fixed format: organization:acme:project:networking:workspace:net-prod:run_phase:apply.
| Trust condition | Who can assume the role |
|---|---|
Exact sub ending run_phase:plan | Plan phase of one workspace |
sub ending run_phase:*, matched with StringLike | Both phases of one workspace |
workspace:* within one project | Every workspace in that project |
aud with no organization match | Other organizations' runs too, so never do this |
At a minimum, match the audience (aud) and the organization name. The audience stops a token meant for one platform being used on another. The token also carries claims such as terraform_workspace_name and terraform_run_phase, and the run ID helps with logging.
Vault-backed dynamic credentials
Here HCP Terraform authenticates to Vault, and a Vault secrets engine generates short-lived AWS, GCP or Azure credentials. Choose it when you want one central place for cloud credentials, or when Terraform Enterprise and Vault share a secure network and endpoints must stay off the public internet. Direct dynamic credentials need less setup and suit most cases.
API tokens
| Token | Tied to | Key limits |
|---|---|---|
| User | A person | Inherits their permissions; breaks automation if disabled |
| Team | A team | Limited to the team's workspaces; the usual choice for automation |
| Organization | The organization | One at a time; meant for initial setup; cannot start runs |
| Audit trail | The organization | Reads audit events; owners only |
| Agent | An agent pool | Only for agents; not valid for the API |
Give each token the shortest practical lifetime, because its expiration cannot change after creation. A token is shown once, so store it in your CI system's secret store or, better, fetch it from Vault.
The CLI reads a token from a credentials block in the CLI configuration or from an environment variable, which takes precedence over the file.
export TF_TOKEN_app_terraform_io="$TEAM_TOKEN"
Permissions
Team permissions apply at organization, project and workspace level, and they are additive: a user gets the highest level granted. Workspace roles are Read, Plan, Write and Admin, and HashiCorp recommends granting only what a job needs.
Remember the indirect routes too. Anyone who can merge to a branch connected to a workspace can cause plans there, so protect that branch.
Pipelines outside HCP Terraform
The same ideas apply to other CI systems. Authenticate with the identity the platform already issues, such as an OIDC token to Vault, and scope each role to one pipeline with short-lived tokens. Avoid secrets shared between pipelines.
Keep saved plan files out of unprotected artifacts, since they can hold sensitive values. Mark secret Terraform variables as sensitive so they are redacted from logs.
How the exam asks about this
- "Remove stored AWS keys from HCP Terraform workspaces." Use dynamic provider credentials with
TFC_AWS_PROVIDER_AUTHand a role ARN variable. - "Pull request plans must not be able to change production." Use separate plan and apply roles, matched on
run_phase. - "A pipeline that starts runs fails when it uses the organization token." Use a team token; organization tokens cannot start runs.
What to remember for the exam
- Each plan and apply gets its own token and temporary credentials.
- The
subformat is organization, project, workspace and run phase. - Always match
audand at least the organization name in the trust policy. - Team tokens fit routine automation; organization tokens fit initial setup.
TF_TOKEN_variables replace periods in the hostname with underscores and beat the CLI configuration file.- Permissions combine upward: the highest granted level wins.
A trust policy that does not check the organization can let workspaces in other organizations assume your role. Match the audience and organization at the very least.
Common mistakes
Using a person's user token in a pipeline. It carries that person's permissions and stops working if user tokens are disabled or the person leaves. Use a team token.
One powerful role for every phase. A shared role gives speculative plans write access they do not need. Split plan and apply roles.
Trusting the CI secret store alone. Storing a long-lived key there still leaves a key to steal and rotate. Replace it with short-lived credentials wherever possible.
Check yourself
Why use separate plan and apply roles with dynamic credentials?
So the plan phase, including plans from pull requests, holds read-only access and only the apply phase can change infrastructure.
Which token should a pipeline use to start runs in its team's workspaces?
A team token, which is not tied to a person and is limited to the workspaces that team can access.
What must a cloud trust policy check at a minimum?
The audience claim and the subject claim's organization name, so runs from other organizations cannot assume the role.
Topic 2 of 3 in Terraform Security and Governance
Test yourself on Terraform Security and Governance
The full HashiCorp Terraform Infrastructure Engineer Professional question bank has 600 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.