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
In a nutshell
  • Each plan and apply gets its own token and temporary credentials.
  • The sub format is organization, project, workspace and run phase.
  • Always match aud and 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

An HCP Terraform run gets a signed workload identity token, the cloud provider checks its claims against the trust policy and returns temporary credentials, and the provider uses them with no static keys stored. 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.

HCP Terraformsigns a tokenOIDCCloud trust policychecks aud and subTemporary credentialsPlan or applyCredentials discarded

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 conditionWho can assume the role
Exact sub ending run_phase:planPlan phase of one workspace
sub ending run_phase:*, matched with StringLikeBoth phases of one workspace
workspace:* within one projectEvery workspace in that project
aud with no organization matchOther 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

TokenTied toKey limits
UserA personInherits their permissions; breaks automation if disabled
TeamA teamLimited to the team's workspaces; the usual choice for automation
OrganizationThe organizationOne at a time; meant for initial setup; cannot start runs
Audit trailThe organizationReads audit events; owners only
AgentAn agent poolOnly 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_AUTH and 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 sub format is organization, project, workspace and run phase.
  • Always match aud and 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.
Watch out

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.