Authenticate Providers with Dynamic Credentials

15min
Terraform

Terraform Cloud's dynamic provider credentials let you establish a trust relationship between Terraform Cloud and your cloud provider. They limit the blast radius of compromised credentials by using unique, short-lived credentials for each Terraform run. Dynamic credentials also give you fine-grained control over the resources that each of your Terraform Cloud projects and workspaces can manage. Terraform Cloud supports dynamic credentials for AWS, Google Cloud Platform, Azure, and Vault.

When you use dynamic credentials, Terraform Cloud begins each run by authenticating with your cloud provider, passing it details about the workload, including your organization and workspace name. Your cloud provider then responds with temporary credentials which Terraform Cloud uses to provision your resources for the run. This workflow is based on the OpenID Connect protocol (OIDC), an open source standard for verifying identity across different systems.

In this tutorial, you will set up a trust relationship between Terraform Cloud and your cloud provider, and configure a workspace with dynamic credentials. Then you will use dynamic credentials to provision infrastructure for that workspace.

Prerequisites

This tutorial assumes that you are familiar with the Terraform and Terraform Cloud workflows. If you are new to Terraform, complete the Get Started collection first. If you are new to Terraform Cloud, complete the Terraform Cloud Get Started tutorials first.

For this tutorial, you will need:

Terraform v1.2+ installed locally.
a Terraform Cloud account and organization.
An account with one of the supported cloud providers: AWS, Google Cloud Platform, Microsoft Azure, or Vault.

We recommend you use a non-production HCP Vault cluster to complete this tutorial.

Visit your Vault instance's Overview page in HCP, and create a new admin token, and use it to set the VAULT_TOKEN environment variable in your local environment.

$ export VAULT_TOKEN=<YOUR_TOKEN>

Find your vault cluster's public URL in HCP, and use it to set the VAULT_ADDR environment variable.

$ export VAULT_ADDR=https://<YOUR_CLUSTER>.hashicorp.cloud:8200

Set your Vault namespace to admin.

$ export VAULT_NAMESPACE=admin

Note: If you are using Vault Open Source or Vault Enterprise, set these three environment variables to the appropriate values for your installation.

Create example repository

Visit the template repository for this tutorial. Click the Use this template button and select Create a New Repository. Choose the GitHub owner that you use with Terraform Cloud, and name the new repository learn-terraform-dynamic-credentials. Leave the rest of the settings at their default values.

Clone example repository

Clone the new repository, which contains Terraform configuration to create the trust relationship between your cloud provider and Terraform Cloud. Find the URL to your repository by clicking the Code button on GitHub, or customize the following command.

$ git clone https://github.com/<YOUR_USERNAME>/learn-terraform-dynamic-credentials.git

Replace <YOUR_USERNAME> with your GitHub user name.

Change into the example repository directory.

$ cd learn-terraform-dynamic-credentials

The example repository includes Terraform configuration to create trust relationships for each supported cloud provider. Change into the appropriate subdirectory for your cloud provider.

$ cd vault/trust

Configure trust with your cloud provider

To use dynamic credentials, you must first establish a trust relationship between your cloud provider and Terraform Cloud. You will also create the roles and policies that define the resources and services the dynamic credentials can manage.

In this tutorial, you will create the trust relationship by running Terraform commands locally. In production, you may prefer to manage your trust relationships in their own Terraform Cloud workspaces.

Review trust relationship configuration

Open main.tf and review the configuration for your trust relationship.

The configuration first defines the Vault provider.

main.tf

provider "vault" {}

Vault will use Terraform Cloud's TLS certificate to verify that requests for dynamic credentials come from Terraform Cloud.

Next, the configuration sets up a JWT auth backend to establish a trust relationship with Terraform Cloud. Vault will validate Terraform's TLS certificate before accepting any requests for dynamic credentials.

main.tf

resource "vault_jwt_auth_backend" "tfc_jwt" {
  path               = var.jwt_backend_path
  type               = "jwt"
  oidc_discovery_url = "https://${var.tfc_hostname}"
  bound_issuer       = "https://${var.tfc_hostname}"
}

Next the configuration defines a role for the trust relationship. If the request meets the role's conditions, Vault will provide Terraform Cloud with dynamic credentials that assume this role. The role is attached to a policy which you will review in the next section. The configuration also sets a unique identifier for your cloud provider called an audience.

main.tf

resource "vault_jwt_auth_backend_role" "tfc_role" {
  backend        = vault_jwt_auth_backend.tfc_jwt.path
  role_name      = "tfc-role"
  token_policies = [vault_policy.tfc_policy.name]

  bound_audiences = [var.tfc_vault_audience]

  bound_claims_type = "glob"
  bound_claims = {
    sub = "organization:${var.tfc_organization_name}:project:${var.tfc_project_name}:workspace:${var.tfc_workspace_name}:run_phase:*"
  }

  user_claim = "terraform_full_workspace"
  role_type  = "jwt"
  token_ttl  = 1200
}

