Terraform AWS Provider Auth Errors — Fix in Minutes

SSO and STS credentials are temporary by design, and their expiry produces some of the most misleading errors in the Terraform workflow. An SSO session typically lasts around 8 hours, and assumed-role STS tokens can live anywhere from 15 minutes to 12 hours depending on the role configuration. When they die, you get ExpiredToken, TokenRefreshRequired, or a vague auth failure that reads exactly like a provider bug — especially cruel when the morning's plan worked and the afternoon's apply doesn't.

The confusion comes from the split between login state and credential cache. Running aws sso login populates a cached token under ~/.aws/sso/cache keyed by your SSO session, and the SDK silently uses it until it rots. Terraform never prompts you to refresh; it just fails. Engineers then burn an hour pinning provider versions and wiping .terraform directories while the actual fix is a single login command. Worse, long applies can start with valid tokens and expire mid-run, leaving half-applied state that needs careful recovery.

Build refresh into the routine instead of treating it as setup. Start each work session and each CI job that needs SSO with aws sso login --profile prod, then confirm with aws sts get-caller-identity before running anything stateful. For STS-heavy flows, check the token's Expiration timestamp right after assuming the role and compare it against your apply window — if the apply takes 40 minutes and the token lives 15, you'll fail at minute 16. Short-lived credentials are a security feature, not a bug; the bug is assuming they'll outlive your workday.

# Confirm the expiry instead of guessing
aws sts get-caller-identity 2>&1 | tail -3

# Refresh the SSO session for this profile
aws sso login --profile prod

# Prove the refresh worked before touching state
aws sts get-caller-identity --profile prod

# Check how long an assumed-role token will live
aws sts assume-role --role-arn arn:aws:iam::123456789012:role/TerraformDeploy \
  --role-session-name check --query 'Credentials.[Expiration]' --output text

Assume-role failures feel personal — AWS tells you you're not authorized to become a role you can see plain as day — but the logic is strictly two-sided and both sides must agree. Your IAM identity needs permission to call sts:AssumeRole on the role's ARN, and the role's trust policy must name your ARN (or your account, or your SSO role) as a trusted Principal allowed to assume it. Miss either half and you get AccessDenied, and the error rarely tells you which half is broken.

The classic mistake is configuring only the Terraform side. You add an assume_role block with the right ARN, your own IAM policy even allows sts:AssumeRole broadly, and it still fails — because nobody edited the role's trust policy to list your user or SSO role ARN. The mirror image happens after SSO migrations: the trust policy still names the old IAM user ARNs while everyone now arrives via an SSO permission-set role with a completely different ARN. Both produce identical AccessDenied text.

Debug it outside Terraform first, where the feedback loop is seconds. Run aws sts assume-role directly with the same ARN and read the verdict. Then inspect the role with aws iam get-role and compare its trust Principal against your actual Arn from get-caller-identity — character for character, including path and session-name suffixes on assumed roles. Watch for conditions too: an ExternalId or MFA condition in the trust policy denies silently when Terraform doesn't send the matching value. When both halves line up, the provider's assume_role block works on the first try.

# Reproduce the denial without Terraform in the loop
aws sts assume-role --role-arn arn:aws:iam::123456789012:role/TerraformDeploy \
  --role-session-name debug 2>&1 | tail -5

# Who am I really? Compare this ARN to the trust policy Principal
aws sts get-caller-identity --query Arn --output text

# Read the role's trust policy verbatim
aws iam get-role --role-name TerraformDeploy \
  --query 'Role.AssumeRolePolicyDocument' --output json

# Trust policy shape that works (replace ACCOUNT and USER):
# {"Version":"2012-10-17","Statement":[{"Effect":"Allow",
#  "Principal":{"AWS":"arn:aws:iam::ACCOUNT:user/deployer"},
#  "Action":"sts:AssumeRole"}]}

ProfileNotFound errors are almost never about AWS being down — they're about a name mismatch between what you exported and what exists on disk. Terraform reads AWS_PROFILE and looks for a matching stanza: [profile prod] in ~/.aws/config for settings like region and SSO, and [prod] in ~/.aws/credentials for static keys. A typo, a missing export in a fresh terminal, or a CI job that never set the variable at all produces the same error, and the message helpfully echoes the wrong name right back at you.

The split between the two files trips up even experienced engineers. SSO profiles live in config, static keys live in credentials, and region plus output format live in config — which the AWS provider v4 and later read by default. Copying a [prod] block into the wrong file, or expecting credentials-file regions to apply, fails quietly. Then there's scope: you export AWS_PROFILE in one terminal tab, open another to run the apply, and the second shell has no idea the first existed. CI multiplies this — each job step can be a fresh shell.

Treat profiles as explicit inputs, not ambient state. Echo the variable, grep both files for the stanza, and run aws configure list to see the resolved profile, region, and credential source in one view. Bake the export into wrapper scripts, direnv files, or CI variables so it travels with the work instead of living in one terminal's memory. Profile problems are spelling and scope problems; a 30-second file check beats a 30-minute provider reinstall every single time.

# What profile does this shell think it's using?
echo "AWS_PROFILE=$AWS_PROFILE"

# Does the stanza exist in the right file?
grep -A 4 '\[profile prod\]' ~/.aws/config
grep -A 2 '\[prod\]' ~/.aws/credentials

# Resolved view: profile, region, and credential source
aws configure list

# Create it properly when it's genuinely missing
aws configure --profile prod

Every fix in this guide works once; the checklist makes them stick. The pattern behind all five failures is the same: Terraform inherits ambient shell state, and ambient state rots — tokens expire, exports leak between sessions, runner images change what they load. A pre-apply routine that asserts identity, region, token freshness, role access, and profile resolution turns a whole category of 3-hour mysteries into 30-second guard failures with readable messages.

Keep the routine in version control next to your Terraform code so the whole team runs the same checks. A five-line wrapper script beats tribal knowledge: it prints who you're acting as, fails when the region is empty, refreshes SSO when needed, and only then calls plan. CI should run the same script with the same assertions — environment parity between laptops and runners is what stops works-here-fails-there incidents permanently. Review the checklist quarterly, because AWS changes defaults and session durations more often than anyone admits.

The deeper lesson is cultural: treat credential setup as part of the deploy, not as prerequisites everyone supposedly handled. Log the caller Arn on every run, alert when guard failures spike, and never let debugging exports live past the session that needed them. Teams that do this stop fearing Tuesday deploys.