Elements

The Version element specifies the access policy language version. The only allowed values are these:

If you do not include a Version element, the value defaults to 2008-10-17. However, it is a good practice to always include a Version element and set it to 2012-10-17.

"Version":"2012-10-17"

The Id element specifies an optional identifier for the policy. The ID is used differently in different services.

For IAM policies, the service automatically sets the policy's Id value to the policy name that you create. If you attempt to set the Id element, the policy will rejected. The Id value for an IAM policy might look like the following example.

"Id":"Admin_Policy"

For services that let you set an ID element, we recommend you use a UUID (GUID) for the value, or incorporate a UUID as part of the ID to ensure uniqueness.

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

The Statement element is the main element for a policy. This element is required. It can include multiple elements (see the subsequent sections in this page). The Statement element contains an array of individual statements. Each individual statement is a JSON block enclosed in braces { }.

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

The following example shows a policy that contains an array of three statements inside a single Statement element. (The policy allows you to access your buckets in the Amazon S3 console.) The policy includes the aws:username variable, which is replaced during policy evaluation with the user name from the request. For more information, see Introduction.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "s3:ListAllMyBuckets"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Resource": "arn:aws:s3:::mybucket/home/${aws:username}/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::mybucket",
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "/${aws:username}/*"
          ]
        }
      }
    }
  ]
}

The Sid (statement ID) is an optional identifier that you provide for the policy statement. You can assign a Sid value to each statement in a statement array. In services that let you specify an ID element, such as SQS and SNS, the Sid value is just a sub-ID of the policy document's ID. In IAM, the Sid value must be unique within a policy.

"Sid":"1"

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

The Effect element is required and specifies whether you want the statement to result in an allow or an explicit deny. Valid values for Effect are Allow and Deny.

"Effect":"Allow"

By default, access to resources is denied. To allow access to a resource, you must set the Effect element to Allow. To override an allow (for example, to override an allow that is otherwise in force), you set the Effect element to Deny. For more information, see IAM Policy Evaluation Logic.

The Principal element specifies the user, account, service, or other entity that is allowed or denied access to a resource.

For IAM users and groups, you do not specify a principal; for those cases, the principal is the user or group that you are attaching the policy to. For IAM roles, principals are used to specify who can assume the role. In other services, principals are used in policies that are attached to a resource, such as an Amazon S3 bucket or an Amazon SQS queue.

You specify a principal using the Amazon Resource Name (ARN) of the account, IAM user, group, or role. For more information about the format of ARNs, see Amazon Resource Names (ARNs) and AWS Service Namespaces.

In IAM, you can use wildcards (*) to indicate all possible users. As a shortcut, if you're specifying an account ID, you can use a shortened form that consists of the AWS: prefix followed by the ID.

The following examples show various ways in which principals can be specified.

<!-- Everyone (anonymous users) -->
"Principal":"AWS":"*.*" 

<!-- Specific account or accounts -->
"Principal":{"AWS":"arn:aws:iam::123456789012:root" }
"Principal":{"AWS":"123456789012"}
"Principal":{"AWS":["arn:aws:iam::123456789012:root","arn:aws:iam::999999999999:root"]}  

<!-- Individual user -->
"Principal":"AWS":"arn:aws:iam::123456789012:user/Username"  
	
<!-- Specific role -->
"Principal":{"AWS":["arn:aws:iam::123456789012:role/MyRole"]}
	
<!-- Specific service -->
"Principal":{"Service":["ec2.amazonaws.com"]}

Some services support additional options for specifying a principal. For example, Amazon S3 lets you use a canonical user in a format like this:

<!-- Individual user in S3 -->
"Principal":{"CanonicalUser":"79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be"}

For more information, see the following:

The NotPrincipal element lets you specify an exception to a list of principals. For example, you can use this to prevent all AWS accounts except a specific account from accessing a resource. Conversely, you can deny access to all principals except the one named in the NotPrincipal element. As with Principal, you specify the user or account that should be allowed or denied permission; the difference is that NotPrincipal translates to everyone except that person or account.

In the following example, all users are denied access to a resource except for the user named Bob in the AWS account 123456789012.

"Effect": "Deny",
"NotPrincipal": {
    "AWS":"arn:aws:iam::123456789012:user/Bob"
}

The Action element describes the type of access that should be allowed or denied (for example, read, write, list, delete, and so on). Statements must include either an Action or NotAction element. Each AWS service has its own set of actions that describe tasks that you can perform with that service.