The configuration first defines the AWS provider and retrieves Terraform Cloud's TLS certificate.

main.tf

provider "aws" {
  region = var.aws_region
}

data "tls_certificate" "tfc_certificate" {
  url = "https://${var.tfc_hostname}"
}

AWS will use this TLS certificate to verify that requests for dynamic credentials come from Terraform Cloud.

Next the configuration sets up an OIDC provider in AWS with Terraform Cloud's TLS certificate, the SHA1 fingerprint from the TLS certificate, and a unique identifier for your cloud provider called an audience.

main.tf

resource "aws_iam_openid_connect_provider" "tfc_provider" {
  url             = data.tls_certificate.tfc_certificate.url
  client_id_list  = [var.tfc_aws_audience]
  thumbprint_list = [data.tls_certificate.tfc_certificate.certificates[0].sha1_fingerprint]
}

Then the configuration defines an IAM role for the trust relationship. If the request meets the role's conditions, AWS will provide Terraform Cloud with dynamic credentials that assume this role.

main.tf

resource "aws_iam_role" "tfc_role" {
  name = "tfc-role"

  assume_role_policy = <<EOF
{
 "Version": "2012-10-17",
 "Statement": [
   {
     "Effect": "Allow",
     "Principal": {
       "Federated": "${aws_iam_openid_connect_provider.tfc_provider.arn}"
     },
     "Action": "sts:AssumeRoleWithWebIdentity",
     "Condition": {
       "StringEquals": {
         "${var.tfc_hostname}:aud": "${one(aws_iam_openid_connect_provider.tfc_provider.client_id_list)}"
       },
       "StringLike": {
         "${var.tfc_hostname}:sub": "organization:${var.tfc_organization_name}:project:${var.tfc_project_name}:workspace:${var.tfc_workspace_name}:run_phase:*"
       }
     }
   }
 ]
}
EOF
}

The configuration first defines the GCP provider with your project ID, retrieves data about your project, and enables the GCP services you will use to configure the trust relationship.

main.tf

provider "google" {
  project = var.gcp_project_id
  region  = "global"
}

data "google_project" "project" {
}

resource "google_project_service" "services" {
  count   = length(var.gcp_service_list)
  service = var.gcp_service_list[count.index]
}

Next the configuration creates an IAM workload identity pool and provider for the trust relationship. The workload identity pool provider maps GCP attributes to their corresponding OIDC assertions, and configures the relationship to use Terraform Cloud. GCP will automatically verify that requests for credentials come from Terraform Cloud using its TLS certificate.

The commented example configuration can be used to set a unique identifier for your cloud provider called an audience. This configuration does not set a value for allowed audiences, so the provider will use the default value.

Finally, the attribute_condition attribute defines the TFC organization, project, and workspace that can use the trust relationship.

main.tf

resource "google_iam_workload_identity_pool" "tfc_pool" {
  workload_identity_pool_id = "my-tfc-pool"
}

resource "google_iam_workload_identity_pool_provider" "tfc_provider" {
  workload_identity_pool_id          = google_iam_workload_identity_pool.tfc_pool.workload_identity_pool_id
  workload_identity_pool_provider_id = "my-tfc-provider-id"

  attribute_mapping = {
    "google.subject"                        = "assertion.sub",
    "attribute.aud"                         = "assertion.aud",
    "attribute.terraform_run_phase"         = "assertion.terraform_run_phase",
    "attribute.terraform_project_id"        = "assertion.terraform_project_id",
    "attribute.terraform_project_name"      = "assertion.terraform_project_name",
    "attribute.terraform_workspace_id"      = "assertion.terraform_workspace_id",
    "attribute.terraform_workspace_name"    = "assertion.terraform_workspace_name",
    "attribute.terraform_organization_id"   = "assertion.terraform_organization_id",
    "attribute.terraform_organization_name" = "assertion.terraform_organization_name",
    "attribute.terraform_run_id"            = "assertion.terraform_run_id",
    "attribute.terraform_full_workspace"    = "assertion.terraform_full_workspace",
  }
  oidc {
    issuer_uri = "https://${var.tfc_hostname}"
    # The default audience format used by TFC is of the form:
    # //iam.googleapis.com/projects/{project number}/locations/global/workloadIdentityPools/{pool ID}/providers/{provider ID}
    # which matches with the default accepted audience format on GCP.
    #
    # Uncomment the line below if you are specifying a custom value for the audience instead of using the default audience.
    # allowed_audiences = [var.tfc_gcp_audience]
  }
  attribute_condition = "assertion.sub.startsWith(\"organization:${var.tfc_organization_name}:project:${var.tfc_project_name}:workspace:${var.tfc_workspace_name}\")"
}

The configuration first defines the Azure Resource Manager and Active Directory providers, retrieves data about your subscription, and creates an application to own the trust relationship.

