How do I decode and analyze "UnauthorizedOperation" authorization errors for EC2 instance launch failures?

Short description

The UnauthorizedOperation error might occur when the AWS Identity and Access Management (IAM) policy is too restrictive. This error might also occur when the IAM user doesn't have permissions to launch EC2 instances. To get more details about the failure, use the AWS Command Line Interface (AWS CLI) to decode the encoded message that's in the error message.

Note: To decode the encoded message, the IAM user or role must have permission to perform the DecodeAuthorizationMesssage API operation. If the user or role doesn't have this permission, then the decode operation fails with the following error message:

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

Resolution

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

To decode the authorization failure error, complete the following steps:

1. Run the decode-authorization-message command:

   aws sts decode-authorization-message --encoded-message encoded-message-error

   Note: Replace encoded-message-error with the encoded message that's in the error message.

   The decoded message lists the required permissions that are missing from the IAM user or role 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\"}]}}]}}}"
   }

2. Check the principal, action, resource, condition, and key fields to get more information about the cause of the failure. The message includes the requested action and resource, the principal who made the request, and the condition key values of the user's request.

   In the preceding example, the request failed 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 ARN.

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

You can also use the IAM policy simulator to troubleshoot identity-based policies and IAM permission boundaries.

Related information

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

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

Troubleshoot access denied error messages