You specify a value using a namespace that identifies a service (iam, sqs, sns, s3, etc.) followed by the name of the action to allow or deny. The name must match an action that is supported by the service. The prefix and the action name are case insensitive. For example, iam:ListAccessKeys is the same as IAM:listaccesskeys. The following examples show Action elements for different services.

<!-- SQS action -->
"Action":"sqs:SendMessage"

<!-- EC2 action -->
"Action":"ec2:StartInstances"			
			
<!-- IAM action -->
"Action":"iam:ChangePassword"			
			
<!-- S3 action -->
"Action":"s3:GetObject"

You can specify multiple values for the Action element.

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

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 ?) as part of the action name. For example, the following Action element applies to all IAM actions that include the string AccessKey, including CreateAccessKey, DeleteAccessKey, ListAccessKeys, and UpdateAccessKey.

"Action":"iam:*AccessKey*"

Some services let you limit the actions that are available. For example, Amazon SQS lets you make available just a subset of all the possible Amazon SQS actions. In that case, the * wildcard doesn't allow complete control of the queue; it allows only the subset of actions that you've shared. For more information, see Understanding Permissions in the Amazon Simple Queue Service Developer Guide.

The NotAction element lets you specify an exception to a list of actions. For example, you can use NotAction to let users use only the Amazon SQS SendMessage action, without having to list all the actions that the user is not allowed to perform. Using NotAction can sometimes result in shorter policies than using an Action element and listing many actions.

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

"NotAction":"sqs:SendMessage"

The following example matches any action except Publish.

"NotAction":"sns:Publish"

The following example shows how to reference all Amazon S3 actions except GetObject.

"NotAction":"s3:GetObject"

For an example of how to use the NotAction element in a policy that controls access to an Amazon S3 bucket, see Example Policies for Amazon S3 in the Amazon Simple Storage Service Developer Guide.

The Resource element specifies the object or objects that the statement covers. Statements must include either a Resource or a NotResource element. You specify a resource using an ARN. (For more information about the format of ARNs, see Amazon Resource Names (ARNs) and AWS Service Namespaces.)

Each service has its own set of resources. Although you always use an ARN to specify a resource, the details of the ARN for a resource depend on the service and the resource. For information about how to specify a resource, refer to the documentation for the service whose resources you're writing a statement for.

The following example refers to a specific Amazon SQS queue.

"Resource":"arn:aws:sqs:us-west-2:111122223333:queue1"

The following example refers to the IAM user named Bob in an the AWS account 123456789012.

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

You can use wildcards as part of the resource ARN. The following example refers to all IAM users whose path is /accounting.

"Resource":"arn:aws:iam::123456789012:user/acounting/*"

The following example refers to all items within a specific Amazon S3 bucket.

"Resource":"arn:aws:s3:::my_corporate_bucket/*"

You can specify multiple resources. The following example refers to two Amazon DynamoDB tables.

"Resource":[
    "arn:aws:dynamodb:us-west-2:123456789012:table/books_table",
    "arn:aws:dynamodb:us-west-2:123456789012:table/maagazines_table"
]

In the Resource element, you can use policy variables in the part of the ARN that identifies the specific resource (that is, in the trailing part of the ARN). For example, you can use the key {aws:username} as part of a resource ARN to indicate that the current user's name should be included as part of the resource's name. The following example shows how you can use the {aws:username} key in a Resource element. The policy allows access to a Amazon DynamoDB table that matches the current user's name.

{
  "Version": "2012-10-17",
  "Statement": [{
      "Effect": "Allow",
      "Action": ["dynamodb:*"],
      "Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/${aws:username}"
    }
  ]
}

For more information about policy variables, see Policy Variables.

The NotResource element lets you grant or deny access to all but a few of your resources, by allowing you to specify only those resources to which your policy should not be applied.

For example, imagine you have a group named Developers. Members of Developers should have access to all of your Amazon S3 resources except the CompanySecretInfo folder in the mybucket bucket. The following examples shows what the policy to establish these permissions might look like.

{
	"Version": "2012-10-17",
	"Statement": [{
	  "Effect": "Allow",
	  "Action": ["s3:*"], 
	  "NotResource": ["arn:aws:s3:::mybucket/CompanySecretInfo", "arn:aws:s3:::mybucket/CompanySecretInfo/*"]
	}]
}

