Actions

AWS/IAM Policy

From Ever changing code

< AWS

AWS policies, in my own words..

resource policy
attached to a resource directly, evaluate whether a user can access/denied to the resource
capability policies
(IAM docs refer to user-based permissions) also known 'user policy or group policies' defines what actions a user/group/role is allowed or denied. These policies can override 'resource policies' by explicitly deny actions
IAM policies
eg. can restrict access to IP range, based on day and time

IAM Policy Elements Reference

This section describes the elements that you can use in an IAM policy. The elements are listed here in the general order you use them in a policy. The order of the elements doesn't matter—for example, the Resource element can come before the Action element. You're not required to specify any Condition elements in the policy.

Note

The details of what goes into a policy vary for each service, depending on what actions the service makes available, what types of resources it contains, and so on. When you're writing policies for a specific service, it's helpful to see examples of policies for that service. For a list of all the services that support IAM, and for links to the documentation in those services that discusses IAM and policies, see AWS Services That Support IAM.

Version

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

2012-10-17. This is the current version of the policy language, and you should use this version number for all policies.

2008-10-17. This was an earlier version of the policy language. You might see this version on existing policies. Do not use this version for any new policies or any existing policies that you are updating.

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.

Note

If your policy includes policy variables, you must include a Version element and set it to 2012-10-17. If you don't include a Version element set to 2012-10-17, variables such as ${aws:username} won't be recognized as variables and will instead be treated as literal strings in the policy.

"Version":"2012-10-17"

Id

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"

Note

Some AWS services (for example, Amazon SQS or Amazon SNS) might require this element and have uniqueness requirements for it. For service-specific information about writing policies, refer to the documentation for the service you're working with.

Statement

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 own "home folder" 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": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListAllMyBuckets",
        "s3:GetBucketLocation"
      ],
      "Resource": ["arn:aws:s3:::*"]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": ["arn:aws:s3:::BUCKET-NAME"],
      "Condition": {"StringLike": {"s3:prefix": [
        "",
        "home/",
        "home/${aws:username}/"
      ]}}
    },
    {
      "Effect": "Allow",
      "Action": ["s3:*"],
      "Resource": [
        "arn:aws:s3:::BUCKET-NAME/home/${aws:username}",
        "arn:aws:s3:::BUCKET-NAME/home/${aws:username}/*"
      ]
    }
  ]
}

Sid

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.

Note

Some AWS services (for example, Amazon SQS or Amazon SNS) might require this element and have uniqueness requirements for it. For service-specific information about writing policies, refer to the documentation for the service you're working with.

Effect

The Effect element is required and specifies whether the statement will 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.

Principal

The Principal element specifies the user, account, service, or other entity that is allowed or denied access to a resource. The Principal element is used in the trust policies for IAM roles and in resource-based policies—that is, in policies that can be attached directly to a resource, such as an Amazon S3 bucket or an Amazon SQS queue. The principal is used in these ways:

  • In IAM roles, principals are used in the role's trust policy to specify who can assume the role. For cross-account access, the principal is typically the identifier of the trusted account.
  • In resource-based services, the principal specifies the accounts or users who are allowed to access the resource.

The Principal element is not used in policies that you attach to IAM users and groups. Similarly, in the access policy for an IAM role, you do not specify a principal. In those cases, the principal is implicitly the user that the policy is attached to (for IAM users) or the user who assumes the role (for role access policies). If the policy is attached to an IAM group, the principal is the member of the group who is making the request.

Specifying a Principal

You specify a principal using the Amazon Resource Name (ARN) of the account, IAM user, or role. (IAM groups cannot be specified as principals.) For more information about the format of ARNs, see Amazon Resource Names (ARNs) and AWS Service Namespaces. 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

Using an account identifier as the principal in a policy means that the policy's permissions apply to all requests that come from that account, including from individual users in that account. The following examples demonstrate different ways to specify an account as principal.

"Principal":{"AWS":"arn:aws:iam::''<code>account-number-without-hyphens</code>'':root"}

"Principal":{"AWS":"''<code>account-number-without-hyphens</code>''"}

Note

When you are specifying an account as the principal, the keyword root in an ARN means the account. It does not mean that the principal can only be a user who is making requests using the root credentials for an account.

You can specify more than one account as a principal, as shown in the following example.

