The Stack Observer
Cloud Native / DevOps

Terraform Dynamic Credentials with AWS Native OIDC: A Complete Setup Guide

•Stackxx•Cloud Native, DevOps

AWS has introduced native OpenID Connect (OIDC) integration for HCP Terraform and Terraform Enterprise within Account Factory for Terraform (AFT), fundamentally changing how dynamic provider credentials are configured. This integration, available since AFT 1.19.0, eliminates the manual steps previously required to establish trust relationships between AWS and Terraform workspaces.

Goal

This guide walks through implementing Terraform dynamic credentials with AWS native OIDC integration. By the end, you’ll have a working configuration that generates short-lived credentials for each Terraform run without managing long-lived AWS access keys.

Prerequisites

  • AWS Account with permissions to create IAM roles and OIDC providers
  • HCP Terraform organization or Terraform Enterprise instance
  • AFT version 1.19.0 or later
  • Existing AFT deployment or willingness to redeploy with new settings
  • Understanding of your current AWS landing zone architecture

Understanding the Architecture

Before diving into implementation, understand what changes with native OIDC integration:

ComponentBefore (Manual)After (Native)
OIDC ProviderManual creation in each accountAutomatically created by AFT
IAM Trust PolicyManually configuredManaged by AFT
Environment VariablesMultiple variables per workspaceReduced configuration
CredentialsLong-lived or complex federationShort-lived, dynamic per-run

The key benefit is abstraction. AFT now handles the OIDC infrastructure, allowing platform teams to focus on governance rather than credential plumbing.

Steps

Step 1: Enable Native OIDC in AFT

Update your AFT deployment configuration to enable the native OIDC integration:

# In your AFT terraform.tfvars or equivalent
terraform_oidc_integration = true

When terraform_oidc_integration = true, AFT automatically:

  • Creates the OIDC identity provider in each provisioned account
  • Configures IAM roles with appropriate trust policies
  • Sets up the federation between AWS and your Terraform organization

Step 2: Configure Workspace Roles

Define the IAM roles that Terraform workspaces will assume. These roles should follow least-privilege principles:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::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:YOUR_ORG:workspace:WORKSPACE_NAME:run_phase:*"
        }
      }
    }
  ]
}

With native integration, much of this trust configuration is handled automatically. You primarily need to define the permission boundaries for each role.

Step 3: Configure HCP Terraform

In your HCP Terraform workspace, configure the AWS provider for dynamic credentials:

# In your Terraform configuration
provider "aws" {
  region = var.aws_region

  assume_role_with_web_identity {
    role_arn                = var.aws_role_arn
    web_identity_token_file = var.tfc_default_workload_identity_token_file
  }
}

Set the required environment variables in your workspace:

  • TFC_AWS_PROVIDER_AUTH = true
  • TFC_AWS_RUN_ROLE_ARN = arn:aws:iam::ACCOUNT_ID:role/TerraformExecutionRole

Step 4: Validate the Setup

Create a test Terraform configuration to verify dynamic credentials work:

data "aws_caller_identity" "current" {}

output "account_id" {
  value = data.aws_caller_identity.current.account_id
}

output "caller_arn" {
  value = data.aws_caller_identity.current.arn
}

Run terraform plan. If configured correctly, Terraform will obtain temporary credentials via OIDC and display your AWS account information without any static credentials in the workspace.

Common Pitfalls

  • Trust policy mismatches: Ensure the subject condition matches your exact organization and workspace names. OIDC is sensitive to naming.
  • Role propagation delays: Newly created IAM roles may take time to propagate. If you see “Access Denied” immediately after setup, wait 30-60 seconds and retry.
  • Feature flag confusion: The terraform_oidc_integration setting only works with AFT 1.19.0+. Verify your AFT version before enabling.
  • Existing workflows: Existing HelmReleases (if using AFT with Helm) will continue using client-side apply until explicitly updated. The native OIDC setting only affects new configurations.

Verify

Confirm your dynamic credentials implementation:

# In HCP Terraform, check the run output
# Look for messages indicating credential acquisition:
# "Obtaining dynamic credentials for AWS"

# Verify the assumed role in AWS CloudTrail
# Filter for "AssumeRoleWithWebIdentity" events
# Confirm the role ARN matches your configuration

# Check credential lifetime
# Dynamic credentials are valid for the Terraform run duration only
# (typically 1 hour or less)

Monitor your AWS CloudTrail logs for AssumeRoleWithWebIdentity calls from Terraform. You should see distinct events for each run, with no long-lived credential usage.

Security Model

This architecture reflects a broader shift toward zero-standing-credential approaches. By using identity-based, short-lived access rather than static secrets, organizations improve their security posture while maintaining operational scalability. Tokens are generated on-demand, tied to specific Terraform runs, and automatically expire.

For platform teams managing multiple AWS accounts through AFT, native OIDC integration significantly reduces the operational burden of maintaining cross-account access while strengthening security controls.

Sources

  • HashiCorp Blog – “Simplifying Terraform dynamic credentials on AWS with native OIDC integration” (April 9, 2026)
  • AWS AFT GitHub Release – v1.19.0
  • HCP Terraform Documentation – Dynamic Provider Credentials
Next signal