main.tf

provider "azurerm" {
  features {}
}

provider "azuread" {}

data "azurerm_subscription" "current" {}

resource "azuread_application" "tfc_application" {
  display_name = "tfc-application"
}

Next the configuration defines two federated identity credentials, one for planning configuration changes, and the second to apply them. It configures each of them to accept requests from Terraform Cloud using the default audience. Azure will automatically verify that requests for credentials come from Terraform Cloud using its TLS certificate. The subject attribute defines the TFC organization, project, and workspace that can use the trust relationship.

main.tf

resource "azuread_application_federated_identity_credential" "tfc_federated_credential_plan" {
  application_object_id = azuread_application.tfc_application.object_id
  display_name          = "my-tfc-federated-credential-plan"
  audiences             = [var.tfc_azure_audience]
  issuer                = "https://${var.tfc_hostname}"
  subject               = "organization:${var.tfc_organization_name}:project:${var.tfc_project_name}:workspace:${var.tfc_workspace_name}:run_phase:plan"
}

resource "azuread_application_federated_identity_credential" "tfc_federated_credential_apply" {
  application_object_id = azuread_application.tfc_application.object_id
  display_name          = "my-tfc-federated-credential-apply"
  audiences             = [var.tfc_azure_audience]
  issuer                = "https://${var.tfc_hostname}"
  subject               = "organization:${var.tfc_organization_name}:project:${var.tfc_project_name}:workspace:${var.tfc_workspace_name}:run_phase:apply"
}

This configuration ensures that your cloud provider will check that requests for dynamic credentials satisfy the following OIDC claims:

aud: The audience of the token, a unique case-sensitive string that identifies your cloud provider. This ensures that a request for dynamic credentials intended for one cloud provider is invalid for other providers. You may want to customize the audience for certain advanced use cases, such as using multiple sets of dynamic credentials with a single cloud provider. For this tutorial, use the default value for the audience.
sub: The subject of the token, which includes the Terraform Cloud organization name, project, and workspace that can use this trust relationship. This ensures that your cloud provider only authenticates requests for the specified projects and workspaces in your organization, and lets you scope permissions on a per-project or per-workspace basis.

Tip

Refer to the Dynamic Credentials documentation for a list of other possible claims.

The sub claim includes four parts separated by colons (:):

Claim	Value	Purpose
`organization`	`${var.tfc_organization_name}`	Your TFC organization name
`project`	`${var.tfc_project_name}`	Your TFC project name
`workspace`	`${var.tfc_workspace_name}`	Your TFC workspace name
`run_phase`	`plan` or `apply`	The Terraform workflow phase

Tip: Refer to the Dynamic Credentials documentation for a list of other possible claims.

The example configuration uses the bound claims type glob and the glob character (*) to allow any workflow phase. When you define your trust relationships, you can also use * to allow requests from any workspace within a named project, or any project in your organization. Depending on your organization's needs, you can configure a single trust relationship for each cloud provider, or separate trust relationships for each project or workspace.

The example configuration uses the StringLike function and the glob (*) character to allow any workflow phase. When you define your trust relationships, you can also use * to allow requests from any workspace within a named project, or any project in your organization. Depending on your organization's needs, you can configure a single trust relationship for each cloud provider, or separate trust relationships for each project or workspace.

The example configuration uses the startsWith function to allow any workflow phase. When you define your trust relationships, you can also use startsWith to allow requests from any workspace within a named project, or any project in your organization by ommitting those parts of the claim. Depending on your organization's needs, you can configure a single trust relationship for each cloud provider, or separate trust relationships for each project or workspace.

For each run, after your cloud provider verifies that the request is signed by Terraform Cloud with the provided TLS certificate, Terraform Cloud will provide a Terraform Workload Identity (TWI) token that includes information about the run, such as the organization, project, and workspace. Your cloud provider will then use Terraform Cloud's OIDC metadata and public signing key to verify that the token was generated by Terraform Cloud and the information it contains has not been tampered with. Once verified, if the token matches the conditions for your trust relationship, your cloud provider will respond with a set of dynamic credentials that use the configured role. Terraform Cloud will then use those dynamic credentials to provision your resources.

Warning: Always include the audience and the name of your Terraform Cloud organization when you configure claims. They make sure the claims are only valid for your intended cloud provider, and prevent unauthorized access from other Terraform Cloud organizations.

Finally, the configuration defines the policy that specifies which resources your dynamic credentials can manage.

main.tf

resource "vault_policy" "tfc_policy" {
  name = "tfc-policy"

  policy = <<EOT
# 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"]
}

path "sys/mounts" {
  capabilities = ["list", "read"]
}

path "sys/mounts/example" {
  capabilities = ["create", "read", "update", "patch", "delete", "list"]
}

path "example/*" {
  capabilities = ["create", "read", "update", "patch", "delete", "list"]
}
EOT
}

