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) or AWS CloudShell to decode the encoded message in the error message. The encoded message looks similar to the following example:

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

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 the permission, then the decode operation fails with the following error message:

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

Resolution

Note: If you receive errors when you run AWS Command Line Interface (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.
   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\"}]}}]}}}"
   }

   The decoded message lists the required permissions that are missing from the IAM user or role policy.
2. Review the principal, action, resource, condition, and key fields in the decoded message 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