"Principal":{"AWS":["arn:aws:iam::''<code>account-number-without-hyphens</code>'':root","arn:aws:iam::''<code>account-number-without-hyphens</code>'':root"]}

Individual IAM user or users

You can specify an individual IAM user (or array of users) as the principal.

Note

In a Principal element, the user name is case sensitive.

"Principal":{"AWS":"arn:aws:iam::''<code>account-number-without-hyphens</code>'':user/''<code>username</code>''"}

"Principal": [
    "arn:aws:iam::''<code>account-number-without-hyphens</code>'':user/''<code>username1</code>''", 
    "arn:aws:iam::''<code>account-number-without-hyphens</code>'':user/''<code>username2</code>''"
]

If you are specifying users in a Principal element, you cannot use a wildcard (*) to mean "all users". Principals must always evaluate to a specific user or users. The following ARN is not allowed as a principal:

arn:aws:iam::<code>account-number-without-hyphens:user/*</code>

Federated user (using web identity federation)

"Principal":{"Federated":"www.amazon.com"}
"Principal":{"Federated":"graph.facebook.com"}
"Principal":{"Federated":"accounts.google.com"}

Federated user (using SAML-based provider)

"Principal":{"Federated":"arn:aws:iam::''<code>account-number-without-hyphens</code>'':saml-provider/''<code>providername</code>''"}

Specific role

"Principal":{"AWS":"arn:aws:iam::''<code>account-number-without-hyphens</code>'':role/''<code>rolename</code>''"}

AWS service

If you are creating a trust policy for an IAM role that will be assumed by another AWS service, the Principal element can be a service, as in the following example:

"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:

"Principal":{"CanonicalUser":"79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be"}

More Information

For more information, see the following:

NotPrincipal

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"
}

Action

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.

</div>

NotAction

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.

Resource

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.

Note

Some services do not let you specify actions for individual resources; instead, any actions that you list in the Action or NotAction element apply to all resources in that service. In these cases, you use the wildcard * in the Resource element.

The following example refers to a specific Amazon SQS queue.

"Resource":"arn:aws:sqs:us-west-2:''<code>account-number-without-hyphens</code>'':queue1"

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

"Resource":"arn:aws:iam::''<code>account-number-without-hyphens</code>'':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::''<code>account-number-without-hyphens</code>'':user/accounting/*"

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 DynamoDB tables.

"Resource":[
    "arn:aws:dynamodb:us-west-2:''<code>account-number-without-hyphens</code>'':table/books_table",
    "arn:aws:dynamodb:us-west-2:''<code>account-number-without-hyphens</code>'':table/magazines_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:ACCOUNT-ID-WITHOUT-HYPHENS:table/${aws:username}"
  }]
}

For more information about policy variables, see IAM Policy Variables Overview.

NotResource

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 example 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.

Condition

The Condition element (or Condition block) 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 let you specify 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

The following example shows the basic format of a Condition element:

"Condition": {
  "DateGreaterThan" : {
     "aws:CurrentTime" : "2013-12-15T12:00:00Z"
   }
}

A value from the request is represented by a key, in this case aws:CurrentTime. The key value is compared to a value that you specify either as a literal value (2013-08-16T12:00:00Z) or as a policy variable, as explained later. The type of comparison to make is specified by the condition (here, DateGreaterThan). You can create string conditions, date conditions, numeric conditions, and so on, and you can use typical Boolean comparisons like equals, greater than, and less than.

Under some circumstances, keys can contains multiple values. For example, a request to DynamoDB might ask to return or update multiple attributes from a table. A policy for access to DynamoDB tables can include the dynamodb:Attributes key, which contains all the attributes listed in the request. You can test the multiple attributes in the request against a list of allowed attributes in a policy by using set operators in a condition. For more information, see Creating a Condition That Tests Multiple Key Values (Set Operations).

When the policy is evaluated during a request, AWS replaces the key with the corresponding value from the request. (In this example, AWS would use the date and time of the request.) The condition is evaluated to return true or false, which is then factored into whether the policy as a whole allows or denies the request.

Multiple Values in a Condition

A Condition element 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.

http://docs.aws.amazon.com/IAM/latest/UserGuide/images/AccessPolicyLanguage_Condition_Block.gif

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"]
      }
}

Finally, under some circumstances, individual keys in a policy can contain multiple values, and you can use set operators to test these multi-valued keys against one or more values listed in the policy. For more information, see Creating a Condition That Tests Multiple Key Values (Set Operations).

Available Keys for Conditions

Keys in a condition represent values that are part of the request sent by a user. AWS provides the following predefined keys for all AWS services that support IAM for access control:

  • aws:CurrentTime—To check for date/time conditions (see Date Conditions).
  • aws:EpochTime—To check for date/time conditions using a date in epoch or UNIX time (see Date Conditions).
  • aws:principaltype—To check the type of principal (user, account, federated user, etc.) for the current request (see String Conditions).
  • aws:SecureTransport—To check whether the request was sent using SSL (see Boolean Conditions).
  • aws:SourceArn—To check the source of the request, using the Amazon Resource Name (ARN) of the source. (This value is available for only some services. For more information, see Amazon Resource Name (ARN) under "Element Descriptions" in the Amazon Simple Queue Service Developer Guide.)
  • aws:SourceIp—To check the requester's IP address (see IP Address ).
  • aws:UserAgent—To check the requester's client application (see String Conditions).

Note

Key names are case sensitive.

Some AWS services also provide service-specific keys. For example, for information about keys that you can use in policies for Amazon S3 resources, see Amazon S3 Policy Keys in the Amazon Simple Storage Service Developer Guide. For keys that are available in other services, see the documentation for the individual services.

Available Keys for Web Identity Federation

If you are using web identity federation to give temporary security credentials to users who have been authenticated using an identity provider (IdP) such as Amazon, Google, or Facebook, additional condition keys are available when the temporary security credentials are used to make a request. These keys let you write policies that make sure that federated users can get access only to resources that are specific to a specific registered app and to a specific federated user.

Federated Provider

The aws:FederatedProvider key identifies which of the IdPs was used to authenticate the user. For example, if the user authenticated using Login with Amazon, the key would contain the value www.amazon.com. You might use the key in a resource policy like the following, which uses the aws:FederatedProvider key as a policy variable in the ARN of a resource. The policy allows any user who has been authenticated using an IdP to get objects out of a folder in an Amazon S3 bucket that's specific to their IdP.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": ["*"],
    "Action": ["s3:GetObject"],
    "Resource": ["arn:aws:s3:::BUCKET-NAME/${aws:FederatedProvider}/*"]
  }]
}

Application ID and User ID

You can also use two keys that provide a unique identifier for the user and an identifier for the application or site that the user authenticated with. These keys have the following IdP-specific names:

For Login With Amazon users, the keys are www.amazon.com:app_id and www.amazon.com:user_id

For Facebook users, the keys are graph.facebook.com:app_id and graph.facebook.com:id

For Google users, the keys are accounts.google.com:aud (for the app ID) and accounts.google.com:sub (for the user ID).

For more information about web identity federation, see Creating Temporary Security Credentials for Mobile Apps Using Third-Party Identity Providers.

Available Keys for SAML-Based Federation

If you are working with SAML-based federation, you can include additional condition keys in the policy.

Trust Policies

In the trust policy of a role, you can include the following keys, which help you establish whether the caller is allowed to assume the role. Except for saml:doc, all the values are derived from the SAML assertion. Items in the list that are marked with an asterisk (*) are available in the console UI to create conditions.

  • saml:aud (URL). An endpoint to which SAML assertions are presented.
  • saml:cn (list). This is an eduOrg attribute.
  • saml:doc (string).* This represents the principal that was used to assume the role. The format is account-ID/document-friendly-name, such as 123456789012/Metadata_Document. The account-ID value refers to the account that owns the SAML provider.
  • saml:edupersonaffiliation (list). This is an eduPerson attribute.
  • saml:edupersonassurance (list). This is an eduPerson attribute.
  • saml:edupersonentitlement (list).* This is an eduPerson attribute.
  • saml:edupersonnickname (list). This is an eduPerson attribute.
  • saml:edupersonorgdn (string).* This is an eduPerson attribute.
  • saml:edupersonorgunitdn (list). This is an eduPerson attribute.
  • saml:edupersonprimaryaffiliation (string). This is an eduPerson attribute.
  • saml:edupersonprimaryorgunitdn (string). This is an eduPerson attribute.
  • saml:edupersonprincipalname (string). This is an eduPerson attribute.
  • saml:edupersonscopedaffiliation (list). This is an eduPerson attribute.
  • saml:edupersontargetedid (list). This is an eduPerson attribute.
  • saml:eduorghomepageuri (list). This is an eduOrg attribute.
  • saml:eduorgidentityauthnpolicyuri (list). This is an eduOrg attribute.
  • saml:eduorglegalname (list). This is an eduOrg attribute.
  • saml:eduorgsuperioruri (list). This is an eduOrg attribute.
  • saml:eduorgwhitepagesuri (list). This is an eduOrg attribute.
  • saml:iss (string).* The issuer, which is represented by a URN.
  • saml:sub (string).* This is the subject of the claim, which includes a value that uniquely identifies an individual user within an organization (for example, _cbb88bf52c2510eabe00c1642d4643f41430fe25e3).
  • saml:sub_type (string).* This key can be "persistent" or "transient". A value of "persistent" indicates that the value in saml:sub is the same for a user between sessions. If the value is "transient", the user has a different saml:sub value for each session.

For general information about eduPerson and eduOrg attributes, see the Internet2 website. For a list of eduPerson attributes, see eduPerson Object Class Specification (201203).

Keys whose type is a list can include multiple values. To create conditions in the policy for list values, you can use set operators (ForAllValues, ForAnyValue). For example, to allow any user whose affiliation is "faculty", "staff", or "employee" (but not "student", "alum", or other possible affiliations), you might use a condition like the following:

"Condition": {
   "ForAllValues:StringLike":{
	   "saml:edupersonaffiliation":["faculty","staff","employee"]}
   }
}

Access (Permissions) Policies

In the access policy of a role for SAML federation that defines what users are allowed to access in AWS, you can include the following keys:

saml:namequalifier. This contains a hash value that represents the combination of the saml:doc and saml:iss values. It is used as a namespace qualifier; the combination of saml:namequalifier and saml:sub uniquely identifies a user.

saml:sub. As described in the previous list.

saml:sub_type. As described in the previous list.

For more information about using these keys, see Creating Temporary Security Credentials for SAML Federation in the Using Temporary Security Credentials guide.

Condition Types

These are the types of conditions you can specify:

  • String
  • Numeric
  • Date and time
  • Boolean
  • Binary
  • IP address
  • Amazon Resource Name (ARN). (This value is available for only some services.)
  • ...IfExists
  • Existence of condition keys

String Conditions

String conditions let you restrict access based on comparing a key to a string value.

Condition Description

StringEquals

Exact matching, case sensitive

Short version: streq

StringNotEquals

Negated matching

Short version: strneq

StringEqualsIgnoreCase

Exact matching, ignoring case

Short version: streqi

StringNotEqualsIgnoreCase

Negated matching, ignoring case

Short version: strneqi

StringLike

Case-sensitive matching. The values can include a multi-character match wildcard (*) or a single-character match wildcard (?) anywhere in the string.

Note

If a key contains multiple values, StringLike can be qualified with set operators—ForAllValues:StringLike and ForAnyValues:StringLike. For more information, see Creating a Condition That Tests Multiple Key Values (Set Operations).

Short version: strl

StringNotLike

Negated case-sensitive 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 include a specific value in its user agent header.

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

The following example uses string matching with a policy variable to create a policy that lets an IAM user use the Amazon S3 console to manage his or her own "home directory" in an Amazon S3 bucket.

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

For an example of a policy that shows how to use the Condition element to restrict access to resources based on an application ID and a user ID for web federation identity, see Allow Users Signed In Using Login with Amazon to Access their Own Amazon S3 Folder.

Numeric Conditions

Numeric conditions let you restrict access based on comparing a key to an integer or decimal value.

Condition Description

NumericEquals

Matching

Short version: numeq

NumericNotEquals

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 key to specify that the requester can list up to 10 objects in example_bucket at a time.

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

Date Conditions

Date conditions let you restrict access based on comparing a key to a date/time value. You use these conditions with the aws:CurrentTime key or aws:EpochTime keys. You must specify date/time values with one of the W3C implementations of the ISO 8601 date formats or in epoch (UNIX) time.

Note

Wildcards are not permitted for date conditions.

Condition Description

DateEquals

Matching a specific date

Short version: dateeq

DateNotEquals

Negated matching

Short version: dateneq

DateLessThan

Matching before a specific date and time

Short version: datelt

DateLessThanEquals

Matching at or before a specific date and time

Short version: datelteq

DateGreaterThan

Matching after a specific a date and time

Short version: dategt

DateGreaterThanEquals

Matching at or after a specific date and time

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, 2013.

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

Boolean Conditions

Boolean conditions let you restrict access based on comparing a key to "true" or "false."

Condition Description

Bool

Boolean matching

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

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

Binary Comparison

The BinaryEquals condition can be useful for testing key values that are in binary format. It compares the value of the specified key byte for byte to a value in the policy that uses base-64 to represent the binary value.

"Condition" : {
  "BinaryEquals": {
    "''<code>key</code>''" : "QmluYXJ5VmFsdWVJbkJhc2U2NA=="
  }
}			

IP Address

IP address conditions let you restrict access based on comparing a key to an IP address or range of IP addresses. You use these with the aws:SourceIp key. The value must be in the standard CIDR format (for example, 203.0.113.0/24). For more information, see RFC 4632.

Condition Description

IpAddress

The specified IP address or range

NotIpAddress

All IP addresses except the specified 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 IP range 203.0.113.0 to 203.0.113.255.

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

The aws:SourceIp condition key resolves to the IP address that the request originates from. If the requests originates from an Amazon EC2 instance, aws:SourceIp evaluates to the instance's public IP address. If the request originates from an AWS service that makes calls to AWS, like Amazon Elastic MapReduce, AWS Elastic Beanstalk, and AWS CloudFormation, aws:SourceIp resolves to the IP address of that service. For these types of services, we recommend that you don’t use the aws:SourceIp condition.

Amazon Resource Name (ARN)

Amazon Resource Name (ARN) conditions let you restrict access based on comparing a key to an ARN. The ARN is considered a string. This value is available for only some services; not all services support request values that can be compared as ARNs.

Condition Description

ArnEquals

Matching for ARN

ArnNotEquals

Negated matching for ARN

ArnLike

Case-insensitive matching of the ARN. Each of the six colon-delimited components of the ARN is checked separately and each can include a multi-character match wildcard (*) or a single-character match wildcard (?).

ArnNotLike

Negated case-insensitive matching of the ARN. The values can include a multi-character match wildcard (*) or a single-character match wildcard (?) anywhere in the string.

The following example shows a policy you need to attach to any queue that you want Amazon SNS to send messages to. It gives Amazon SNS permission to send messages to the queue (or queues) of your choice, but only if the service is sending the messages on behalf of a particular Amazon SNS topic (or topics). You specify the queue in the Resource field, and the Amazon SNS topic as the value for the SourceArn key.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"AWS": "ACCOUNT-ID-WITHOUT-HYPHENS"},
    "Action": ["SQS:SendMessage"],
    "Resource": "arn:aws:sqs:REGION:ACCOUNT-ID-WITHOUT-HYPHENS:QUEUE-ID",
    "Condition": {"ArnEquals": {"aws:SourceArn": "arn:aws:sns:REGION:ACCOUNT-ID-WITHOUT-HYPHENS:TOPIC-ID"}}
  }]
}

...IfExists Conditions

You can add IfExists at the end of any condition except the Null condition—for example, StringEqualsIfExists. You do this if you mean "If the policy key is present in the context of the request, process the key as specified in the policy. If the key is not present, I don't care."

Existence of Condition Keys

Use a Null condition to check if a condition key is present at the time of authorization. In the policy statement, use either true (the key doesn't exist) or false (the key exists and its value is not null).

For example, you can use this condition to determine whether a user has authenticated with MFA (multi-factor authentication). The following example shows a condition that states that MFA authentication must exist (be not null) for the user to use the Amazon EC2 API.

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

Supported Data Types

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

  • Strings
  • Numbers (Ints and Floats)
  • Boolean
  • Null
  • Lists
  • Maps
  • Structs (which are just nested Maps)

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.

Type JSON

String

String

Integer

Number

Float

Number

Boolean

true false

Null

null

Date

String adhering to the W3C Profile of ISO 8601

IpAddress

String adhering to RFC 4632

List

Array

Object

Object

References