Menu
AWS Identity and Access Management
User Guide

Troubleshoot IAM Policies

Use the information here to help you diagnose and fix common errors found in IAM policies.

IAM policies use syntax that begins with the rules of JavaScript Object Notation (JSON). JSON describes an 'object' and the name and value pairs that make up an object. The IAM policy grammar builds on that by defining what names and values have meaning for, and are understood by, the AWS services that use policies to grant permissions.

More Than One Policy Object

An IAM policy must consist of one and only one JSON object. You denote an object by placing { } braces around it. Although you can nest other objects within a JSON object by embedding additional { } braces within the outer pair, a policy can contain only one outermost pair of { } braces. The following example is incorrect because it contains two objects at the top level (called out in red:

{
  "Version": "2012-10-17",
  "Statement": 
  {
     "Effect":"Allow",
     "Action":"ec2:Describe*",
     "Resource":"arn:aws:ec2:us-east-2:ACCOUNT-ID-WITHOUT-HYPHENS:instance/*"
  }
}
{ 
  "Statement": {
     "Effect": "Allow",
     "Action": "s3:*",
     "Resource": "arn:aws:s3:::my-bucket/*"
  }
}

You can, however, meet the intention of the previous example with the use of correct policy grammar. Instead of including two complete policy objects each with its ownStatement element, you can combine the two blocks into a single Statement element. The Statement element has an array of two objects as its value, as shown in the following example:

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ec2:Describe*", "Resource":" arn:aws:ec2:us-east-2:ACCOUNT-ID-WITHOUT-HYPHENS:instance/*" }, { "Effect": "Allow", "Action": "s3:*", "Resource": "arn:aws:s3:::my-bucket/*" } ] }

More Than One Statement Element

This error might at first appear to be a variation on the previous section. However, syntactically it is a different type of error. The following example has only one policy object as denoted by a single pair of { } braces at the top level. However, that object contains two Statement elements within it.

An IAM policy must contain only one Statement element, consisting of the name (Statement) appearing to the left of a colon, followed by its value on the right. The value of a Statement element must be an object, denoted by { } braces, containing one Effect element, one Action element, and one Resource element. The following example is incorrect because it contains two Statement elements in the policy object.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "ec2:Describe*",
    "Resource": "*"
  },
  "Statement": {
    "Effect": "Allow",
    "Action": "s3:*",
    "Resource": "arn:aws:s3:::my-bucket/*"
  }
}

A value object can be an array of multiple value objects. To solve this problem, combine the two Statement elements into one element with an object array, as shown in the following example:

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ec2:Describe*", "Resource":"*" }, { "Effect": "Allow", "Action": "s3:*", "Resource": "arn:aws:s3:::my-bucket/*" } ] }

The value of the Statement element is an object array. The array in this example consists of two objects, each of which is by itself is a correct value for a Statement element. Each object in the array is separated by commas.

More Than One Effect, Action, or Resource Element in a Statement Element

On the value side of the Statement name/value pair, the object must consist of only one Effect element, one Action element, and one Resource element. The following policy is incorrect because it has two Effect elements in the value object of the Statement:

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Deny",
    "Effect": "Allow",     
    "Action": "ec2:* ",
    "Resource": "*"
  }
}

Note

The policy engine has been updated to block such errors in new or edited policies. However, the policy engine continues to permit policies that were saved before the engine was updated. The behavior of existing policies with the error is as follows:

  • Multiple Effect elements: only the last Effect element is observed. The others are ignored.

  • Multiple Action elements: all Action elements are combined internally and treated as if they were a single list.

  • Multiple Resource elements: all Resource elements are combined internally and treated as if they were a single list.

The policy engine does not allow you to save any policy with syntax errors. You must correct the errors in the policy before you can save it. The Policy Validator tool can help you to find all older policies with errors and can recommend corrections for them.

In each case, the solution is to remove the incorrect extra element. For Effect elements, this is straightforward: if you want the previous example to deny permissions to Amazon EC2 instances, then you must remove the line "Effect": "Allow", from the policy, as follows:

Copy
{ "Version": "2012-10-17", "Statement": { "Effect": "Deny", "Action": "ec2:* ", "Resource": "*" } }

However, if the duplicate element is Action or Resource, then the resolution can be more complicated. You might have multiple actions that you want to allow (or deny) permission to, or you might want to control access to multiple resources. For example, the following example is incorrect because it has multiple Resource elements:

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "s3:*",
    "Resource": "arn:aws:s3:::my-bucket",
    "Resource": "arn:aws:s3:::my-bucket/*"
  }
}

Each of the required elements in a Statement element's value object can be present only once. The solution is to place each value in an array. The following example illustrates this by making the two separate resource elements into one Resource element with an array as the value object:

Copy
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "s3:*", "Resource": [ "arn:aws:s3:::my-bucket", "arn:aws:s3:::my-bucket/*" ] } }

Missing Policy Summary

The IAM console includes a table that summarizes the access level, resources, and conditions allowed or denied for each service within a policy. This policy summary is included on the Policies page for managed policies, and on the Users page for policies that are attached to a user. If AWS is unable to render a summary for a policy, then you see the JSON policy document instead of the summary, and receive the following error:

A summary for this policy cannot be generated. You can still view or edit the JSON policy document.

If your policy does not include a summary, one of the following errors has occurred:

  • Unsupported policy element – AWS does not support generating policy summaries for policies that include one of the following policy elements:

    • Principal

    • NotPrincipal

    • Resource

  • Policy object does not exist – AWS cannot generate a policy if that policy includes objects that do not exist. For example, if you intended for your policy to allow actions on the S3 bucket named thatBucket, but only a bucket named thisBucket exists, then the policy summary cannot be generated.

  • Service does not support summaries – If your policy includes an action or resource for a service that does not support policy summaries, then you can only view the JSON policy document. To determine whether a service supports policy summaries, you can create a temporary policy that provides access to all of the actions (*) and all of the resources (*) in that service. If the summary does not appear for this basic all-access policy, then the service does not support summaries.

  • No policy permissions – If a policy does not provide permissions, then the policy summary cannot be generated. For example, if a policy includes "NotAction": "*", then it grants access to all actions except "all actions" (*). This means it grants Deny or Allow access to nothing.

    Note

    You must be careful when using policy elements such as NotPrincipal, NotAction, and NotResource. For information about using policy elements, see IAM Policy Elements Reference.

  • Typo – Because the policy validator in AWS checks only that the JSON is syntactically correct, you can create a policy that includes a typo. If you are certain that your policy contains none of the errors above, then your policy might include a typo. Check for misspelled service names, such as s2 instead of s3 and ce2 instead of ec2. Another common typo is the inclusions of unnecessary text in ARNs, such as arn:aws:s3: : :*, or missing colons in actions, such as AWSAuthRuntimeService.AuthenticatePassword. You can evaluate a policy that might include typos by using the policy simulator to confirm whether the policy provides the permissions you intended.

Missing Version Element

As AWS features evolve, new capabilities are added to IAM policies to support those features. Sometimes, an update to the policy syntax includes a new version number. If you use newer features of the policy grammar in your policy, then you must tell the policy parsing engine which version you are using. The default policy version is "2008-10-17". If you want to use any policy feature that was introduced later, then you must specify the version number that supports the feature you want. We recommend that you always include the latest policy syntax version number, which is "Version": "2012-10-17". For example, the following policy is incorrect because it uses a policy variable ${...} in the ARN for a resource without specifying a policy syntax version that supports policy variables:

{
  "Statement": 
  {
    "Action": "iam:*AccessKey*",
    "Effect": "Allow",
    "Resource": "arn:aws:iam::123456789012:user/${aws:username}"
  }
}

Adding a Version element at the top of the policy with the value 2012-10-17, the first IAM API version that supports policy variables, solves this problem:

Copy
{ "Version": "2012-10-17", "Statement": { "Action": "iam:*AccessKey*", "Effect": "Allow", "Resource": "arn:aws:iam::123456789012:user/${aws:username}" } }

I Can't Attach or Detach a Policy in My IAM Account

Some AWS managed policies are linked to a service. These policies are used only with a service-linked role for that service. In the IAM console, when you view the Summary page for a policy, the page includes a banner to indicate that the policy is linked to a service. You cannot attach this policy to a user, group, or role within IAM. When you create a service-linked role for the service, this policy is automatically attached to your new role. Because the policy is required, you cannot detach the policy from the service-linked role.