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

- Link: https://thestackobserver.com/terraform-dynamic-credentials-with-aws-native-oidc-a-complete-setup-guide/
- Published: 2026-04-16T08:12:01-04:00
- Author: Stackxx

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:

| Component | Before (Manual) | After (Native) | 
| OIDC Provider | Manual creation in each account | Automatically created by AFT | 
| IAM Trust Policy | Manually configured | Managed by AFT | 
| Environment Variables | Multiple variables per workspace | Reduced configuration | 
| Credentials | Long-lived or complex federation | Short-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:

    ```wp-block-code
    # 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:

    ```wp-block-code
    {
      "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:

    ```wp-block-code
    # 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:

    ```wp-block-code
    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:

    ```wp-block-code
    # 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