This policy allows full access to the example path. Policies give you fine-grained control over the permissions granted by your dynamic credentials.

Finally, the configuration defines the IAM policy that specifies which resources your dynamic credentials can manage, and attaches that policy to the role.

main.tf

resource "aws_iam_policy" "tfc_policy" {
  name        = "tfc-policy"
  description = "TFC run policy"

  policy = <<EOF
{
 "Version": "2012-10-17",
 "Statement": [
   {
     "Effect": "Allow",
     "Action": [
       "ec2:*"
     ],
     "Resource": "*"
   }
 ]
}
EOF
}

resource "aws_iam_role_policy_attachment" "tfc_policy_attachment" {
  role       = aws_iam_role.tfc_role.name
  policy_arn = aws_iam_policy.tfc_policy.arn
}

This policy allows all operations on EC2 instances. IAM policies give you fine-grained control over the permissions granted by your dynamic credentials.

Finally, the configuration defines a service account for your trust relationship, attaches it to your identity pool, and grants the service account the Editor role for your project.

main.tf

resource "google_service_account" "tfc_service_account" {
  account_id   = "tfc-service-account"
  display_name = "Terraform Cloud Service Account"
}

resource "google_service_account_iam_member" "tfc_service_account_member" {
  service_account_id = google_service_account.tfc_service_account.name
  role               = "roles/iam.workloadIdentityUser"
  member             = "principalSet://iam.googleapis.com/${google_iam_workload_identity_pool.tfc_pool.name}/*"
}

resource "google_project_iam_member" "tfc_project_member" {
  project = var.gcp_project_id
  role    = "roles/editor"
  member  = "serviceAccount:${google_service_account.tfc_service_account.email}"
}

This policy allows editor access to your project. IAM policies give you fine-grained control over the permissions granted by your dynamic credentials with either predifined or custom roles.

Finally, the configuration asigns the service principal to the Contributor role for your current subscription.

main.tf

resource "azurerm_role_assignment" "tfc_role_assignment" {
  scope                = data.azurerm_subscription.current.id
  principal_id         = azuread_service_principal.tfc_service_principal.object_id
  role_definition_name = "Contributor"
}

This role assignment allows contributor-level access to your subscription. Azure roles give you fine-grained control over the permissions granted by your dynamic credentials with either predifined or custom roles.

You can configure the policies attached to your trust relationships to be as restrictive or permissive as you need.

Configure organization and workspace name

In the trust directory for your cloud provider, copy the example .tfvars file to configure your organization and workspace name.

$ cp terraform.tfvars.example terraform.tfvars

Open terraform.tfvars and set your organization and workspace name. These values are used to define the OIDC subject for your trust relationship's policy.

terraform.tfvars

tfc_organization_name = "<YOUR_ORG>"
tfc_workspace_name    = "learn-terraform-dynamic-credentials"

Replace <YOUR_ORG> with your Terraform Cloud organization name. Use the given workspace name for this tutorial.

Initialize configuration

Initialize your Terraform configuration.

$ terraform init

Apply configuration

Apply this configuration to create your trust relationship. Respond to the confirmation prompt with a yes.

$ terraform apply
terraform apply

