Grammar of the IAM JSON policy language - AWS Identity and Access Management
The policy language and JSONConventions used in this grammarGrammarPolicy grammar notes

Grammar of the IAM JSON policy language

This page presents a formal grammar for the language used to create JSON policies in IAM. We present this grammar so that you can understand how to construct and validate policies.

For examples of policies, see the following topics:

For examples of policies used in other AWS services, go to the documentation for those services.

The policy language and JSON

Policies are expressed in JSON. When you create or edit a JSON policy, IAM can perform policy validation to help you create an effective policy. IAM identifies JSON syntax errors, while IAM Access Analyzer provides additional policy checks with recommendations to help you further refine your policies. To learn more about policy validation, see IAM policy validation. To learn more about IAM Access Analyzer policy checks and actionable recommendations, see IAM Access Analyzer policy validation.

In this document, we do not provide a complete description of what constitutes valid JSON. However, here are some basic JSON rules:

  • White space between individual entities is allowed.

  • Values are enclosed in quotation marks. Quotation marks are optional for numeric and Boolean values.

  • Many elements (for example, action_string_list and resource_string_list) can take a JSON array as a value. Arrays can take one or more values. If more than one value is included, the array is in square brackets ([ and ]) and comma-delimited, as in the following example:

    "Action" : ["ec2:Describe*","ec2:List*"]

  • Basic JSON data types (Boolean, number, and string) are defined in RFC 7159.

Conventions used in this grammar

