Introduction

Terraform uses the AWS SDK credential chain, so it can read shared credentials files without hardcoding secrets in configuration. Most authentication problems come from profile selection or file path mismatches, not from Terraform syntax itself. A clean setup uses named profiles, environment variables, and minimal provider configuration.

Core Sections

Understand the AWS credential chain Terraform uses

When Terraform runs with the AWS provider, credentials are resolved in an order that includes environment variables, shared credentials files, and metadata services. For local development, the shared credentials file is usually the simplest path.

Typical credential file locations are in the user home directory under .aws. The file is INI formatted and can include multiple profiles.

1[default]
2aws_access_key_id = AKIAEXAMPLEKEY
3aws_secret_access_key = secret-example
4
5[dev]
6aws_access_key_id = AKIADEVKEY
7aws_secret_access_key = secret-dev

Select profile in provider configuration

You can choose which profile Terraform should use directly in the provider block.

1terraform {
2  required_providers {
3    aws = {
4      source  = "hashicorp/aws"
5      version = "~> 5.0"
6    }
7  }
8}
9
10provider "aws" {
11  region  = "us-east-1"
12  profile = "dev"
13}

This is explicit and works well for team-shared modules.

Override credential file path with environment variables

If the credentials file is not in the default location, set path variables before running Terraform.

1export AWS_SHARED_CREDENTIALS_FILE=/opt/secure/aws-credentials
2export AWS_PROFILE=dev
3export AWS_REGION=us-east-1
4terraform init
5terraform plan

For scripts and CI jobs, this approach is usually cleaner than embedding profile details in every module.

Use temporary credentials and assume role flows

Long-lived access keys should be avoided when possible. If your organization uses role assumption, first acquire session credentials with AWS CLI, then run Terraform with that profile.

[dev-admin]
role_arn = arn:aws:iam::123456789012:role/terraform-admin
source_profile = dev

Then use profile = "dev-admin" in provider settings. This reduces key exposure and centralizes permissions in IAM roles.

Validate what Terraform is actually using

When debugging, confirm active identity before apply operations.

aws sts get-caller-identity --profile dev
terraform providers
TF_LOG=INFO terraform plan

If account id or role is unexpected, stop and fix profile resolution first. Running with the wrong identity is one of the most expensive Terraform mistakes.

CI workflow pattern for profile-based Terraform runs

A dependable pipeline uses short-lived credentials injected at runtime, not static secrets in repository variables. For example, the job can export AWS_PROFILE, generate a temporary credentials file in a secure workspace path, run Terraform, then remove the file at job end.

1umask 077
2cat > /tmp/aws-credentials <<'INI'
3[ci]
4aws_access_key_id = EXAMPLE
5aws_secret_access_key = EXAMPLE
6aws_session_token = EXAMPLE
7INI
8
9export AWS_SHARED_CREDENTIALS_FILE=/tmp/aws-credentials
10export AWS_PROFILE=ci
11terraform plan
12rm -f /tmp/aws-credentials

This approach limits credential lifetime and keeps secret handling auditable.

Common profile setup for local developer machines

A simple local setup is to keep one read-only profile for plan and one elevated profile for apply in non-production environments. This separation reduces accidental destructive changes while still keeping workflows fast.

1[dev-plan]
2aws_access_key_id = EXAMPLE
3aws_secret_access_key = EXAMPLE
4
5[dev-apply]
6aws_access_key_id = EXAMPLE
7aws_secret_access_key = EXAMPLE

Then run terraform plan with dev-plan and use explicit operator approval before running apply with a stronger profile. Even in small teams, this operational separation prevents many avoidable incidents.

Common Pitfalls

• Storing access keys directly in main.tf or variable files committed to source control.
• Setting profile in Terraform but forgetting to update the matching credentials file entry.
• Using a custom credentials file path without exporting AWS_SHARED_CREDENTIALS_FILE.
• Mixing multiple auth mechanisms in CI, causing unpredictable credential resolution.
• Running apply without verifying active AWS identity and target account.

Summary

• Terraform can read AWS shared credentials files through the standard AWS SDK chain.
• Use named profiles for clarity and safer multi-account workflows.
• Set environment variables when credentials live in non-default paths.
• Prefer temporary credentials and role assumption over long-lived access keys.
• Always verify caller identity before planning or applying infrastructure changes.