Terraform used the selected providers to generate the following execution plan.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # vault_jwt_auth_backend.tfc_jwt will be created
  + resource "vault_jwt_auth_backend" "tfc_jwt" {
##...
Plan: 3 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + openid_claims = {
      + "sub" = "organization:<YOUR_ORG>:project:Default Project:workspace:learn-terraform-dynamic-credentials:run_phase:*"
    }
  + run_role      = "tfc-role"

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

vault_policy.tfc_policy: Creating...
vault_jwt_auth_backend.tfc_jwt: Creating...
vault_policy.tfc_policy: Creation complete after 0s [id=tfc-policy]
vault_jwt_auth_backend.tfc_jwt: Creation complete after 1s [id=jwt]
vault_jwt_auth_backend_role.tfc_role: Creating...
vault_jwt_auth_backend_role.tfc_role: Creation complete after 0s [id=auth/jwt/role/tfc-role]

Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Outputs:

openid_claims = tomap({
  "sub" = "organization:<YOUR_ORG>:project:Default Project:workspace:learn-terraform-dynamic-credentials:run_phase:*"
})
run_role = "tfc-role"

You will use the run_role output value in the next section.

$ terraform apply
data.tls_certificate.tfc_certificate: Reading...
data.tls_certificate.tfc_certificate: Read complete after 0s [id=896bd9f2e4b99335cca9e93921664e636e35cab3]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # aws_iam_openid_connect_provider.tfc_provider will be created
  + resource "aws_iam_openid_connect_provider" "tfc_provider" {
##...
Plan: 4 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + openid_claims = (known after apply)
  + role_arn      = (known after apply)

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

aws_iam_policy.tfc_policy: Creating...
aws_iam_openid_connect_provider.tfc_provider: Creating...
aws_iam_openid_connect_provider.tfc_provider: Creation complete after 0s [id=arn:aws:iam::812345678901:oidc-provider/app.terraform.io]
aws_iam_role.tfc_role: Creating...
aws_iam_policy.tfc_policy: Creation complete after 0s [id=arn:aws:iam::812345678901:policy/tfc-policy]
aws_iam_role.tfc_role: Creation complete after 1s [id=tfc-role]
aws_iam_role_policy_attachment.tfc_policy_attachment: Creating...
aws_iam_role_policy_attachment.tfc_policy_attachment: Creation complete after 0s [id=tfc-role-20230123162051967100000001]

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

Outputs:

openid_claims = {
  "StringEquals" = {
    "app.terraform.io:aud" = "aws.workload.identity"
  }
  "StringLike" = {
    "app.terraform.io:sub" = "organization:<YOUR_ORG>:project:Default Project:workspace:learn-terraform-dynamic-credentials:run_phase:*"
  }
}
role_arn = "arn:aws:iam::812345678901:role/tfc-role"

You will use the role_arn output value in the next section.

$ terraform apply
data.google_project.project: Reading...
data.google_project.project: Read complete after 1s [id=projects/hc-601cc6bb16504507af3f98e938a]

Terraform used the selected providers to generate the following execution plan.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # google_iam_workload_identity_pool.tfc_pool will be created
  + resource "google_iam_workload_identity_pool" "tfc_pool" {
##...
Plan: 9 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + openid_claims         = "assertion.sub.startsWith(\"organization:<YOUR_ORG>:project:Default Project:workspace:learn-terraform-dynamic-credentials\")"
  + project_id            = "projects/hc-601cc6bb16504507af3f98e938a"
  + project_number        = "200260489446"
  + service_account_email = (known after apply)
  + workload_pool_id      = "my-tfc-pool"
  + workload_provider_id  = "my-tfc-provider-id"

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

google_service_account.tfc_service_account: Creating...
google_project_service.services[3]: Creating...
google_iam_workload_identity_pool.tfc_pool: Creating...
google_project_service.services[2]: Creating...
google_project_service.services[1]: Creating...
google_project_service.services[0]: Creating...
google_service_account.tfc_service_account: Creation complete after 1s [id=projects/hc-601cc6bb16504507af3f98e938a/serviceAccounts/tfc-service-account@hc-601cc6bb16504507af3f98e938a.iam.gserviceaccount.com]
google_project_iam_member.tfc_project_member: Creating...
google_project_service.services[0]: Creation complete after 3s [id=hc-601cc6bb16504507af3f98e938a/iam.googleapis.com]
google_project_service.services[3]: Creation complete after 3s [id=hc-601cc6bb16504507af3f98e938a/iamcredentials.googleapis.com]
google_project_service.services[2]: Creation complete after 3s [id=hc-601cc6bb16504507af3f98e938a/sts.googleapis.com]
google_project_service.services[1]: Creation complete after 3s [id=hc-601cc6bb16504507af3f98e938a/cloudresourcemanager.googleapis.com]
google_project_iam_member.tfc_project_member: Creation complete after 7s [id=hc-601cc6bb16504507af3f98e938a/roles/editor/serviceAccount:tfc-service-account@hc-601cc6bb16504507af3f98e938a.iam.gserviceaccount.com]
google_iam_workload_identity_pool.tfc_pool: Still creating... [10s elapsed]
google_iam_workload_identity_pool.tfc_pool: Creation complete after 11s [id=projects/hc-601cc6bb16504507af3f98e938a/locations/global/workloadIdentityPools/my-tfc-pool]
google_iam_workload_identity_pool_provider.tfc_provider: Creating...
google_service_account_iam_member.tfc_service_account_member: Creating...
google_service_account_iam_member.tfc_service_account_member: Creation complete after 4s [id=projects/hc-601cc6bb16504507af3f98e938a/serviceAccounts/tfc-service-account@hc-601cc6bb16504507af3f98e938a.iam.gserviceaccount.com/roles/iam.workloadIdentityUser/principalSet://iam.googleapis.com/projects/200260489446/locations/global/workloadIdentityPools/my-tfc-pool/*]
google_iam_workload_identity_pool_provider.tfc_provider: Still creating... [10s elapsed]
google_iam_workload_identity_pool_provider.tfc_provider: Creation complete after 10s [id=projects/hc-601cc6bb16504507af3f98e938a/locations/global/workloadIdentityPools/my-tfc-pool/providers/my-tfc-provider-id]

Apply complete! Resources: 9 added, 0 changed, 0 destroyed.

Outputs:

openid_claims = "assertion.sub.startsWith(\"organization:<YOUR_ORG>:project:Default Project:workspace:learn-terraform-dynamic-credentials\")"
project_id = "projects/hc-601cc6bb16504507af3f98e938a"
project_number = "200260489446"
service_account_email = "tfc-service-account@hc-601cc6bb16504507af3f98e938a.iam.gserviceaccount.com"
workload_pool_id = "my-tfc-pool"
workload_provider_id = "my-tfc-provider-id"

You will use the output values in the next section.

$ terraform apply
data.azurerm_subscription.current: Reading...
data.azurerm_subscription.current: Read complete after 1s [id=/subscriptions/b558524e-d2bb-4d1b-9437-f47c388fc0e7]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the
following symbols:
  + create

Terraform will perform the following actions:

  # azuread_application.tfc_application will be created
  + resource "azuread_application" "tfc_application" {
##...
Plan: 5 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + openid_claims   = [
      + "organization:<YOUR_ORG>:project:Default Project:workspace:learn-terraform-dynamic-credentials:run_phase:plan",
      + "organization:<YOUR_ORG>:project:Default Project:workspace:learn-terraform-dynamic-credentials:run_phase:apply",
    ]
  + run_client_id   = (known after apply)
  + subscription_id = "b558524e-d2bb-4d1b-9437-f47c388fc0e7"
  + tenant_id       = "157db1e6-8420-42f1-bf83-d717bed116a7"

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

azuread_application.tfc_application: Creating...
azuread_application.tfc_application: Creation complete after 1s [id=81c2df4e-2089-4bc4-825c-d3afabc1c30d]
azuread_application_federated_identity_credential.tfc_federated_credential_plan: Creating...
azuread_application_federated_identity_credential.tfc_federated_credential_apply: Creating...
azuread_service_principal.tfc_service_principal: Creating...
azuread_service_principal.tfc_service_principal: Creation complete after 2s [id=638d2773-a0a0-4974-a658-08d3e085832a]
azuread_application_federated_identity_credential.tfc_federated_credential_plan: Creation complete after 5s [id=81c2df4e-2089-4bc4-825c-d3afabc1c30d/federatedIdentityCredential/427126d1-bc19-4263-992b-c4e8369af73b]
azuread_application_federated_identity_credential.tfc_federated_credential_apply: Creation complete after 10s [id=81c2df4e-2089-4bc4-825c-d3afabc1c30d/federatedIdentityCredential/62408c73-8185-4a75-bba3-186592bad0b1]
azurerm_role_assignment.tfc_role_assignment: Creating...
azurerm_role_assignment.tfc_role_assignment: Still creating... [10s elapsed]
azurerm_role_assignment.tfc_role_assignment: Still creating... [20s elapsed]
azurerm_role_assignment.tfc_role_assignment: Creation complete after 29s [id=/subscriptions/b558524e-d2bb-4d1b-9437-f47c388fc0e7/providers/Microsoft.Authorization/roleAssignments/1efd1697-cb09-aa60-9b92-aca889a758d6]

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

Outputs:

openid_claims = [
  "organization:<YOUR_ORG>:project:Default Project:workspace:learn-terraform-dynamic-credentials:run_phase:plan",
  "organization:<YOUR_ORG>:project:Default Project:workspace:learn-terraform-dynamic-credentials:run_phase:apply",
]
run_client_id = "d7ef60c5-21e2-4be0-8a04-7f0d5fc4aa18"
subscription_id = "b558524e-d2bb-4d1b-9437-f47c388fc0e7"
tenant_id = "157db1e6-8420-42f1-bf83-d717bed116a7"

You will use the output values in the next section.

Terraform Cloud can now use this trust relationship to request dynamic credentials when it provisions infrastructure for the learn-terraform-dynamic-credentials workspace in your default project.

Provision infrastructure with dynamic credentials

Use your trust relationship to provision infrastructure in Terraform Cloud. First, navigate to the infra directory and review the example configuration.

cd ../infra

This configuration defines a single secret in an example mount.

main.tf

provider "vault" {}

resource "vault_mount" "example" {
  path    = "example"
  type    = "kv-v2"
  options = { version = "2" }
}

resource "vault_kv_secret_v2" "example" {
  mount = vault_mount.example.path

  name                = "unsecret"
  cas                 = 1
  delete_all_versions = true
  data_json = jsonencode(
    {
      foo = "bar"
    }
  )
}

This configuration defines a single EC2 instance in the us-east-2 region.

main.tf

provider "aws" {
  region = var.aws_region
}

data "aws_ami" "amazon_linux" {
  most_recent = true
  owners    = ["amazon"]

  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
  }
}

resource "aws_instance" "web" {
  ami           = data.aws_ami.amazon_linux.id
  instance_type = var.instance_type

  user_data = <<-EOF
    #!/bin/bash
    sudo yum update -y
    sudo yum install httpd -y
    sudo systemctl enable httpd
    sudo systemctl start httpd
    echo "<html><body><div>Hello, world!</div></body></html>" > /var/www/html/index.html
    EOF

  tags = var.tags
}

This configuration defines a single compute instance in the us-east1 region.

main.tf

provider "google" {
  project = var.gcp_project_id
  region  = var.gcp_region
  zone    = var.gcp_zone
}

resource "google_compute_instance" "vm_instance" {
  name         = "terraform-instance"
  machine_type = var.machine_type

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-11"
    }
  }

  network_interface {
    network = "default"
    access_config {
    }
  }

  metadata_startup_script = <<-EOF
    #!/bin/bash
    sudo yum update -y
    sudo yum install httpd -y
    sudo systemctl enable httpd
    sudo systemctl start httpd
    echo "<html><body><div>Hello, world!</div></body></html>" > /var/www/html/index.html
    EOF

  tags = var.tags
}

This configuration defines a network and subnet in the eastus location.

main.tf

provider "azurerm" {
  features {
    resource_group {
      prevent_deletion_if_contains_resources = false
    }
  }
}

resource "azurerm_resource_group" "example" {
  name     = "exampleTFResourceGroup"
  location = var.azure_location
}

resource "azurerm_virtual_network" "example" {
  name                = "example-network"
  address_space       = ["10.0.0.0/16"]
  location            = azurerm_resource_group.example.location
  resource_group_name = azurerm_resource_group.example.name
}

resource "azurerm_subnet" "example" {
  name                 = "internal"
  resource_group_name  = azurerm_resource_group.example.name
  virtual_network_name = azurerm_virtual_network.example.name
  address_prefixes     = ["10.0.2.0/24"]
}

Create infrastructure workspace

Now, navigate to Terraform Cloud in your web browser, and select your organization.

Create a new workspace in your default project by selecting New > Workspace on the Projects & workspaces page. Configure it with the following settings.

Select Version control workflow.
Choose the learn-terraform-dynamic-credentials GitHub repository that you created earlier in this tutorial. If you have not yet connected your GitHub account to Terraform Cloud, follow the prompts to do so. Refer to the Use VCS-Driven Workflow tutorial for detailed instructions.
On the Configure settings step, expand the Advanced options interface, and set the Terraform Working Directory to the appropriate one for your cloud provider.
vault/infra
Leave the rest of the settings on the Configure settings step at their default values, then click Create Workspace.

Configure trust variables

After you create your workspace, navigate to its Variables page and add the following workspace variables:

Variable category	Key	Value	Sensitive
Environment variable	`TFC_VAULT_PROVIDER_AUTH`	`true`	No
Environment variable	`TFC_VAULT_ADDR`	The address of your Vault instance	No
Environment variable	`TFC_VAULT_RUN_ROLE`	`vault_run_role` output from previous run	No
Environment variable	`TFC_VAULT_NAMESPACE`	`admin`	No

The TFC_VAULT_PROVIDER_AUTH variable configures the workspace to use dynamic credentials for the Vault provider, and the other variables identify your Vault instance and the role Vault will use to provision resources with dynamic credentials.

Variable category	Key	Value	Sensitive
Environment variable	`TFC_AWS_PROVIDER_AUTH`	`true`	No
Environment variable	`TFC_AWS_RUN_ROLE_ARN`	`role_arn` output from previous run	No

The TFC_AWS_PROVIDER_AUTH variable configures the workspace to use dynamic credentials for the AWS provider, and TFC_AWS_RUN_ROLE_ARN is the ARN of the role that AWS will use to provision resources with dynamic credentials.

Variable category	Key	Value	Sensitive
Environment variable	`TFC_GCP_PROVIDER_AUTH`	`true`	No
Terraform variable	`gcp_project_id`	`project_id` output from previous run	No
Environment variable	`TFC_GCP_PROJECT_NUMBER`	`project_number` output from previous run	No
Environment variable	`TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL`	`service_account_email` output from previous run	No
Environment variable	`TFC_GCP_WORKLOAD_POOL_ID`	`workload_pool_id` output from previous run	No
Environment variable	`TFC_GCP_WORKLOAD_PROVIDER_ID`	`workload_provider_id` output from previous run	No

The TFC_GCP_PROVIDER_AUTH variable configures the workspace to use dynamic credentials for the GCP provider, and the other variables identify the project and other resources that GCP will use to provision resources with dynamic credentials.

Variable category	Key	Value	Sensitive
Environment variable	`TFC_AZURE_PROVIDER_AUTH`	`true`	No
Environment variable	`TFC_AZURE_RUN_CLIENT_ID`	`run_client_id` output from previous run	No
Environment variable	`ARM_SUBSCRIPTION_ID`	`subscription_id` output from previous run	No
Environment variable	`ARM_TENANT_ID`	`tenant_id` output from previous run	No

The TFC_AZURE_PROVIDER_AUTH variable configures the workspace to use dynamic credentials for the Azure provider, and the other variables identify the tenant, subscription, and run client that Azure will use to provision resources with dynamic credentials.

Tip

If you closed the terminal window with the output values from the trust configuration, return to the trust directory and run terraform output to display them.

Apply configuration

From your workspace's Actions menu, select Start new run. Choose the Plan and apply run type. Then click Start run.

Terraform Cloud requests dynamic credentials from your cloud provider, and uses them to perform a speculative plan. Once the plan is complete, click the Confirm & Apply button, then Confirm Plan to apply it. Terraform Cloud will request another set of dynamic credentials and use them for the apply step.

Once the plan and apply steps are complete, review the results.

Apply complete screen

Now you have provisioned infrastructure with Terraform Cloud using dynamic credentials instead of long-lived credentials. Since you do not need to store the credentials themselves in Terraform Cloud, this reduces the potential for accidental exposure. Defining the role and permissions for the dynamic credentials lets you specify exactly which operations those keys can be used for.

In your organization, different teams may be responsible for managing trust relationships and deploying infrastructure. For example, a security team could configure and manage the workspaces that define trust relationships, while infrastructure teams configure and manage downstream workspaces that use the trust relationships from the security team. When different teams manage trust and infrastructure, consider how you will coordinate changes to maintain scoped trust relationships while still enabling the downstream teams that rely on them.

Remember that trust relationships reference your organization, project, and workspace names, so changing any of those values within Terraform Cloud can potentially break your trust relationships.

Clean up your infrastructure

Remove the infrastructure and trust relationship that you created in this tutorial.

Destroy infrastructure

First, remove the infrastructure you created in this tutorial. In Terraform Cloud, navigate to Settings > Destruction and Deletion. From there, select the Queue destroy plan button and follow the prompts to plan and apply a destroy workflow, which also uses dynamic credentials.

Delete infrastructure workspace

After destroying your infrastructure, delete the workspace from Terraform Cloud. From the Settings > Destruction and Deletion page, select the Delete from Terraform Cloud button and follow the prompts to delete the workspace.

Destroy trust relationship

Destroy the trust relationship you created in this tutorial.

In your terminal window, navigate to the trust directory.

cd ../trust

Use Terraform to destroy these resources. Respond to the confirmation prompt with a yes.

$ terraform destroy
data.tls_certificate.tfc_certificate: Reading...
data.tls_certificate.tfc_certificate: Read complete after 1s [id=896bd9f2e4b99335cca9e93921664e636e35cab3]
aws_iam_openid_connect_provider.tfc_provider: Refreshing state... [id=arn:aws:iam::812345678901:oidc-provider/app.terraform.io]
aws_iam_policy.tfc_policy: Refreshing state... [id=arn:aws:iam::812345678901:policy/tfc-policy]
aws_iam_role.tfc_role: Refreshing state... [id=tfc-role]
aws_iam_role_policy_attachment.tfc_policy_attachment: Refreshing state... [id=tfc-role-20230123163910381200000001]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  - destroy

Terraform will perform the following actions:

  # aws_iam_openid_connect_provider.tfc_provider will be destroyed
  - resource "aws_iam_openid_connect_provider" "tfc_provider" {
##...
Plan: 0 to add, 0 to change, 4 to destroy.

Changes to Outputs:
  - openid_claims = {
      - StringEquals = {
          - "app.terraform.io:aud" = "aws.workload.identity"
        }
      - StringLike   = {
          - "app.terraform.io:sub" = "organization:<YOUR_ORG>:project:Default Project:workspace:learn-terraform-dynamic-credentials:run_phase:*"
        }
    } -> null
  - role_arn      = "arn:aws:iam::812345678901:role/tfc-role" -> null

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

aws_iam_role_policy_attachment.tfc_policy_attachment: Destroying... [id=tfc-role-20230123163910381200000001]
aws_iam_role_policy_attachment.tfc_policy_attachment: Destruction complete after 0s
aws_iam_policy.tfc_policy: Destroying... [id=arn:aws:iam::812345678901:policy/tfc-policy]
aws_iam_role.tfc_role: Destroying... [id=tfc-role]
aws_iam_policy.tfc_policy: Destruction complete after 0s
aws_iam_role.tfc_role: Destruction complete after 0s
aws_iam_openid_connect_provider.tfc_provider: Destroying... [id=arn:aws:iam::812345678901:oidc-provider/app.terraform.io]
aws_iam_openid_connect_provider.tfc_provider: Destruction complete after 0s

Destroy complete! Resources: 4 destroyed.

Next steps

In this tutorial, you created a trust relationship between Terraform Cloud and your cloud provider. Then you used that trust relationship to provision infrastructure with dynamic credentials.

Refer to the following resources to learn more about dynamic credentials.

Instead of creating workspaces manually, you can use HashiCorp's TFE provider to provision them. Refer to the terraform-dynamic-credentials-setup-examples GitHub repository for example configuration.
Read the dynamic credentials documentation for more details about how to configure your trust relationships.
You can also manually generate custom auth tokens for custom authentication workflows or providers that do not natively support dynamic credentials.