Dynamic Credentials with the Vault Provider

You can use Terraform Cloud’s native OpenID Connect integration with Vault to get dynamic credentials for the Vault provider in your Terraform Cloud runs. Configuring the integration requires the following steps:

1. Configure Vault: Set up a trust configuration between Vault and Terraform Cloud. Then, you must create Vault roles and policies for your Terraform Cloud workspaces.
2. Configure Terraform Cloud: Add environment variables to the Terraform Cloud workspaces where you want to use Dynamic Credentials.

Once you complete the setup, Terraform Cloud automatically authenticates to Vault during each run. The Vault provider authentication is valid for the length of the plan or apply. Vault does not revoke authentication until the run is complete.

If you are using Vault's secrets engines, you must complete the following set up before continuing to configure Vault-backed dynamic credentials.

Configure Vault

You must enable and configure the JWT backend in Vault. These instructions use the Vault CLI commands, but you can also use Terraform to configure Vault. Refer to our example Terraform configuration.

Enable the JWT Auth Backend

Run the following command to enable the JWT auth backend in Vault:

vault auth enable jwt

Configure Trust with Terraform Cloud

You must configure Vault to trust Terraform Cloud’s identity tokens and verify them using Terraform Cloud’s public key. The following command configures the jwt auth backend in Vault to trust Terraform Cloud as an OIDC identity provider:

vault write auth/jwt/config \
    oidc_discovery_url="https://app.terraform.io" \
    bound_issuer="https://app.terraform.io"

The oidc_discovery_url and bound_issuer should both be the root address of Terraform Cloud, including the scheme and without a trailing slash.

TFE Specific Requirements

If you are using a custom or self-signed CA certificate you may need to specify the CA certificate or chain of certificates, in PEM format, via the oidc_discovery_ca_pem argument as shown in the following example command:

vault write auth/jwt/config \
    oidc_discovery_url="https://app.terraform.io" \
    bound_issuer="https://app.terraform.io" \
    oidc_discovery_ca_pem=@my-cert.pem

In the example above, my-cert.pem is a PEM formatted file containing the certificate.

Create a Vault Policy

You must create a Vault policy that controls what paths and secrets your Terraform Cloud workspace can access in Vault. Create a file called tfc-policy.hcl with the following content:

# Allow tokens to query themselves
path "auth/token/lookup-self" {
  capabilities = ["read"]
}

# Allow tokens to renew themselves
path "auth/token/renew-self" {
    capabilities = ["update"]
}

# Allow tokens to revoke themselves
path "auth/token/revoke-self" {
    capabilities = ["update"]
}

# Configure the actual secrets the token should have access to
path "secret/*" {
  capabilities = ["read"]
}

Then create the policy in Vault:

vault policy write tfc-policy tfc-policy.hcl

Create a JWT Auth Role

Create a Vault role that Terraform Cloud can use when authenticating to Vault.

Vault offers a lot of flexibility in determining how to map roles and permissions in Vault to workspaces in Terraform Cloud. You can have one role for each workspace, one role for a group of workspaces, or one role for all workspaces in an organization. You can also configure different roles for the plan and apply phases of a run.

The following example creates a role called tfc-role. The role is mapped to a single workspace and Terraform Cloud can use it for both plan and apply runs.

Create a file called vault-jwt-auth-role.json with the following content:

{
  "policies": ["tfc-policy"],
  "bound_audiences": ["vault.workload.identity"],
  "bound_claims_type": "glob",
  "bound_claims": {
    "sub":
"organization:my-org-name:project:my-project-name:workspace:my-workspace-name:run_phase:*"
  },
  "user_claim": "terraform_full_workspace",
  "role_type": "jwt",
  "token_ttl": "20m"
}

Then run the following command to create a role named tfc-role with this configuration in Vault:

vault write auth/jwt/role/tfc-role @vault-jwt-auth-role.json

To understand all the available options for matching bound claims, refer to the Terraform workload identity claim specification and the Vault documentation on configuring bound claims. To understand all the options available when configuring Vault JWT auth roles, refer to the Vault API documentation.

Token TTLs

We recommend setting token_ttl to a relatively short value. Terraform Cloud can renew the token periodically until the plan or apply is complete, then revoke it to prevent it from being used further.

Configure Terraform Cloud

You’ll need to set some environment variables in your Terraform Cloud workspace in order to configure Terraform Cloud to authenticate with Vault using dynamic credentials. You can set these as workspace variables, or if you’d like to share one Vault role across multiple workspaces, you can use a variable set.

Required Environment Variables

Optional Environment Variables

You may need to set these variables, depending on your Vault configuration and use case.

Vault Provider Configuration

Once you set up dynamic credentials for a workspace, Terraform Cloud automatically authenticates to Vault for each run. Do not pass the address, token, or namespace arguments into the provider configuration block. Terraform Cloud sets these values as environment variables in the run environment.

You can use the Vault provider to read static secrets from Vault and use them with other Terraform resources. You can also access the other resources and data sources available in the Vault provider documentation. You must adjust your Vault policy to give your Terraform Cloud workspace access to all required Vault paths.

Specifying Multiple Configurations

You can add additional configurations to handle multiple distinct Vault setups, enabling you to use multiple provider aliases within the same workspace.

For more details, see Specifying Multiple Configurations.

Required Terraform Variable

To use additional configurations, add the following code to your Terraform configuration. This lets Terraform Cloud supply variable values that you can then use to map authentication and configuration details to the correct provider blocks.

variable "tfc_vault_dynamic_credentials" {
  description = "Object containing Vault dynamic credentials configuration"
  type = object({
    default = object({
      token_filename = string
      address = string
      namespace = string
      ca_cert_file = string
    })
    aliases = map(object({
      token_filename = string
      address = string
      namespace = string
      ca_cert_file = string
    }))
  })
}

Example Usage

provider "vault" {
  // skip_child_token must be explicitly set to true as TFC manages the token lifecycle
  skip_child_token = true
  address          = var.tfc_vault_dynamic_credentials.default.address
  namespace        = var.tfc_vault_dynamic_credentials.default.namespace

  auth_login_token_file {
    filename = var.tfc_vault_dynamic_credentials.default.token_filename
  }
}

provider "vault" {
  // skip_child_token must be explicitly set to true as TFC manages the token lifecycle
  skip_child_token = true
  alias            = "ALIAS1"
  address          = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].address
  namespace        = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].namespace

  auth_login_token_file {
    filename = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].token_filename
  }
}