Normally you would write a policy that uses "Effect":"Allow" and that includes a Resources element that lists each folder individually that the Developers group has access to. However, in that case, each time you added a folder to mybucket that users should have access to, you would have to add its name to the list in Resource. If you use a NotResource element instead, users will automatically have access to new folders unless you add the folder names to the NotResource element.

The Condition element lets you specify conditions for when a policy is in effect. The Condition element is optional. In the Condition element, you build expressions in which you use Boolean operators (equal, less than, etc.) to match your condition against values in the request. Condition values can include date, time, the IP address of the requester, the ARN of the request source, the user name, user ID, and the user agent of the requester. Some services also let you additional values in conditions; for example, Amazon S3 lets you write a condition using the s3:VersionId key, which is unique to that service. (For more information about writing conditions in policies for Amazon S3, see Using IAM Policies in the Amazon Simple Storage Service Developer Guide.)

The Condition Block

A Condition element, or condition block, can contain multiple conditions, and each condition can contain multiple key-value pairs. The following figure illustrates this. Unless otherwise specified, all keys can have multiple values.

An example of a condition is NumericEquals. Let's say you want to let John use a resource only if a numeric value foo equals either A or B, and another numeric value bar equals C. 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. You would add another condition, DateGreaterThan, with a date equal to January 1, 2009. The condition block would then look like the following figure.

If there are multiple conditions, or if there are multiple keys in a single condition, the conditions are evaluated using a logical AND. If a single condition includes multiple values for one key, the condition is evaluated using a logical OR. All conditions must be met for an allow or an explicit deny decision. If a condition isn't met, the result is a deny.

As noted, AWS has predefined conditions and keys (like aws:CurrentTime). Individual AWS services also define service-specific keys.

As an example, let's say you want to let user John access your Amazon SQS queue under the following conditions:

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

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

• The request (IAM or SQS) or message (SNS) comes from an IP address within the range 192.0.2.0 to 192.0.2.255 or 203.0.113.0 to 203.0.113.255.

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

The following shows what the condition block looks like in your policy. The two values for aws:SourceIp are evaluated using OR. The three separate conditions are evaluated using AND.

"Condition" :  {
      "DateGreaterThan" : {
         "aws:CurrentTime" : "2013-08-16T12:00:00Z"
       },
      "DateLessThan": {
         "aws:CurrentTime" : "2013-08-16T15:00:00Z"
       },
       "IpAddress" : {
          "aws:SourceIp" : ["192.0.2.0/24", "203.0.113.0/24"]
      }
}

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

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "s3:ListAllMyBuckets",
        "s3:GetBucketLocation"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::*"
      ]
    },
    {
      "Action": [
        "s3:ListBucket"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::myBucket"
      ],
      "Condition": {
        "StringEquals": {
          "s3:prefix": [
            "",
            "home/"
          ],
          "s3:delimiter": [
            "/"
          ]
        }
      }
    },
    {
      "Action": [
        "s3:ListBucket"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::myBucket"
      ],
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "home/${aws:username}/*"
          ]
        }
      }
    },
    {
      "Action": [
        "s3:*"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::myBucket/home/${aws:username}",
        "arn:aws:s3:::myBucket/home/${aws:username}/*"
      ]
    }
  ]
}

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

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

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

{
  "Version": "2012-10-17",
  "Statement":[{
    "Effect":"Allow",
    "Action":"iam:*AccessKey*",
    "Resource":"arn:aws:iam::123456789012:user/*",
    "Condition":{
      "IpAddress":{
         "aws:SourceIp":"203.0.113.0/24"
      }
    }
  }]
}

{
  "Version": "2008-10-17",
  "Id": "arn:aws:sqs:us-west-2:123456789012:user_queue1/SQSDefaultPolicy",
  "Statement": [
    {
      "Sid": "Sid1234567890123",
      "Effect": "Allow",
      "Principal": {
        "AWS": "123456789012"
      },
      "Action": ["SQS:SendMessage"],
      "Resource": "arn:aws:sqs:us-west-2:336924118301:your_queue_1",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "arn:aws:sns:us-east-1:123456789012:your_topic_1"
        }
      }
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement":[{
      "Action":["ec2:*"],
      "Effect":"Allow",
      "Resource":["*"],
      "Condition":{
         "Null":{"aws:MultiFactorAuthAge":"false"}
      }
    }
  ]
}

This section lists the set of data types the access policy language supports. The language doesn't support all types for each policy element; for information about each element, see the preceding sections.

The following table maps each data type to the serialization. Note that all policies must be in UTF-8. For information about the JSON data types, go to RFC 4627.