How can I decode an authorization failure message after receiving an "UnauthorizedOperation" error during an EC2 instance launch?

Short description

The "UnauthorizedOperation" error indicates that permissions attached to the AWS Identity and Access Management (IAM) role or user trying to perform the operation doesn't have the required permissions to launch EC2 instances. Because the error involves an encoded message, use the AWS Command Line Interface (AWS CLI) to decode the message. This decoding provides more details regarding the authorization failure.

Prerequisite

The IAM user or role attempting to decode the encoded message must have permission to the DecodeAuthorizationMesssage API action with an IAM policy. If the user or role doesn't have this permission, the decode action fails and the following error message appears:

"Error: A client error (AccessDenied) occurred when calling the DecodeAuthorizationMessage operation: User: xxx is not authorized to perform: (sts:DecodeAuthorizationMessage) action".

Resolution

1.    Verify that the AWS CLI is installed and configured on your machine with the following command:

$ aws --version

Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent version of the AWS CLI.

2.    Run the decode-authorization-message command. Replace encoded-message with the exact encoded message contained in the error message.

$ aws sts decode-authorization-message --encoded-message encoded-message

3.    The decoded message lists the required permissions that are missing from the IAM role or user policy.

Example encoded message:

Launch Failed - You are not authorized to perform this operation. Encoded authorization failure message: 4GIOHlTkIaWHQD0Q0m6XSnuUMCm-abcdefghijklmn-abcdefghijklmn-abcdefghijklmn

Example decoded message:

$ aws sts decode-authorization-message --encoded-message 4GIOHlTkIaWHQD0Q0m6XSnuUMCm-abcdefghijklmn-abcdefghijklmn-abcdefghijklmn

{
    "DecodedMessage": 
"{\"allowed\":false,\"explicitDeny\":false,\"matchedStatements\":{\"items\":[]},\"failures\":{\"items\":[]},\"context\":{\"principal\":{\"id\":\"ABCDEFGHIJKLMNO\",\"name\":\"AWS-User\",
\"arn\":\"arn:aws:iam::accountID:user/test-user\"},\"action\":\"iam:PassRole\",
\"resource\":\"arn:aws:iam::accountID:role/EC2_instance_Profile_role\",\"conditions\":{\"items\":[{\"key\":\"aws:Region\",\"values\":{\"items\":[{\"value\":\"us-east-2\"}]}},
{\"key\":\"aws:Service\",\"values\":{\"items\":[{\"value\":\"ec2\"}]}},{\"key\":\"aws:Resource\",\"values\":{\"items\":[{\"value\":\"role/EC2_instance_Profile_role\"}]}},
{\"key\":\"iam:RoleName\",\"values\":{\"items\":[{\"value\":\"EC2_instance_Profile_role\"}]}},{\"key\":\"aws:Account\",\"values\":{\"items\":[{\"value\":\"accountID\"}]}},
{\"key\":\"aws:Type\",\"values\":{\"items\":[{\"value\":\"role\"}]}},{\"key\":\"aws:ARN\",\"values\":{\"items\":[{\"value\":\"arn:aws:iam::accountID:role/EC2_instance_Profile_role\"}]}}]}}}"
}

The preceding error message indicates that the request failed to call RunInstances because AWS-User didn't have permission to perform the iam:PassRole action on the arn:aws:iam::accountID:role/EC2_instance_Profile_role.

4.    Edit the IAM policy associated with the IAM role or user to add the missing required permissions listed in the preceding step.

---

Related information

Why can't I run AWS CLI commands on my EC2 instance?

Why am I unable to start or launch my EC2 instance?