How to Read Encoded Authorization Error Messages in AWS

When working with AWS IAM (Identity and Access Management) and AWS services, you may occasionally run into AccessDenied or UnauthorizedOperation errors. These errors can be vague, especially in production environments where policies, roles, and service control policies (SCPs) may overlap.

To improve security and not expose sensitive internal permission structures, AWS encodes certain authorization failure messages. This post will teach you how to decode and read those encoded authorization errors, enabling you to debug access issues quickly and securely.

Why Are AWS Error Messages Encoded?

AWS encodes certain error messages for security reasons. When a user or service doesn’t have access to a resource, AWS may return a message like:

An error occurred (AccessDenied) when calling the DescribeInstances operation: 
User is not authorized to perform: ec2:DescribeInstances on resource: arn:aws:ec2:region:account-id:instance/instance-id 
(encoded message: eTDFi1nQHZWuYb4Fz5f4k5L+EXAMPLE==)

The encoded message is there to provide more detail — but only to someone with the necessary privileges to decode it.

This prevents information leakage to attackers (e.g., details about policies or account structure) while still enabling authorized users to debug.

Prerequisites

To decode an AWS authorization error message, you'll need:

• AWS CLI installed and configured

• IAM permissions to use sts:DecodeAuthorizationMessage

• The encoded message string

If you do not have permission to call sts:DecodeAuthorizationMessage, you’ll need help from an IAM administrator.

Step-by-Step: Decoding AWS Authorization Error Messages

Step 1 - Capture the Encoded Message

From your CLI or API error, copy the encoded message. It typically looks like this:

encoded message: jC9GHT6rskfdue3sd9SDJ9sdfK== 

Step 2 - Use aws sts decode-authorization-message

AWS provides a method via the STS (Security Token Service) API:

aws sts decode-authorization-message \
  --encoded-message "jC9GHT6rskfdue3sd9SDJ9sdfK==" \
  --query DecodedMessage \
  --output text

This will return a JSON-formatted message like:

{
  "allowed": false,
  "explicitDeny": false,
  "matchedStatements": [],
  "failures": [
    {
      "action": "ec2:DescribeInstances",
      "resource": "arn:aws:ec2:region:account-id:instance/instance-id",
      "reason": "No applicable policies allow this action."
    }
  ],
  "context": {
    "principal": {
      "id": "AROAEXAMPLEID",
      "arn": "arn:aws:iam::123456789012:role/my-role"
    }
  }
}

Step 3 - Interpret the Output

• allowed: Whether the request is allowed (usually false for errors).

• explicitDeny: If there is an explicit deny from a policy or SCP.

• failures: Lists what went wrong and why.

• matchedStatements: Shows policies that matched the request.

• context: Contains the identity (user or role) that made the request.

Real-World Example

Error Message:

An error occurred (UnauthorizedOperation) when calling the ModifyInstanceAttribute operation:
You are not authorized to perform this operation. 
(encoded message: AbCdEf123456EXAMPLE==)

Decoded Output:

{
  "allowed": false,
  "failures": [
    {
      "action": "ec2:ModifyInstanceAttribute",
      "resource": "*",
      "reason": "Explicit deny from service control policy"
    }
  ],
  "context": {
    "principal": {
      "arn": "arn:aws:iam::123456789012:user/devops-engineer"
    }
  }
}

Resolution Steps:

• The action was blocked due to an explicit deny in an SCP.

• You would check the AWS Organizations SCPs attached to the account or OU.

• Work with your org admin to update the SCP if necessary.

IAM Permissions Required to Decode

To use the sts:DecodeAuthorizationMessage API, your IAM identity must have a policy like:

{
  "Effect": "Allow",
  "Action": "sts:DecodeAuthorizationMessage",
  "Resource": "*"
}

This action is considered read-only and low risk, but it’s typically granted only to admins or security roles.

Pro Tips

• CloudTrail Logging: Errors with encoded messages are often logged in CloudTrail. You can extract the encoded message from the logs.

• Decode via SDK: AWS SDKs (Python, Go, etc.) can decode these messages programmatically using the DecodeAuthorizationMessage API.

• Policy Simulator: You can simulate IAM access with the IAM Policy Simulator, which can help predict and debug permission issues.

Troubleshooting Common Cases

Scenario	Cause	Resolution
Encoded message shows No applicable policies	No IAM policy allows the action	Attach a policy with the required action and resource
Message shows Explicit deny	SCP or IAM policy has a Deny statement	Remove or adjust the deny rule
Principal is incorrect	Action is made using a wrong role or user	Ensure correct identity is assuming the role
No DecodeAuthorizationMessage permission	Cannot decode the message	Request access from AWS admin

Conclusion

Encoded AWS error messages can be frustrating — but they're also an intentional security feature. By learning how to decode and read them, you can quickly diagnose permission issues, tighten security, and avoid unnecessary troubleshooting.

Mastering this small but powerful tool in the AWS toolkit can save hours and foster safer IAM practices in your infrastructure.

Bookmark this post for the next time AWS gives you a cryptic "AccessDenied."

SPEAK TO OUR CLOUD EXPERT