Element Descriptions

The Version is the access policy language version. This is an optional element, and currently the only allowed value is 2008-10-17.

"Version":"2008-10-17"

The Statement is the main element for a statement. It can include multiple elements (see the subsequent sections in this guide).

The Statement element contains an array of individual statements. Each individual statement is a distinct JSON block enclosed in curly brackets { }.

"Statement":[{...},{...},{...}]

The Sid (statement ID) is an optional identifier you provide for the policy statement. The Sid must be unique within a single policy.

The Sid is not exposed in the IAM API. You can't retrieve a particular statement based on this ID.

"Sid" : "1"

The Effect is a required element that indicates whether you want the statement to result in an allow or an explicit deny (for more information, see Explicit Deny).

Valid values for Effect are Allow and Deny.

"Effect":"Allow"

The Principal is the person or persons who receive or are denied permission according to the policy. Although Principal is a legitimate element in the access policy language, you must not include it in IAM policies. The principal is implied and is the user or group the policy is attached to. The Principal element is applicable if you're writing a resource-based policy for an SQS queue, for example.

The Action is the specific type or types of access allowed or denied (for example, read or write). You can specify one or multiple values for this element.

"Action":["iam:CreateAccessKey","iam:ListAccessKeys"]

The values must be one of the expected values for the particular AWS product in question, and the value must be prefixed with a namespace value indicating the AWS product in question. The prefix and the action name are case insensitive. For example, iam:ListAccessKeys is equivalent to IAM:listaccesskeys. For information about the correct namespaces and actions to use, see Integrating with Other AWS Products.

You can use a wildcard (*) to give access to all the actions the specific AWS product offers. For example, the following Action element applies to all IAM actions.

"Action":"iam:*"

You can also use wildcards (* or ?) within the action name itself. For example, the following Action element applies to all IAM actions that include the string AccessKey.

"Action":"iam:*AccessKey*"

The NotAction element is useful if you want to make an exception to a list of actions. You could use this, for example, if you want your users to be able to use only the SQS SendMessage.

The following example refers to all actions other than the SQS SendMessage. You would use this in a policy with "Effect":"Deny" to keep users from accessing any other actions.

"NotAction":"sqs:SendMessage"

The Resource is the object or objects the policy covers. For a list of the types of resources you can specify in a policy, and the format you must use (called the Amazon Resource Name (ARN)), see Identifiers for IAM Entities and also Integrating with Other AWS Products.

You can specify one or multiple resources in the policy, and you can use wildcards. The following example refers to the user named Bob with path /division_abc/subdivision_xyz/ in your AWS account.

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

The following example refers to all users whose path is /division_abc/subdivision_xyz/.

"Resource":"arn:aws:iam::123456789012:user/division_abc/subdivision_xyz/*"

The NotResource element is useful if you want to make an exception to a list of resources. You could use this, for example, if you want your users to be able to access a specific Amazon SQS queue belonging to the AWS account. If the AWS account were to create a new queue for the company, an admin wouldn't have to update the policy with the new queue's name in order to prevent users from being able to use the queue. By default, the users wouldn't be able to use it.

The following example refers to all resources other than your company's queue called my_corporate_queue. You would use this in a policy with "Effect":"Deny" to keep users from accessing any queue besides my_corporate_queue.

"NotResource":"arn:aws:sqs:*:123456789012:my_corporate_queue"

This section describes the Condition element and the information you can use inside the element.

The Condition Block

The Condition element is the most complex part of the policy statement. We refer to it as the condition block, because although it has a single Condition element, it can contain multiple conditions, and each condition can contain multiple key-value pairs. The following figure illustrates this. Unless otherwise specified for a particular key, all keys can have multiple values.

