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

Short description

The UnauthorizedOperation error indicates that permissions that are attached to the AWS Identity and Access Management (IAM) role aren't correct. Or, the user that's performing the operation doesn't have the required IAM permissions to launch EC2 instances. To get more details about the authorization failure, use the AWS Command Line Interface (AWS CLI) to decode the encoded message that's in the error message.

Prerequisite:

The IAM user or role that tries to decode the message must have permission to perform the DecodeAuthorizationMesssage API action with an IAM policy. If the user or role doesn't have this permission, then 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".

Note: If you receive errors when you run AWS CLI commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Resolution

To use the AWS CLI to decode the encoded message, complete the following steps:

1. To verify that the AWS CLI is installed and configured on your machine, run the following command:

   $ aws --version

2. Run the decode-authorization-message command:

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

   Note: Replace encoded-message with the exact encoded message that's contained in the error message.
   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
   ...
   "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\"}]}}]}}}"
   }

   Note: The request fails because the AWS-User doesn't have permission to perform the iam:PassRole action on the arn:aws:iam::accountID:role/EC2_instance_Profile_role.

3. Edit the IAM policy that's associated with the IAM role or user to add the missing required permissions.

Related information

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

Why can't I start or launch my EC2 instance?

Troubleshooting access denied error messages