Simplify and Secure Terraform Workflows on AWS with Dynamic Provider Credentials

By Welly Siauw, Principal Partner Solutions Architect – AWS
By Marc Cosentino, Sr. Product Manager – HashiCorp

HashiCorp

The HashiCorp Terraform AWS provider has surpassed more than one billion downloads, and every single Terraform apply starts with a provider credentials setup.

We hear from customers that they want seamless Terraform provider authentication experience on Amazon Web Services (AWS). In this post, we show you how to set up temporary AWS provider credentials.

The new dynamic provider credentials feature offers the ability to generate dynamic, short-lived credentials for Terraform Cloud runs using OpenID Connect protocol (OIDC). This feature is now available for all Terraform Cloud tiers.

Terraform Cloud is HashiCorp’s managed service offering and eliminates the heavy lifting for practitioners, teams, and organizations to use Terraform in production.

HashiCorp is an AWS Partner and cloud infrastructure automation company that provides the open-source tools Terraform, Vagrant, Packer, Vault, Consul, and Nomad. Enterprise versions of these products enhance the open-source tools with features that promote collaboration, operations, governance, and multi-data center functionality.

Background

Terraform users typically use static credentials to authenticate with AWS providers, but this practice brings operational and security challenges. Users store the static credentials by using workspace variables or variable sets, adding additional steps in their Terraform workflow. Storing long-lived credentials could expose a security risk, even if you rotate your AWS credentials regularly.

When authenticating to AWS, we recommend you use an AWS Identity and Access Management (IAM) role to grant temporary security credentials, which are time-bound, last from a few minutes to several hours, and do not require you to rotate them or explicitly revoke them when they’re no longer needed or expire.

Temporary security credentials are generated dynamically and provided to the user when they assume the IAM role. You can assume the IAM role using an IAM identity such as IAM user or an external identity provider (IdP). For example, you can federate identity using an OIDC-compatible IdP such as Terraform Cloud.

Dynamic Provider Credentials

To start using dynamic provider credentials, users must first configure a trust relationship between AWS IAM with Terraform Cloud as the IdP. This is done by creating an IAM OIDC identity provider on AWS IAM.

Users provide configuration such as the Provider URL (https://app.terraform.io) and the Audience (aws.workload.identity). Below is the example of configuration for Terraform Cloud as IdP.

Figure 1 – Terraform Cloud shown as IdP in AWS IAM console.

After creating the IAM OIDC identity provider, users must create one or more IAM roles. The IAM role trust policy permits Terraform Cloud IdP to request temporary security credentials for access to AWS.

The identity policies assigned to the role determine what Terraform Cloud runs are allowed to do in AWS; for example, launch an Amazon Elastic Compute Cloud (Amazon EC2) instance or create an Amazon Simple Storage Service (Amazon S3) bucket.

You can find an example of the IAM role trust policy that permits Terraform Cloud below.

{
  "Version": "2012-10-17",
  "Statement": [
    {
       "Effect": "Allow",
       "Principal": {
         "Federated": "arn:aws:iam::<aws-account-id>:oidc-provider/app.terraform.io"
       },
       "Action": "sts:AssumeRoleWithWebIdentity",
       "Condition": {
         "StringEquals": {
            "app.terraform.io:aud": "aws.workload.identity"
         },
         "StringLike": {
            "app.terraform.io:sub": "organization:my-tfc-org:project:*:workspace:*:run_phase:*"
         }
       }
    }
  ]
}

The example IAM trust policy we shared earlier is set with claim format (sub) as such: organization:<tfc-org>:project:<project-name>:workspace:<workspace-name>:run_phase:<run-type>.

Users can limit the IAM role to be assumable only from a certain Terraform Cloud Organization (tfc-org-name), specific Terraform Cloud project name (project-name), or from specific Terraform Cloud Workspace name (workspace-name).

Users will set environment variables in their Terraform Cloud workspace in order to configure how Terraform Cloud will authenticate to AWS:

• TFC_AWS_PROVIDER_AUTH = set to true to use dynamic provider credentials.
• TFC_AWS_RUN_ROLE_ARN = IAM Role ARN to authenticate against.

Users can set these as workspace variables, or if they would like to use one AWS role across multiple workspaces users can use a variable set. As shown in the example below, users are no longer required to specify variables for long-lived credentials such as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Figure 2 – Terraform Cloud workspace with variables for dynamic provider credentials.

To use dynamic provider credentials, no other authentication and configuration is required inside the AWS provider block. Users run Terraform plan or apply as usual via command line interface (CLI), API, or Terraform Cloud graphical user interface (GUI).

Here is an example of the AWS provider configuration:

Terraform {
  cloud {
	organization = “my-tfc-org”
	workspaces {
  	name = “demo-workspace”
	}
  }
  required_providers {
	aws = {
  	source  = “hashicorp/aws”
  	version = “>= 3.73.0”
	}
}

provider “aws” {
  region = var.aws_region
}

During the plan or apply, Terraform Cloud generates an OIDC-compliant workload identity token, which includes information about the organization, project, workspace, and run stage. Terraform Cloud sends the identity token to AWS Security Token Service (AWS STS), which verifies the token using Terraform Cloud’s public signing key to ensure the token is genuine and the information in it can be trusted.

If the token is genuine, AWS STS returns the IAM role temporary credentials that will be used by the Terraform AWS provider, and the plan or apply can proceed.

Figure 3 – Diagram of Terraform Cloud dynamic provider credentials workflow.

Optional Configuration

Terraform Cloud provides optional configuration to further customize the dynamic provider credentials. The tables below lists the optional environment variables.

Using this optional configuration, users can create two distinct IAM roles for the plan and apply phases. For example, TFC_AWS_PLAN_ROLE_ARN will have read-only access to all AWS resources, while TFC_AWS_APPLY_ROLE_ARN will have write access to the relevant AWS resources. To ensure only the appropriate role is used for each phase, users can specify the IAM role trust policy accordingly.

For example, TFC_AWS_PLAN_ROLE_ARN will have the following condition in the trust policy:

"Condition": {
  "StringEquals": {
    "app.terraform.io:aud": "aws.workload.identity"
  },
  "StringLike": {
    "app.terraform.io:sub": "organization:my-tfc-org:project:*:workspace:*:run_phase:plan"
  }
}

And TFC_AWS_APPLY_ROLE_ARN will have the following condition in the trust policy:

"Condition": {
  "StringEquals": {
    "app.terraform.io:aud": "aws.workload.identity"
  },
  "StringLike": {
    "app.terraform.io:sub": "organization:my-tfc-org:project:*:workspace:*:run_phase:apply"
  }
}

We recommend you always check the audience (aud) and the name of the organization (sub) to prevent unauthorized access from other Terraform Cloud organizations.

Conclusion

In this post, we showed you how to use dynamic provider credentials to generate dynamic, short-lived credentials for Terraform Cloud runs in AWS. By using this feature, users can mitigate security risks from storing long-lived credentials, avoid operational burden by rotating static credentials, and simplify the setup of Terraform workspace.

Dynamic provider credentials are now available for all Terraform Cloud tiers. To learn more about this feature, check the blog post by HashiCorp and follow the learn tutorial. You can find Terraform Cloud in AWS Marketplace.

.

.

HashiCorp – AWS Partner Spotlight

HashiCorp is an AWS Partner and cloud infrastructure automation company that provides the open-source tools Terraform, Vagrant, Packer, Vault, Consul, and Nomad.

Contact HashiCorp | Partner Overview | AWS Marketplace | Case Studies