Vault AWS Auth: IAM Identity Login
AWS auth lets a workload prove its IAM identity to Vault using a signed sts:GetCallerIdentity request, with no static secret.
When CI runs on AWS (EC2 runners, CodeBuild, or a role assumed via OIDC), the IAM identity already present can authenticate to Vault. The iam method is the modern choice.
What it does
The AWS iam auth method has the client sign an sts:GetCallerIdentity request and send it to Vault, which executes it against STS to confirm the caller ARN. A role binds the allowed principal ARN and attaches policies. The CLI vault login -method=aws builds the signed request for you.
Common usage
# Vault config (run once)
vault auth enable aws
vault write auth/aws/role/ci \
auth_type=iam \
bound_iam_principal_arn="arn:aws:iam::123456789012:role/ci-runner" \
token_policies="ci" token_ttl=20m
# login (uses the ambient AWS credentials)
vault login -method=aws role=ciOptions
| Field | What it does |
|---|---|
| auth_type=iam | Use IAM (vs the older ec2 method) |
| bound_iam_principal_arn | IAM role/user ARN allowed to log in |
| region | STS region for the signed request |
| token_policies | Policies attached to issued tokens |
In CI
On GitHub Actions you can assume an AWS role via OIDC first, then vault login -method=aws uses those ambient credentials, chaining two OIDC-based logins with no static secret. Make sure the STS region used by the client matches what the role expects, or the signed request fails verification.
Common errors in CI
"error logging in: ... no valid credentials" means the AWS SDK found no credentials in the environment; configure the role assumption first. "entry for role ci not found" means the role is missing. "IAM Principal ... does not match ..." means the caller ARN is not in bound_iam_principal_arn (watch assumed-role ARNs, which differ from the role ARN). STS errors often trace to a region mismatch.