Fix: Encoded authorization failure message

You called an AWS API and got back an Encoded authorization failure message followed by a long opaque blob instead of a readable reason. This is not a bug and the blob is not corrupt: AWS deliberately encodes the authorization decision because it can expose policy details the denied caller is not entitled to see. The blob contains exactly what you need. You just have to decode it with the right permission to read which statement, action, and resource produced the denial.

Encoded authorization failure message: <encoded blob>

What this error means

When an AWS request fails authorization, some services return the full evaluation detail in an encoded string rather than plain text. That string is a signed, encoded representation of the authorization decision. A principal with the sts:DecodeAuthorizationMessage permission can decode it into JSON that describes the request context and, critically, which policy allowed or denied the action. The decoded document includes an allowed boolean, an explicitDeny boolean, and the matched statements from the identity policy and any service control policy, along with the action and resource ARN that were evaluated. Reading that JSON turns a mystery into a specific, fixable policy gap.

Common causes

• The identity policy is missing an Allow for the action, so the request hit an implicit deny.
• An explicit Deny in a service control policy (SCP) from AWS Organizations blocked the action, often a region or service guardrail.
• A permissions boundary on the role capped the effective permissions below what the identity policy granted.
• The action was scoped to the wrong resource ARN, so the Allow that exists did not match the resource in the request.
• A Condition key did not match at request time (for example a VPC endpoint, source IP, or org ID condition).
• The call was made by a different principal than expected (an instance profile or execution role), which lacks the permission.

How to fix it

STABILIZE

1. If a production workload is blocked and this denial appeared after a recent change, roll that change back while you investigate rather than widening permissions under pressure. Confirm which principal is actually failing from the affected environment itself:

aws sts get-caller-identity

DIAGNOSE

1. Decode the blob. This is the whole point: copy the encoded string from the error and pass it to STS. The --query and jq pipe give you readable JSON:

aws sts decode-authorization-message \
  --encoded-message <blob> \
  --query DecodedMessage \
  --output text | jq

2. Read the decoded JSON. The top level DecodedMessage (already unwrapped above) contains a context block with the principal, the action, and the resource that were evaluated. It also contains a matchedStatements list and, when applicable, a failures list. The two fields that tell you the nature of the denial are:

   • allowed: whether the request was permitted overall (this will be false here).
   • explicitDeny: whether a statement with Effect: Deny matched. If explicitDeny is true, a Deny statement blocked you, commonly in an SCP. If explicitDeny is false and allowed is false, no Allow matched, so this is an implicit deny and you are simply missing a grant.

3. Note the exact action and resource from the decoded context. These are the strings your policy must match, character for character, including the partition and account in the ARN.

FIX

1. If the decode shows an implicit deny (no Allow matched), add a minimal statement scoped to the exact action and resource from the decoded context:

aws iam put-role-policy \
  --role-name app-role \
  --policy-name allow-decoded-action \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": ["ec2:RunInstances"],
      "Resource": "arn:aws:ec2:us-east-1:123456789012:instance/*"
    }]
  }'

2. If the decode shows an explicit deny, the blocking statement is usually an SCP or a permissions boundary you cannot see from the application account. Take the matched statement to your AWS Organizations administrator and confirm which guardrail applies, then request an exception or adjust the workload to fit the guardrail.
3. If the action was allowed but the resource did not match, correct the resource ARN in the policy so it matches the decoded resource exactly rather than a broader or narrower pattern.

How to prevent it

• Grant sts:DecodeAuthorizationMessage to your operators and CI roles so anyone debugging a denial can read the reason immediately.
• Scope policies to the exact action and resource ARNs your workloads use, so an implicit deny is rare and obvious when it happens.
• Keep a record of which SCPs and permissions boundaries apply per account, since those are the layers application teams cannot inspect themselves.
• Validate policy changes with IAM Access Analyzer before deploying them.
• Test policy changes in a staging account governed by the same SCPs and boundaries as production.

When to call a senior engineer

Call for help when the decoded message points to an explicit deny in an SCP or boundary that nobody in your team owns, when the denial crosses account boundaries and the full policy picture is unclear, or when unblocking the workload keeps drifting toward wildcard permissions. Erzon engineers can decode the message, trace the denying statement across every evaluation layer, and restore access with least privilege instead of stars so your team can reason about the account afterward.