The following conventions are used in this grammar:

  • The following characters are JSON tokens and are included in policies:

    { } [ ] " , :

  • The following characters are special characters in the grammar and are not included in policies:

    = < > ( ) |

  • If an element allows multiple values, it is indicated using repeated values, a comma delimiter, and an ellipsis (...). Examples:

    [<action_string>, <action_string>, ...]

    <principal_map> = { <principal_map_entry>, <principal_map_entry>, ... }

    If multiple values are allowed, it is also valid to include only one value. For only one value, the trailing comma must be omitted. If the element takes an array (marked with [ and ]) but only one value is included, the brackets are optional. Examples:

    "Action": [<action_string>]

    "Action": <action_string>

  • A question mark (?) following an element indicates that the element is optional. Example:

    <version_block?>

    However, be sure to refer to the notes that follow the grammar listing for details about optional elements.

  • A vertical line (|) between elements indicates alternatives. In the grammar, parentheses define the scope of the alternatives. Example:

    ("Principal" | "NotPrincipal")

  • Elements that must be literal strings are enclosed in double quotation marks ("). Example:

    <version_block> = "Version" : ("2008-10-17" | "2012-10-17")

For additional notes, see Policy grammar notes following the grammar listing.

Grammar

The following listing describes the policy language grammar. For conventions used in the listing, see the preceding section. For additional information, see the notes that follow.

Note

This grammar describes policies marked with a version of 2008-10-17 and 2012-10-17. A Version policy element is different from a policy version. The Version policy element is used within a policy and defines the version of the policy language. A policy version, on the other hand, is created when you make changes to a customer managed policy in IAM. The changed policy doesn't overwrite the existing policy. Instead, IAM creates a new version of the managed policy. To learn more about the Version policy element see IAM JSON policy elements: Version. To learn more about policy versions, see Versioning IAM policies.

policy  = {
     <version_block?>
     <id_block?>
     <statement_block>
}

<version_block> = "Version" : ("2008-10-17" | "2012-10-17")

<id_block> = "Id" : <policy_id_string>

<statement_block> = "Statement" : [ <statement>, <statement>, ... ]

<statement> = { 
    <sid_block?>,
    <principal_block?>,
    <effect_block>,
    <action_block>,
    <resource_block>,
    <condition_block?>
}

<sid_block> = "Sid" : <sid_string>

<effect_block> = "Effect" : ("Allow" | "Deny")  

<principal_block> = ("Principal" | "NotPrincipal") : ("*" | <principal_map>)

<principal_map> = { <principal_map_entry>, <principal_map_entry>, ... }

<principal_map_entry> = ("AWS" | "Federated" | "Service" | "CanonicalUser") :   
    [<principal_id_string>, <principal_id_string>, ...]

<action_block> = ("Action" | "NotAction") : 
    ("*" | [<action_string>, <action_string>, ...])

<resource_block> = ("Resource" | "NotResource") : 
    : ("*" | <resource_string> | [<resource_string>, <resource_string>, ...])

<condition_block> = "Condition" : { <condition_map> }
<condition_map> = { 
  <condition_type_string> : { <condition_key_string> : <condition_value_list> },
  <condition_type_string> : { <condition_key_string> : <condition_value_list> }, ...
}  
<condition_value_list> = [<condition_value>, <condition_value>, ...]
<condition_value> = (<condition_value_string> | <condition_value_string> | <condition_value_string>)

Policy grammar notes

  • A single policy can contain an array of statements.

  • Policies have a maximum size between 2048 characters and 10,240 characters, depending on what entity the policy is attached to. For more information, see IAM and AWS STS quotas. Policy size calculations do not include white space characters.

  • Individual elements must not contain multiple instances of the same key. For example, you cannot include the Effect block twice in the same statement.

  • Blocks can appear in any order. For example, version_block can follow id_block in a policy. Similarly, effect_block, principal_block, action_block can appear in any order within a statement.

  • The id_block is optional in resource-based policies. It must not be included in identity-based policies.

  • The principal_block element is required in resource-based policies (for example, in Amazon S3 bucket policies) and in trust policies for IAM roles. It must not be included in identity-based policies.

  • The principal_map element in Amazon S3 bucket policies can include the CanonicalUser ID. Most resource-based policies do not support this mapping. To learn more about using the canonical user ID in a bucket policy, see Specifying a Principal in a Policy in the Amazon Simple Storage Service User Guide.

  • Each string value (policy_id_string, sid_string, principal_id_string, action_string, resource_string, condition_type_string, condition_key_string, and the string version of condition_value) can have its own minimum and maximum length restrictions, specific allowed values, or required internal format.

Notes about string values

This section provides additional information about string values that are used in different elements in a policy.

action_string

Consists of a service namespace, a colon, and the name of an action. Action names can include wildcards. Examples:

"Action":"ec2:StartInstances"

"Action":[
  "ec2:StartInstances",
  "ec2:StopInstances"
]

"Action":"cloudformation:*"

"Action":"*"

"Action":[
  "s3:Get*",
  "s3:List*"
]
policy_id_string

Provides a way to include information about the policy as a whole. Some services, such as Amazon SQS and Amazon SNS, use the Id element in reserved ways. Unless otherwise restricted by an individual service, policy_id_string can include spaces. Some services require this value to be unique within an AWS account.

Note

The id_block is allowed in resource-based policies, but not in identity-based policies.

There is no limit to the length, although this string contributes to the overall length of the policy, which is limited. 

"Id":"Admin_Policy"

"Id":"cd3ad3d9-2776-4ef1-a904-4c229d1642ee"
sid_string

Provides a way to include information about an individual statement. For IAM policies, basic alphanumeric characters (A-Z,a-z,0-9) are the only allowed characters in the Sid value. Other AWS services that support resource policies may have other requirements for the Sid value. For example, some services require this value to be unique within an AWS account, and some services allow additional characters such as spaces in the Sid value.

"Sid":"1" 

"Sid": "ThisStatementProvidesPermissionsForConsoleAccess"
principal_id_string

Provides a way to specify a principal using the Amazon Resource Name (ARN) of the AWS account, IAM user, IAM role, federated user, or assumed-role user. For an AWS account, you can also use the short form AWS:accountnumber instead of the full ARN. For all of the options including AWS services, assumed roles, and so on, see How to specify a principal.

Note that you can use * only to specify "everyone/anonymous." You cannot use it to specify part of a name or ARN.

resource_string

In most cases, consists of an Amazon Resource Name (ARN).

"Resource":"arn:aws:iam::123456789012:user/Bob"

"Resource":"arn:aws:s3:::amzn-s3-demo-bucket/*"
condition_type_string

Identifies the type of condition being tested, such as StringEquals, StringLike, NumericLessThan, DateGreaterThanEquals, Bool, BinaryEquals, IpAddress, ArnEquals, etc. For a complete list of condition types, see IAM JSON policy elements: Condition operators. 

"Condition": {
  "NumericLessThanEquals": {
    "s3:max-keys": "10"
  }
}

"Condition": {
  "Bool": {
    "aws:SecureTransport": "true"
  }
}

"Condition": {
  "StringEquals": {
      "s3:x-amz-server-side-encryption": "AES256"
   }
}
condition_key_string

Identifies the condition key whose value will be tested to determine whether the condition is met. AWS defines a set of condition keys that are available in all AWS services, including aws:PrincipalType, aws:SecureTransport, and aws:userid.

For a list of AWS condition keys, see AWS global condition context keys. For condition keys that are specific to a service, see the documentation for that service such as the following:

"Condition":{
  "Bool": {
      "aws:SecureTransport": "true"
   }
}

"Condition": {
  "StringNotEquals": {
      "s3:x-amz-server-side-encryption": "AES256"
   }
}

"Condition": {
  "StringEquals": {
    "aws:ResourceTag/purpose": "test"
  }
}
condition_value_string

Identifies the value of the condition_key_string that determines whether the condition is met. For a complete list of valid values for a condition type, see IAM JSON policy elements: Condition operators.

"Condition":{
  "ForAnyValue:StringEquals": {
		"dynamodb:Attributes": [
			"ID",
			"PostDateTime"
  	      ]
  }
}