Element Descriptions

Topics

This section describes the elements you can use in a policy and its statements. The elements are listed here in the general order you use them in a policy. The Id, Version, and Statement are top-level policy elements; the rest are statement-level elements. JSON examples are provided.

All elements are optional for the purposes of parsing the policy document itself. The order of the elements doesn't matter (e.g., the Action element can come before the Principal element). Conditions are optional.

Version

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"

Id

The Id is an identifier for the policy. We recommend you use a UUID for the value, or incorporate a UUID as part of the ID to ensure uniqueness.

[Important]Important

The AWS service (e.g., SQS) implementing the access policy language might require this element and have uniqueness requirements for it. For service-specific information about writing policies, see Special Information for SQS Policies.

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

Statement

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":[{...},{...},{...}]

Sid

The Sid (statement ID) is an optional identifier you provide for the policy statement. Essentially it is just a sub-ID of the policy document's ID.

[Important]Important

The AWS service (e.g., SQS) implementing the access policy language might require this element and have uniqueness requirements for it. For service-specific information about writing policies, see Special Information for SQS Policies.

"Sid" : "1"

Effect

The Effect is an optional element that indicates whether you want the statement to result in an allow or a hard deny (for more information, see Hard Deny). If no Effect is present in the policy document, we assume a soft deny (for more information, see Soft Deny).

Valid values for Effect are Allow and Deny.

"Effect":"Allow"

Principal

The Principal is the person or persons who receive or are denied permission according to the policy. You must specify the principal by using the principal's AWS account ID (e.g., 1234-5678-9012, with or without the hyphens). You can specify multiple principals, or a wildcard (*) to indicate all possible users. You can view your account ID by logging in to your AWS account at http://aws.amazon.com and clicking Account Activity.

In JSON, you use "AWS": as a prefix for the principal's AWS account ID. In the following example, two principals are included in the statement.

"Principal":[
   "AWS": "123456789012",
   "AWS": "999999999999"
]

Action

The Action is the specific type or types of access allowed or denied (for example, read or write). You can specify multiple values for this element. The values are free-form but must match values the AWS service expects (for more information, see Special Information for SQS Policies). You can use a wildcard (*) to give the principal access to all the actions the specific AWS service lets you share with other developers. For example, Amazon SQS lets you share only a particular subset of all the possible SQS actions. So, using the wildcard doesn't give someone full control of the queue; it only gives access to that particular subset of actions.

"Action":["SQS:SendMessage","SQS:ReceiveMessage"]

Resource

The Resource is the object or objects the policy covers. The value can include a multi-character match wildcard (*) or a single-character match wildcard (?) anywhere in the string. The values are free-form, but must follow the format the AWS service (e.g., Amazon SQS) expects. For example, for Amazon SQS, you specify a queue in the following format: /<account ID of queue owner>/<queue name>. For example: /987654321012/queue1.

"Resource":"/987654321000/queue2"

Condition

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.

Condition block

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.

Condition block

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.

Condition block

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 a hard deny decision.

Condition block with AND/OR

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 (e.g., Amazon SQS) 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 SQS queue under the following three conditions:

  • The time is after 12:00 noon on 4/16/2009

  • The time is before 3:00 p.m. on 4/16/2009

  • 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 queue.

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" : ["10.52.176.0/24","192.168.143.0/24"]
      }
}

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.

ConditionDescription

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-insensitive 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

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.

ConditionDescription

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

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). You use these conditions with the AWS:CurrentTime key to restrict access based on request time.

[Note]Note

Wildcards are not permitted for date conditions.

ConditionDescription

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

Boolean Conditions

ConditionDescription

Bool

Strict Boolean matching

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. The /32 netmask is the default, so you can omit the slash if you want to specify an exact IP address match.

ConditionDescription

IpAddress

Whitelisting based on the IP address or range

NotIpAddress

Blacklisting based on the IP address or range

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)

  • AWS:SecureTransport (Boolean representing whether the request was sent using SSL)

  • AWS:SourceIp (the requester's IP address, for use with IP address conditions)

  • AWS:UserAgent (information about the requester's client application, for use with string conditions)

Each AWS service that uses the access policy language might also provide service-specific keys. For a list of any service-specific keys you can use, see Special Information for SQS Policies.