AWS STS InvalidIdentityToken Decoder

The Incident (What Does the Error Mean?)

You called aws sts decode-authorization-message --encoded-message <value> from an EC2 instance and received:

An error occurred (InvalidIdentityToken) when calling the DecodeAuthorizationMessage operation:
  The identity token included in the request is invalid.

Immediate consequence: You cannot decode the original access-denied authorization message, which means the root cause of your actual permission failure remains completely opaque. This is a double-failure: the primary action is blocked, and the diagnostic tool is also blocked. Production debugging time compounds rapidly.

This error surfaces in three distinct scenarios:

1. Expired token: The STS temporary credentials fetched from http://169.254.169.254/latest/meta-data/iam/security-credentials/<role-name> have passed their Expiration timestamp. The SDK has not yet rotated them, or credential caching is broken.
2. Missing IAM permission: The instance role's attached policy does not include sts:DecodeAuthorizationMessage. STS requires this as an explicit allow — it is not inherited from any wildcard on other services.
3. Wrong input value: The --encoded-message parameter must receive the encoded field from the original AccessDenied error response body, not the session token itself. Confusing these two strings is the most common operator error.

The Attack Vector / Blast Radius

Why this matters beyond a debugging annoyance:

Temporary credentials from EC2 instance profiles are the primary lateral movement vector in AWS compromise scenarios. When InvalidIdentityToken is thrown repeatedly and silently swallowed by application code, engineers frequently respond by broadening IAM permissions to "fix" the underlying access-denied error without understanding what it actually was. This is how sts:* or iam:* wildcards get introduced into production roles.

Specifically:

• Token expiry not caught in code means your application is running with stale credentials. If the credential refresh loop is broken (e.g., IMDSv2 hop limit set to 1 on a containerized workload inside EC2), the instance silently loses its identity. Any attacker who has already obtained a copy of the expired token cannot reuse it — but your application is now effectively unauthenticated and will fail open or fail in unpredictable ways.
• If sts:DecodeAuthorizationMessage is over-granted (e.g., attached to a role accessible by untrusted workloads), any principal with that role can decode authorization messages for any encoded message they intercept, leaking your account's IAM policy structure, resource ARNs, and action boundaries to an attacker performing reconnaissance.
• Cross-account confusion: If the EC2 instance assumes a role in another account via sts:AssumeRole and then tries to call DecodeAuthorizationMessage, the decoded message context is evaluated against the target account's policies. Misconfigured trust policies here cause InvalidIdentityToken because the token issuer does not match the expected partition/account in the signed token.

Prevention in CI/CD

Stop this from reaching production in the first place.

1. Checkov — Scan IAM Policies in Terraform Before `terraform apply`

checkov -d ./terraform --check CKV_AWS_109,CKV_AWS_110,CKV_AWS_111

Add a custom Checkov check to flag any EC2 instance profile role that references sts:AssumeRole without a corresponding sts:DecodeAuthorizationMessage allow — these always travel together in debuggable production systems.

2. OPA/Conftest Policy — Enforce in Terraform Plan

# policy/sts_decode_required.rego
package aws.iam

deny[msg] {
  role := input.resource_changes[_]
  role.type == "aws_iam_role"
  not has_decode_permission(role)
  msg := sprintf(
    "Role '%v' is attached to an EC2 instance profile but lacks sts:DecodeAuthorizationMessage. Add it as a managed policy.",
    [role.address]
  )
}

has_decode_permission(role) {
  policy := role.change.after.inline_policy[_]
  contains(policy.policy, "sts:DecodeAuthorizationMessage")
}

terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json
conftest test tfplan.json --policy policy/

3. AWS Config Rule — Continuous Compliance

Deploy the managed AWS Config rule iam-policy-no-statements-with-admin-access and supplement it with a custom Lambda-backed Config rule that:

• Evaluates all EC2 instance profile roles on change
• Flags roles that have s3:*, ec2:*, or other broad actions without a corresponding sts:DecodeAuthorizationMessage allow (indicating the role was likely broadened to avoid debugging the original error)

4. CloudTrail Alert — Detect Token Expiry Loops

{
  "source": ["aws.sts"],
  "detail-type": ["AWS API Call via CloudTrail"],
  "detail": {
    "eventName": ["DecodeAuthorizationMessage"],
    "errorCode": ["InvalidIdentityToken"]
  }
}

Route this EventBridge rule to an SNS topic. More than 3 occurrences per hour from the same sourceIPAddress (your EC2 instance's private IP) means the credential rotation loop is broken and the instance is running degraded.

5. IMDSv2 Enforcement via SCP

{
  "Sid": "DenyIMDSv1",
  "Effect": "Deny",
  "Action": "ec2:RunInstances",
  "Resource": "arn:aws:ec2:*:*:instance/*",
  "Condition": {
    "StringNotEquals": {
      "ec2:MetadataHttpTokens": "required"
    }
  }
}

Apply this SCP at the OU level. IMDSv1 is the primary reason credential refresh silently fails in containerized workloads on EC2 — the hop limit of 1 blocks the metadata call from inside the container, causing the SDK to serve expired cached credentials indefinitely.