Authenticate providers with dynamic credentials

15min
|
Terraform

HCP Terraform's dynamic provider credentials let you establish a trust relationship between HCP Terraform 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 HCP Terraform projects and workspaces can manage. HCP Terraform supports dynamic credentials for AWS, Google Cloud Platform, Azure, and Vault.

When you use dynamic credentials, HCP Terraform 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 HCP Terraform 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 HCP Terraform and your cloud provider, and configure a workspace with dynamic credentials. Then you will use dynamic credentials to provision infrastructure for that workspace.

If you use Vault to manage your secrets, you can also use it to manage your dynamic provider credentials. Refer to the Authenticate Providers with Vault-Backed Dynamic Credentials tutorial for details.

Prerequisites

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

For this tutorial, you will need:

Terraform v1.5+ installed locally.
an HCP Terraform 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 Community Edition 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 HCP Terraform, 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 HCP Terraform. 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 HCP Terraform. 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 HCP Terraform 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 HCP Terraform's TLS certificate to verify that requests for dynamic credentials come from HCP Terraform.

Next, the configuration sets up a JWT auth backend to establish a trust relationship with HCP Terraform. 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 HCP Terraform 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 HCP Terraform'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 HCP Terraform.

Next the configuration sets up an OIDC provider in AWS with HCP Terraform'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 HCP Terraform 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 HCP Terraform. GCP will automatically verify that requests for credentials come from HCP Terraform 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 HCP Terraform using the default audience. Azure will automatically verify that requests for credentials come from HCP Terraform 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"
}

The configuration first retrieves information about your EKS cluster, fetches an authentication token, and uses this information to configure the Kubernetes provider.

data "aws_eks_cluster" "upstream" {
  name = var.cluster_name
}

data "aws_eks_cluster_auth" "upstream_auth" {
  name = var.cluster_name
}

provider "kubernetes" {
  host                   = data.aws_eks_cluster.upstream.endpoint
  cluster_ca_certificate = base64decode(data.aws_eks_cluster.upstream.certificate_authority[0].data)
  token                  = data.aws_eks_cluster_auth.upstream_auth.token
}

Next, the configuration sets up an OIDC provider in Kubernetes with HCP Terraform. Kubernetes automatically verifies that requests for credentials come from HCP Terraform, and the groups_claim field tells Kubernetes to verify the name of the HCP Terraform organization attempting to authenticate to the cluster.

resource "aws_eks_identity_provider_config" "oidc_config" {
  cluster_name = var.cluster_name

  oidc {
    identity_provider_config_name = "terraform-cloud"
    client_id                     = var.tfc_kubernetes_audience
    issuer_url                    = var.tfc_hostname
    username_claim                = "sub"
    groups_claim                  = "terraform_organization_name"
  }
}

The configuration first retrieves your GKE cluster's configuration and client credentials.

main.tf

data "google_container_cluster" "upstream" {
  name     = var.cluster_name
  location = var.cluster_location
  project  = var.project
}

data "google_client_config" "provider" {
}

provider "kubernetes" {
  host  = "https://${data.google_container_cluster.upstream.endpoint}"
  token = data.google_client_config.provider.access_token
  cluster_ca_certificate = base64decode(
    data.google_container_cluster.upstream.master_auth[0].cluster_ca_certificate,
  )
}

When you enable identity services in a GKE cluster, the cluster contains a custom resource of type ClientConfig.authentication.gke.io. This object describes the configuration for an external OIDC provider, such as HCP Terraform.

Because the default ClientConfig object already exists, you need to import it in Terraform before you can make changes to it. This configuration defines a kubernetes_manifest resource with the desired configuration for the ClientConfig object. Using configuration-driven import, you can import and apply the configuration changes in a single apply operation.

main.tf

import {
  // The name of this resource is hardcoded by GKE as described in:
  // https://cloud.google.com/kubernetes-engine/docs/how-to/oidc#configuring_on_a_cluster
  //
  id = "apiVersion=authentication.gke.io/v2alpha1,kind=ClientConfig,namespace=kube-public,name=default"
  to = kubernetes_manifest.oidc_conf
}

resource "kubernetes_manifest" "oidc_conf" {
  manifest = {
    apiVersion = "authentication.gke.io/v2alpha1"
    kind       = "ClientConfig"
    metadata = {
      name      = "default"
      namespace = "kube-public"
    }
    spec = {
      authentication = [
        {
          name = data.google_container_cluster.upstream.name
          oidc = {
            clientID    = var.tfc_kubernetes_audience
            issuerURI   = var.tfc_hostname
            userClaim   = "sub"
            groupsClaim = "terraform_organization_name"
          }
        }
      ]
    }
  }
}

Kubernetes automatically verifies that requests for credentials come from HCP Terraform, and the groupsClaim field tells Kubernetes to verify the name of the HCP Terraform organization attempting to authenticate to the cluster.

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 HCP Terraform 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

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 HCP Terraform with the provided TLS certificate, HCP Terraform 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 HCP Terraform's OIDC metadata and public signing key to verify that the token was generated by HCP Terraform 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. HCP Terraform will then use those dynamic credentials to provision your resources.

Warning: Always include the audience and the name of your HCP Terraform organization when you configure claims. They make sure the claims are only valid for your intended cloud provider, and prevent unauthorized access from other HCP Terraform 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 = "HCP Terraform 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.

Finally, the configuration assigns the group that it automatically created with your organization's name to cluster-admin role.

main.tf

resource "kubernetes_cluster_role_binding_v1" "oidc_role" {
  metadata {
    name = "odic-identity"
  }

  role_ref {
    api_group = "rbac.authorization.k8s.io"
    kind      = "ClusterRole"
    name      = "cluster-admin"
  }

  subject {
    api_group = "rbac.authorization.k8s.io"
    kind      = "Group"
    name      = var.tfc_organization_name
  }
}

Finally, the configuration assigns the group that it automatically created with your organization's name to cluster-admin role.

main.tf

resource "kubernetes_cluster_role_binding_v1" "oidc_role" {
  metadata {
    name = "odic-identity"
  }

  role_ref {
    api_group = "rbac.authorization.k8s.io"
    kind      = "ClusterRole"
    name      = "cluster-admin"
  }

  subject {
    api_group = "rbac.authorization.k8s.io"
    kind      = "Group"
    name      = var.tfc_organization_name
  }
}

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"