When creating a condition block, you specify the name of each condition, and at least one key-value pair for each condition. AWS defines the conditions and keys you can use (they're listed in the subsequent sections). An example of a condition is NumericEquals. Let's say you have a fictional resource, and you want to let John use it only if some particular numeric value foo equals either A or B, and another numeric value bar equals C. Then you would create a condition block that looks like the following figure.

Let's say you also want to restrict John's access to after January 1, 2009. Then you would add another condition, DateGreaterThan, with a date equal to January 1, 2009. The condition block would then look like the following figure.

As illustrated in the following figure, we always apply a logical AND to the conditions within a condition block, and to the keys within a condition. We always apply a logical OR to the values for a single key. All conditions must be met to return an allow or an explicit deny decision. If a condition isn't met, the result is a default deny.

As mentioned, AWS defines the conditions and keys you can use (for example, one of the keys is aws:CurrentTime, which lets you restrict access based on the date and time). The AWS service itself can also define its own service-specific keys. For a list of available keys, see Available Keys.

For a concrete example that uses real keys, let's say you want to let John access your Amazon resource under the following three conditions:

• The time is after 12:00 noon on 8/16/2010

• The time is before 3:00 p.m. on 8/16/2010

• The request comes from an IP address within the 192.168.176.0/24 range or the 192.168.143.0/24 range

Your condition block has three separate conditions, and all three of them must be met for John to have access to your resource.

The following shows what the condition block looks like in your policy.

"Condition" :  {
      "DateGreaterThan" : {
         "aws:CurrentTime" : "2009-04-16T12:00:00Z"
       },
      "DateLessThan": {
         "aws:CurrentTime" : "2009-04-16T15:00:00Z"
       },
       "IpAddress" : {
          "aws:SourceIp" : ["192.168.176.0/24","192.168.143.0/24"]
      }
}

Available Keys

AWS provides a set of common keys supported by all AWS services that adopt the access policy language for access control. These keys are:

• aws:CurrentTime—For date/time conditions (see Date Conditions)

• aws:EpochTime—The date in epoch or UNIX time, for use with date/time conditions (see Date Conditions)

• aws:SecureTransport—Boolean representing whether the request was sent using SSL (see Boolean Conditions)

• aws:SourceIp—The requester's IP address, for use with IP address conditions (see IP Address)

• aws:UserAgent—Information about the requester's client application, for use with string conditions (see String Conditions)

The key names are case insensitive. For example, aws:CurrentTime is equivalent to AWS:currenttime.

	Note
	If you use aws:SourceIp, and the request comes from an Amazon EC2 instance, we evaluate the instance's public IP address to determine if access is allowed.

Each AWS product that uses the access policy language might also provide product-specific keys. For a list of any product-specific keys you can use, see Integrating with Other AWS Products.

Condition Types

These are the general types of conditions you can specify:

• String

• Numeric

• Date and time

• Boolean

• IP address

String Conditions

String conditions let you constrain using string matching rules. The actual data type you use is a string.

Condition	Description
StringEquals	Strict matching Short version: streq
StringNotEquals	Strict negated matching Short version: strneq
StringEqualsIgnoreCase	Strict matching, ignoring case Short version: streqi
StringNotEqualsIgnoreCase	Strict negated matching, ignoring case Short version: strneqi
StringLike	Loose case-sensitive matching. The values can include a multi-character match wildcard (*) or a single-character match wildcard (?) anywhere in the string. Short version: strl
StringNotLike	Negated loose case-insensitive matching. The values can include a multi-character match wildcard (*) or a single-character match wildcard (?) anywhere in the string. Short version: strnl

For example, the following statement uses the StringEquals condition with the aws:UserAgent key to specify that the request must have a specific user agent.

{
   "Statement":[{
      "Effect":"Allow",
      "Action":"iam:*AccessKey*",
      "Resource":"arn:aws:iam::123456789012:user/*",
      "Condition":{
         "StringEquals":{
            "aws:UserAgent":"Example Corp Java Client"
            }
         }
      }
   ]
}

Numeric Conditions

Numeric conditions let you constrain using numeric matching rules. You can use both whole integers or decimal numbers. Fractional or irrational syntax is not supported.

Condition	Description
NumericEquals	Strict matching Short version: numeq
NumericNotEquals	Strict negated matching Short version: numneq
NumericLessThan	"Less than" matching Short version: numlt
NumericLessThanEquals	"Less than or equals" matching Short version: numlteq
NumericGreaterThan	"Greater than" matching Short version: numgt
NumericGreaterThanEquals	"Greater than or equals" matching Short version: numgteq

For example, the following statement uses the NumericLessThanEquals condition with the s3:max-keys policy key to specify that the requester can list up to 10 objects in example_bucket at a time.

{
   "Statement":[{
      "Effect":"Allow",
      "Action":"s3:ListBucket",
      "Resource":"arn:aws:s3:::example_bucket",
      "Condition":{
         "NumericLessThanEquals":{
            "s3:max-keys":"10"
            }
         }
      }
   ]
}

Date Conditions

Date conditions let you constrain using date and time matching rules. You must specify all date/time values with one of the W3C implementations of the ISO 8601 date formats (for more information, go to http://www.w3.org/TR/NOTE-datetime), or in epoch (UNIX) time. You use these conditions with the aws:CurrentTime key to restrict access based on request time.

	Note
	Wildcards are not permitted for date conditions.

Condition	Description
DateEquals	Strict matching Short version: dateeq
DateNotEquals	Strict negated matching Short version: dateneq
DateLessThan	A point in time at which a key stops taking effect Short version: datelt
DateLessThanEquals	A point in time at which a key stops taking effect Short version: datelteq
DateGreaterThan	A point in time at which a key starts taking effect Short version: dategt
DateGreaterThanEquals	A point in time at which a key starts taking effect Short version: dategteq

For example, the following statement uses the DateLessThan condition with the aws:CurrentTime key to specify that the request must be received before June 30, 2010.

{
   "Statement":[{
      "Effect":"Allow",
      "Action":"iam:*AccessKey*",
      "Resource":"arn:aws:iam::123456789012:user/*",
      "Condition":{
         "DateLessThan":{
            "aws:CurrentTime":"2010-06-30T00:00:00Z"
            }
         }
      }
   ]
}

Boolean Conditions

Condition	Description
Bool	Strict Boolean matching

For example, the following statement uses the Bool condition with the aws:SecureTransport key to specify that the request must use SSL.

{
   "Statement":[{
      "Effect":"Allow",
      "Action":"iam:*AccessKey*",
      "Resource":"arn:aws:iam::123456789012:user/*",
      "Condition":{
         "Bool":{
            "aws:SecureTransport":"true"
            }
         }
      }
   ]
}

IP Address

IP address conditions let you constrain based on IP address matching rules. You use these with the aws:SourceIp key. The value must be in the standard CIDR format (for example, 10.52.176.0/24). For more information, go to RFC 4632.

Condition	Description
IpAddress	Approval based on the IP address or range
NotIpAddress	Denial based on the IP address or range

For example, the following statement uses the IpAddress condition with the aws:SourceIp key to specify that the request must come from the 192.168.176.0/24 IP address range.

{
   "Statement":[{
      "Effect":"Allow",
      "Action":"iam:*AccessKey*",
      "Resource":"arn:aws:iam::123456789012:user/*",
      "Condition":{
         "IpAddress":{
            "aws:SourceIp":"192.168.176.0/24"
            }
         }
     }
  ]
}