Implementing Vault AWS Authentication with IAM Roles (Associate Exam Guide)

Vault's AWS authentication offers two modes — IAM and EC2 — but for containers and serverless workloads, IAM mode is the better operational fit.

The essence of IAM authentication is that Vault verifies the client's AWS identity by validating a signed sts:GetCallerIdentity request.

AWS Authentication (IAM) Overview

In IAM mode, the client submits an sts:GetCallerIdentity request signed with AWS Signature Version 4 to Vault, which forwards it to AWS STS for verification. Vault has the client's IAM role or user ARN pre-bound to its role configuration; if it matches, Vault issues a token.

For replay resistance, Vault recommends the X-Vault-AWS-IAM-Server-ID header (header_value). Setting the same value on both the server and the client signature blocks man-in-the-middle attacks and cross-region replay.

• The verification target is a signed sts:GetCallerIdentity call. On success, the Caller ARN is extracted and matched against the role's bound_iam_principal_arn.
• Vault needs no AWS credentials of its own in IAM mode — it only needs network reachability to STS.
• The policies and TTL attached to the role are applied to the issued Vault token.

Trust chain for an IAM login

When to Use IAM Auth vs. Other Methods

Vault's AWS authentication has two modes — IAM and EC2 — and AppRole is the typical choice for non-AWS workloads. The exam frequently tests the boundary conditions: which method fits which environment.

IAM fits instance-independent principals like ECS task roles and Lambda execution roles. EC2 mode's strength is binding via the instance identity document. AppRole works entirely outside AWS but requires separate rotation operations.

• Instance-less execution environments (ECS, EKS, Lambda) → IAM auth
• Long-lived EC2 instances that leverage instance metadata → EC2 auth
• On-prem, multi-cloud, batch jobs, or anywhere IAM is unavailable → AppRole

Vault-Side Configuration (Binding an IAM Role)

In IAM mode, the server generally does not need AWS credentials configured. Enable AWS auth, set the Server-ID, then create an auth role bound to an IAM role (or user).

The role defines policies, TTL, whether re-authentication is allowed, and so on. bound_iam_principal_arn accepts multiple values, so it handles cross-account scenarios.

• Make sure auth/aws/config/client's iam_server_id_header_value matches the value used by the client
• Always set the role's auth_type=iam (don't confuse it with the default)
• Policies are Vault's access boundary — design them with least privilege

Vault server configuration example (IAM mode)

# AWS auth を有効化（パスは必要に応じて変更）
vault auth enable -path=aws aws

# Server-ID ヘッダ値を設定（クライアントが署名時に同値を入れる）
vault write auth/aws/config/client \
  iam_server_id_header_value="vault.example.com"

# アプリ用ポリシー（例）
vault policy write app - <<'EOF'
path "secret/data/app/*" {
  capabilities = ["read"]
}
EOF

# IAM ロールにバインドした認証ロールを作成
vault write auth/aws/role/app \
  auth_type=iam \
  bound_iam_principal_arn=arn:aws:iam::111111111111:role/app-task \
  policies=app \
  max_ttl=1h \
  disallow_reauthentication=true

Logging In from the Client (IAM Sign-In)

The client uses its own AWS execution role to generate a signed sts:GetCallerIdentity request. The Vault CLI and Vault Agent automate both the signing and the submission to /auth/aws/login.

The key points are sourcing credentials from AWS environment variables (or the instance/task role) and matching the Server-ID header value.

• Vault CLI: signs automatically via the AWS SDK; log in by specifying role and header_value
• Vault Agent: auto_auth.method "aws" with type=iam handles automatic token acquisition and renewal

CLI and Vault Agent examples

# CLI 例（AWS_PROFILE / タスクロールなどで認証情報が利用可能であること）
export AWS_REGION=ap-northeast-1
vault login -method=aws role=app header_value=vault.example.com

# 成功すると Vault トークンが返る（-format=json で機械可読）
# vault login -method=aws role=app header_value=vault.example.com -format=json | jq

# Vault Agent 例（/etc/vault.d/agent-iam.hcl）
auto_auth {
  method "aws" {
    mount_path = "auth/aws"
    config = {
      type         = "iam"
      role         = "app"
      header_value = "vault.example.com"
      # 必要に応じて region 等を指定
    }
  }
  sink "file" {
    config = {
      path = "/tmp/vault-token"
    }
  }
}

cache {
  use_auto_auth_token = true
}

vault {
  address = "https://vault.example.com"
}

Cross-Account and Least-Privilege Design

IAM auth can bind roles in other AWS accounts. Just list the target role ARNs in bound_iam_principal_arn and applications across accounts can log in. Even when the caller presents an assumed-role session ARN, Vault normalizes it to the underlying role ARN before matching.

Because any principal can call sts:GetCallerIdentity, you don't need to grant special IAM permissions for IAM auth to work. The real-world success factors are network reachability from Vault to AWS STS, clock synchronization, and Server-ID consistency.

• Specifying multiple ARNs makes phased migrations and blue/green operations much easier
• Design Vault policies with least privilege and keep token TTLs short
• Always make /auth/aws/login visible via an audit device

Example: binding to multiple principals

# 複数の IAM ロールを同一 Vault ロールへバインド
vault write auth/aws/role/app \
  auth_type=iam \
  bound_iam_principal_arn=arn:aws:iam::111111111111:role/app-task,arn:aws:iam::222222222222:role/app-task \
  policies=app \
  max_ttl=1h

Troubleshooting and Common Exam Targets

In production, the typical failures are Server-ID mismatch, clock skew, and ARN type mistakes (such as registering a user ARN as a role). On the exam, expect questions on choosing between IAM and EC2, on bound_iam_principal_arn and header_value semantics, and on the fact that Vault verifies logins without holding AWS credentials.

When isolating issues, work through them in order: inspect responses with -format=json, check the audit log, and verify reachability to AWS STS (proxies, firewalls).

• Server-ID mismatch: align auth/aws/config/client with the client's header_value
• Clock skew: enable NTP — authentication fails once the signature expires
• ARN type: bound_iam_principal_arn takes role or user ARNs — not policy ARNs
• In IAM mode, access_key/secret_key in auth/aws/config/client are not required
• Vault token TTL and policies are determined by the Vault role, not by AWS-side policies

Verification command snippets

# 応答の確認
vault login -method=aws role=app header_value=vault.example.com -format=json | jq '.auth.lease_duration,.auth.policies'

# 監査ログ（ファイル監査デバイス例）
vault audit enable file file_path=/var/log/vault_audit.log

tail -f /var/log/vault_audit.log | grep "/auth/aws/login"

Check Your Understanding

Frequently Asked Questions