How do I decode and analyze "You are not authorized to perform this operation" errors for Amazon EC2 instance launch failures?

Short description

If the AWS Identity and Access Management (IAM) policy is too restrictive, then you receive the "not authorized" error message. You also receive this error message if the IAM role or user doesn't have permission to launch EC2 instances.

The error includes an encoded message with details about the missing permissions. To identify the action, resource, or condition that caused the authorization to fail, decode the message. Then, update your IAM policy.

Example encoded error message:

"You are not authorized to perform this operation. User:arntest is not authorized to perform: ec2:RunInstances on resource: ARN* because no identity-based policy allows the ec2:RunInstances action. Encoded authorization failure message: - abcdefgh"

Note: If you use the AWS Command Line Interface (AWS CLI) or an SDK to launch the instance, then the error includes the "(UnauthorizedOperation)" error code.

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.

Verify that you have permission to decode the message

To decode the encoded message, the IAM user or role must have permission to perform the sts:DecodeAuthorizationMessage action. If you don't have the required permission, then you receive the following error message:

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

To add the missing permissions, update the IAM policy for your user or role with the following statement:

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

Decode the encoded message

To decode the encoded message, run the following decode-authorization-message AWS CLI command:

aws sts decode-authorization-message --encoded-message encoded-message \
 | jq -r '.DecodedMessage' | jq.

Note: The jq command writes the output as structured JSON that's easier to read. You can also run this command in AWS CloudShell that has jq installed by default. If you don't have jq installed, then remove \ | jq -r '.DecodedMessage' | jq from the preceding command.

If the decode operation fails with an "InvalidAuthorizationMessage" error, then verify that you used the same AWS credentials that received the original encoded error.

Interpret the decoded message

The DecodedMessage value is a JSON string with escaped quotes (\"). To interpret the message, check the allowed, explicitDeny, action, resource, and conditions fields. If you use jq, then the output formats the message without the escaped quotes.

Example output with jq:

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

Example output without jq:

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

If allowed is false, then the policy didn't allow the action. An explicitDeny shows whether the IAM policy has a Deny statement. If the value for explicitDeny is false, then the block occurred because of an implicit deny and there's a missing Allow statement. The matchedStatements shows the IAM policy statements that matched the request. If the list is empty, then there's no Allow statement for the required action.

The context.principal identifies the IAM user or role that made the request and context.action shows the specific action that got denied. The context.resource is the Amazon Resource Name (ARN) of the resource that the user tried to take the action on. The context.conditions lists the condition key values that Amazon EC2 evaluates during the request, such as AWS Region, service, and AWS account.

In the preceding example outputs, the request failed because test-user doesn't have permission to perform iam:PassRole on arn:aws:iam::123456789012:role/EC2_instance_Profile_role. There's no explicit deny, so the issue is that the user's IAM policy doesn't have an Allow statement that allows them to perform this action.

Update the IAM policy with the missing permission

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

Example policy based on the missing permissions in the example output:

{
 "Version": "2012-10-17",
 "Statement": [
  {
   "Sid": "AllowRunInstances",
   "Effect": "Allow",
   "Action": "ec2:RunInstances",
   "Resource": "*"
  },
  {
   "Sid": "AllowPassRoleToEC2",
   "Effect": "Allow",
   "Action": "iam:PassRole",
   "Resource": "arn:aws:iam::123456789012:role/EC2_instance_Profile_role",
   "Condition": {
    "StringEquals": {
     "iam:PassedToService": "ec2.amazonaws.com"
    }
   }
  }
 ]
}

Note: Replace 123456789012 with your account ID and EC2_instance_Profile_role with your role name. The iam:PassedToService condition is a security best practice that restricts users so that they can't pass to role to any service other than Amazon EC2.

You can also use the IAM policy simulator to verify that the updated policy grants the required permissions before you launch the instance. For a full list of required permissions to launch an instance, see Example: Use the EC2 launch instance wizard.

Related information

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

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

Troubleshoot access denied error messages

Granting permission to launch EC2 instances with IAM roles (PassRole permission)

Troubleshoot Amazon EC2 instance launch issues