Menu
Amazon Simple Storage Service
Developer Guide (API Version 2006-03-01)

Specifying Conditions in a Policy

The access policy language allows you to specify conditions when granting permissions. The Condition  element (or  Condition block) lets you specify conditions for when a policy is in effect. In the Condition element, which is optional, you build expressions in which you use Boolean operators (equal, less than, etc.) to match your condition against values in the request. For example, when granting a user permission to upload an object, the bucket owner can require the object be publicly readable by adding the StringEquals condition as shown here:

Copy to clipboard
{ "Version": "2012-10-17", "Statement": [ { "Sid": "statement1", "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": [ "arn:aws:s3:::examplebucket/*" ], "Condition": { "StringEquals": { "s3:x-amz-acl": [ "public-read" ] } } } ] }

The Condition block specifies the StringEquals condition that is applied to the specified key-value pair, "s3:x-amz-acl":["public-read"]. There is a set of predefined keys you can use in expressing a condition. The example uses the s3:x-amz-acl condition key. This condition requires user to include the x-amz-acl header with value public-read in every PUT object request.

For more information about specifying conditions in an access policy language, see Condition in the IAM User Guide.

The following topics describe AWS-wide and Amazon S3–specific condition keys and provide example policies.

Available Condition Keys

The predefined keys available for specifying conditions in an Amazon S3 access policy can be classified as follows:

  • AWS-wide keys – AWS provides a set of common keys that are supported by all AWS services that support policies. These keys that are common to all services are called AWS-wide keys and use the prefix aws:. For a list of AWS-wide keys, see Available Keys for Conditions in the IAM User Guide. There are also keys that are specific to Amazon S3, which use the prefix s3:. Amazon S3–specific keys are discussed in the next bulleted item.

     

    The new condition keys aws:sourceVpce and aws:sourceVpc are used in bucket policies for VPC endpoints. For examples of using these condition keys, see Example Bucket Policies for VPC Endpoints for Amazon S3.

    The following example bucket policy allows authenticated users permission to use the s3:GetObject action if the request originates from a specific range of IP addresses (192.168.143.*), unless the IP address is 192.168.143.188. In the condition block, the IpAddress and the NotIpAddress are conditions, and each condition is provided a key-value pair for evaluation. Both the key-value pairs in this example use the aws:SourceIp AWS-wide key.

    Note

    The IPAddress and NotIpAddress key values specified in the condition uses CIDR notation as described in RFC 4632. For more information, go to http://www.rfc-editor.org/rfc/rfc4632.txt.

    Copy to clipboard
    { "Version": "2012-10-17", "Id": "S3PolicyId1", "Statement": [ { "Sid": "statement1", "Effect": "Allow", "Principal": "*", "Action":["s3:GetObject"] , "Resource": "arn:aws:s3:::examplebucket/*", "Condition" : { "IpAddress" : { "aws:SourceIp": "192.168.143.0/24" }, "NotIpAddress" : { "aws:SourceIp": "192.168.143.188/32" } } } ] }
  • Amazon S3–specific keys – In addition to the AWS-wide keys the following are the condition keys that are applicable only in the context of granting Amazon S3 specific permissions. These Amazon S3–specific keys use the prefix s3:.

    • s3:x-amz-acl

    • s3:x-amz-copy-source

    • s3:x-amz-metadata-directive

    • s3:x-amz-server-side-encryption

    • s3:VersionId

    • s3:LocationConstraint

    • s3:delimiter

    • s3:max-keys

    • s3:prefix

    • s3:x-amz-server-side-encryption-aws-kms-key-id

    • s3:ExistingObjectTag/<tag-key>

      For example policies using object tags related condition keys, see Object Tagging and Access Control Policies.

    • s3:RequestObjectTagKeys

    • s3:RequestObjectTag/<tag-key>

     

    For example, the following bucket policy allows the s3:PutObject permission for two AWS accounts if the request includes the x-amz-acl header making the object publicly readable.

    Copy to clipboard
    { "Version":"2012-10-17", "Statement": [ { "Sid":"AddCannedAcl", "Effect":"Allow", "Principal": { "AWS": ["arn:aws:iam::account1-ID:root","arn:aws:iam::account2-ID:root"] }, "Action":["s3:PutObject"], "Resource": ["arn:aws:s3:::examplebucket/*"], "Condition": { "StringEquals": { "s3:x-amz-acl":["public-read"] } } } ] }

    The Condition block uses the StringEquals condition and it is provided a key-value pair, "s3:x-amz-acl":["public-read", for evaluation. In the key-value pair, the s3:x-amz-acl is an Amazon S3–specific key, as indicated by the prefix s3:.

Important

Not all conditions make sense for all actions. For example, it makes sense to include an s3:LocationConstraint condition on a policy that grants the s3:CreateBucket Amazon S3 permission, but not for the s3:GetObject permission. Amazon S3 can test for semantic errors of this type that involve Amazon S3–specific conditions. However, if you are creating a policy for an IAM user and you include a semantically invalid Amazon S3 condition, no error is reported, because IAM cannot validate Amazon S3 conditions.

The following section describes the condition keys that can be used to grant conditional permission for bucket and object operations. In addition, there are condition keys related to Amazon S3 Signature Version 4 authentication. For more information, go to Amazon S3 Signature Version 4 Authentication Specific Policy Keys in the Amazon Simple Storage Service API Reference.

Amazon S3 Condition Keys for Object Operations

The following table shows which Amazon S3 conditions you can use with which Amazon S3 actions. Example policies are provided following the table. Note the following about the Amazon S3–specific condition keys described in the following table:

  • The condition key names are preceded by the prefix s3:. For example, s3:x-amz-acl.

  • Each condition key maps to the same name request header allowed by the API on which the condition can be set. That is, these condition keys dictate behavior of the same name request headers. For example:

    • The condition key s3:x-amz-acl that you can use to grant condition permission for the s3:PutObject permission defines behavior of the x-amz-acl request header that the PUT Object API supports.

    • The condition key s3:VersionId that you can use to grant conditional permission for the s3:GetObjectVersion permission defines behavior of the versionId query parameter that you set in a GET Object request.

Permission Applicable Condition Keys (or keywords) Description

s3:PutObject

  • s3:x-amz-acl (for canned ACL permissions)

  • s3:x-amz-grant-permission (for explicit permissions), where permission can be:

    read, write,​ read-acp,​ write​-acp,​ ​full​-control

The PUT Object operation allows access control list (ACL)–specific headers that you can use to grant ACL-based permissions. Using these keys, the bucket owner can set a condition to require specific access permissions when the user uploads an object.

For an example policy, see Example 1: Granting s3:PutObject permission with a condition requiring the bucket owner to get full control.

For more information about ACLs, see Access Control List (ACL) Overview.

s3:x-amz-copy-source

To copy an object you use the PUT Object API (see PUT Object) and specify the source using the x-amz-copy-source header. Using this key, the bucket owner can restrict the copy source to a specific bucket, a specific folder in the bucket, or a specific object in a bucket.

For a policy example, see Example 3: Granting s3:PutObject permission to copy objects with a restriction on the copy source.

s3:x-amz-server-side-encryption

When you upload an object, you can use the x-amz-server-side-encryption header to request Amazon S3 to encrypt the object when it is saved, using an envelope encryption key managed either by AWS Key Management Service (KMS) or by Amazon S3 (see Protecting Data Using Server-Side Encryption).

When granting the s3:PutObject permission, the bucket owner can add a condition using this key to require the user to specify this header in the request. A bucket owner can grant such conditional permission to ensure that objects the user uploads are encrypted when they are saved.

For a policy example, see Example 1: Granting s3:PutObject permission with a condition requiring the bucket owner to get full control.

s3:x-amz-server-side-encryption-aws-kms-key-id

When you upload an object, you can use the x-amz-server-side-encryption-aws-kms-key-id header to request Amazon S3 to encrypt the object using the specified AWS KMS key when it is saved (see Protecting Data Using Server-Side Encryption with AWS KMS–Managed Keys (SSE-KMS)).

When granting the s3:PutObject permission, the bucket owner can add a condition using this key to restrict the AWS KMS key ID used for object encryption to a specific value.

A bucket owner can grant such conditional permission to ensure that objects the user uploads are encrypted with a specific key when they are saved.

The KMS key you specify in the policy must use the following format:

arn:aws:kms:region:acct-id:key/key-id

s3:x-amz-metadata-directive

When you copy an object using the PUT Object API (see PUT Object) you can optionally add the x-amz-metadata-directive header to specify whether you want the object metadata copied from the source object or replaced with metadata provided in the request.

Using this key bucket, an owner can add a condition to enforce certain behavior when objects are uploaded.

Valid values: COPY | REPLACE. The default is COPY.

s3:x-amz-storage-class

By default s3:PutObject stores objects using the STANDARD storage class, but you can use the x-amz-storage-class request header to specify a different storage class.

When granting the s3:PutObject permission, you can use the s3:x-amz-storage-class condition key to restrict which storage class to use when storing uploaded objects. For more information about storage classes, see Storage Classes.

For an example policy, see Example 5: Restrict object uploads to objects with a specific storage class.

Valid Values: STANDARD | STANDARD_IA | REDUCED_REDUNDANCY. The default is STANDARD.

  • s3:RequestObjectTagKeys

  • s3:RequestObjectTag/<tag-key>

Using this condition key you can limit permission for the s3:PutObject action by restricting the object tags allowed in the request. For examples of using these condition keys, see Object Tagging and Access Control Policies.

s3:PutObjectAcl

  • s3:x-amz-acl (for canned ACL permissions)

  • s3:x-amz-grant-permission (for explicit permissions), where permission can be:

    read, write,​ read-acp,​ write​-acp,​ ​grant-full​-control

The PUT Object ACL API sets the access control list (ACL) on the specified object. The operation supports ACL-related headers. When granting this permission, the bucket owner can add conditions using these keys to require certain permissions. For more information about ACLs, see Access Control List (ACL) Overview.

For example, the bucket owner may want to retain control of the object regardless of who owns the object. To accomplish this, the bucket owner can add a condition using one of these keys to require the user to include specific permissions to the bucket owner.

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission for the s3:PutObjectAcl action to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:PutObjectTagging

  • s3:RequestObjectTagKeys

  • s3:RequestObjectTag/<tag-key>

Using this condition key you can limit permission for the s3:PutObjectTagging action by restricting the object tags allowed in the request. For examples of using these condition keys, see Object Tagging and Access Control Policies.

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:PutObjectVersionTagging

  • s3:RequestObjectTagKeys

  • s3:RequestObjectTag/<tag-key>

Using this condition key you can limit permission for the s3:PutObjectVersionTagging action by restricting the object tags allowed in the request. For examples of using these condition keys, see Object Tagging and Access Control Policies.

s3:VersionId

Using this condition key you can limit the permission for the s3:PutObjectVersionTagging action to a specific object version. For an example policy, see Example 4: Granting access to a specific version of an object.

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:GetObjectVersion

s3:VersionId

This Amazon S3 permission enables the user to perform a set of Amazon S3 API operations (see Amazon S3 Storage Class Analysis Export File LayoutAmazon S3 Permissions for Object Operations). For a version-enabled bucket, you can specify the object version to retrieve data for.

By adding a condition using this key, the bucket owner can restrict the user to accessing data only for a specific version of the object. For an example policy, see Example 4: Granting access to a specific version of an object.

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:GetObject

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:GetObjectAcl

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:GetObjectVersionAcl

s3:VersionId

You can retrive Access Control List (ACL) of a specific object version using the GET Object acl API. User must have permission for the s3:GetObjectVersionAcl action. For a version-enabled bucket, this Amazon S3 permission allows a user to get the ACL for a specific version of the object.

The bucket owner can add a condition using the key to restrict the user to a specific version of the object.

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:PutObjectVersionAcl

s3:VersionId

For a version-enabled bucket, you can specify the object version in the PUT Object acl request to set ACL on a specific object version. Using this condition, the bucket owner can restrict the user to setting an ACL only on a specific version of an object.

  • s3:x-amz-acl (for canned ACL permissions)

  • s3:x-amz-grant-permission (for explicit permissions), where permission can be:

    read, write,​ read-acp,​ write​-acp,​ ​grant-full​-control

For a version-enabled bucket, this Amazon S3 permission allows you to set an ACL on a specific version of the object.

For a description of these condition keys, see the s3:PutObjectACL permission in this table.

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:DeleteObjectVersion

s3:VersionId

For a version-enabled bucket, this Amazon S3 permission allows the user to delete a specific version of the object.

The bucket owner can add a condition using this key to limit the user's ability to delete only a specific version of the object.

For an example of using this condition key, see Example 4: Granting access to a specific version of an object. The example is about granting the s3:GetObjectVersion action, but the policy shows the use of this condition key.

s3:DeleteObjectTagging

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:DeleteObjectVersionTagging

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:VersionId

Using this condition key you can limit the permission for the s3:DeleteObjectVersionTagging action to a specific object version. For an example policy, see Example 4: Granting access to a specific version of an object.

s3:GetObjectTagging

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:GetObjectVersionTagging

s3:ExistingObjectTag/<tag-key>

Using this condition key you can limit the permission to only on objects that have a specific tag key and value. For examples, see Object Tagging and Access Control Policies.

s3:VersionId

Using this condition key you can limit the permission for the s3:GetObjectVersionTagging action to a specific object version. For an example policy, see Example 4: Granting access to a specific version of an object.

Example 1: Granting s3:PutObject permission with a condition requiring the bucket owner to get full control

Suppose Account A owns a bucket and the account administrator wants to grant Dave, a user in Account B, permissions to upload objects. By default, objects that Dave uploads are owned by Account B, and Account A has no permissions on these objects. Because the bucket owner is paying the bills, it wants full permissions on the objects that Dave uploads. The Account A administrator can accomplish this by granting the s3:PutObject permission to Dave, with a condition that the request include ACL-specific headers, that either grants full permission explicitly or uses a canned ACL (see PUT Object).

  • Require the x-amz-full-control header in the request with full control permission to the bucket owner.

    The following bucket policy grants the s3:PutObject permission to user Dave with a condition using the s3:x-amz-grant-full-control condition key, which requires the request to include the x-amz-full-control header.

    Copy to clipboard
    { "Version": "2012-10-17", "Statement": [ { "Sid": "statement1", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::AccountB-ID:user/Dave" }, "Action": "s3:PutObject", "Resource": "arn:aws:s3:::examplebucket/*", "Condition": { "StringEquals": { "s3:x-amz-grant-full-control": "id=AccountA-CanonicalUserID" } } } ] }

    Note

    This example is about cross-account permission. However, if Dave, who is getting the permission, belongs to the AWS account that owns the bucket, then this conditional permission is not necessary, because the parent account to which Dave belongs owns objects the user uploads.

    The preceding bucket policy grants conditional permission to user Dave in Account B. While this policy is in effect, it is possible for Dave to get the same permission without any condition via some other policy. For example, Dave can belong to a group and you grant the group s3:PutObject permission without any condition. To avoid such permission loopholes, you can write a stricter access policy by adding explicit deny. In this example, we explicitly deny user Dave upload permission if he does not include the necessary headers in the request granting full permissions to the bucket owner. Explicit deny always supersedes any other permission granted. The following is the revised access policy example.

    Copy to clipboard
    { "Version": "2012-10-17", "Statement": [ { "Sid": "statement1", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::AccountB-ID:user/AccountBadmin" }, "Action": "s3:PutObject", "Resource": "arn:aws:s3:::examplebucket/*", "Condition": { "StringEquals": { "s3:x-amz-grant-full-control": "id=AccountA-CanonicalUserID" } } }, { "Sid": "statement2", "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::AccountB-ID:user/AccountBadmin" }, "Action": "s3:PutObject", "Resource": "arn:aws:s3:::examplebucket/*", "Condition": { "StringNotEquals": { "s3:x-amz-grant-full-control": "id=AccountA-CanonicalUserID" } } } ] }

    If you have two AWS accounts, you can test the policy using the AWS CLI. You attach the policy and, using Dave's credentials, test the permission using the following AWS CLI put-object command. You provide Dave's credentials by adding the --profile parameter. You grant full control permission to the bucket owner by adding the --grant-full-control parameter. For more information about setting up and using the AWS CLI, see Setting Up the Tools for the Example Walkthroughs.

    Copy to clipboard
    aws s3api put-object --bucket examplebucket --key HappyFace.jpg --body c:\HappyFace.jpg --grant-full-control id="AccountA-CanonicalUserID" --profile AccountBUserProfile
  • Require the x-amz-acl header with a canned ACL granting full control permission to the bucket owner.

    To require the x-amz-acl header in the request, you can replace the key-value pair in the Condition block and specify the s3:x-amz-acl condition key as shown below.

    Copy to clipboard
    "Condition": { "StringNotEquals": { "s3:x-amz-acl": "bucket-owner-full-control" }

    To test the permission using the AWS CLI, you specify the --acl parameter. The AWS CLI then adds the x-amz-acl header when it sends the request.

    Copy to clipboard
    aws s3api put-object --bucket examplebucket --key HappyFace.jpg --body c:\HappyFace.jpg --acl "bucket-owner-full-control" --profile AccountBadmin

Example 2: Granting s3:PutObject permission requiring objects stored using server-side encryption

Suppose Account A owns a bucket and the account administrator wants to grant Jane, a user in Account A, permission to upload objects with a condition that Jane always request server-side encryption so that Amazon S3 saves objects encrypted. The Account A administrator can accomplish using the s3:x-amz-server-side-encryption condition key as shown. The key-value pair in the Condition block specifies the s3:x-amz-server-side-encryption key.

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

When testing the permission using AWS CLI, you will need to add the required parameter using the --server-side-encryption parameter.

Copy to clipboard
aws s3api put-object --bucket example1bucket --key HappyFace.jpg --body c:\HappyFace.jpg --server-side-encryption "AES256" --profile AccountBadmin

Example 3: Granting s3:PutObject permission to copy objects with a restriction on the copy source

In the PUT Object request, when you specify a source object, it is a copy operation (see PUT Object - Copy). Accordingly, the bucket owner can grant a user permission to copy objects with restrictions on the source. For example:

  • allow copying objects only from the sourcebucket bucket.

  • allow copying objects from the sourcebucket bucket, and only the objects whose key name prefix start with public/ f. For example, sourcebucket/public/*

  • allow copying only a specific object from the sourcebucket. For example, sourcebucket/example.jpg.

The following bucket policy grants user Dave s3:PutObject permission that allows him to copy only objects with a condition that the request include the s3:x-amz-copy-source header and the header value specify the /examplebucket/public/* key name prefix.

Copy to clipboard
{ "Version": "2012-10-17", "Statement": [ { "Sid": "cross-account permission to user in your own account", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::AccountA-ID:user/Dave" }, "Action": ["s3:PutObject"], "Resource": "arn:aws:s3:::examplebucket/*" }, { "Sid": "Deny your user permission to upload object if copy source is not /bucket/folder", "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::AccountA-ID:user/Dave" }, "Action": "s3:PutObject", "Resource": "arn:aws:s3:::examplebucket/*", "Condition": { "StringNotLike": { "s3:x-amz-copy-source": "examplebucket/public/*" } } } ] }

You can test the permission using the AWS CLI copy-object command. You specify the source by adding the --copy-source parameter, the key name prefix must match that the prefix allowed in the policy. You will need to provide user Dave credentials using the --profile parameter. For more information about setting up AWS CLI, see Setting Up the Tools for the Example Walkthroughs.

Copy to clipboard
aws s3api copy-object --bucket examplebucket --key HappyFace.jpg --copy-source examplebucket/public/PublicHappyFace1.jpg --profile AccountADave

Note that the preceding policy uses the StringNotLike condition. To grant permission to copy only a specific object you will need to change the condition from StringNotLike to StringNotEquals and then specify the exact object key as shown.

Copy to clipboard
"Condition": { "StringNotEquals": { "s3:x-amz-copy-source": "examplebucket/public/PublicHappyFace1.jpg" } }

Example 4: Granting access to a specific version of an object

Suppose Account A owns a version-enabled bucket. The bucket has several versions of the HappyFace.jpg object. The account administrator now wants to grant its user (Dave) permission to get only a specific version of the object. The account administrator can accomplish this by granting Dave s3:GetObjectVersion permission conditionally as shown. The key-value pair in the Condition block specifies the s3:VersionId condition key.

Copy to clipboard
{ "Version": "2012-10-17", "Statement": [ { "Sid": "statement1", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::AccountA-ID:user/Dave" }, "Action": ["s3:GetObjectVersion"], "Resource": "arn:aws:s3:::examplebucketversionenabled/HappyFace.jpg" }, { "Sid": "statement2", "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::AccountA-ID:user/Dave" }, "Action": ["s3:GetObjectVersion"], "Resource": "arn:aws:s3:::examplebucketversionenabled/HappyFace.jpg", "Condition": { "StringNotEquals": { "s3:VersionId": "AaaHbAQitwiL_h47_44lRO2DDfLlBO5e" } } } ] }

In this case, Dave will need to know the exact object version ID to retrieve the object.

You can test the permissions using the AWS CLI get-object command with the --version-id parameter identifying the specific object version. The command retrieves the object and saves it to the OutputFile.jpg file.

Copy to clipboard
aws s3api get-object --bucket examplebucketversionenabled --key HappyFace.jpg OutputFile.jpg --version-id AaaHbAQitwiL_h47_44lRO2DDfLlBO5e --profile AccountADave

Example 5: Restrict object uploads to objects with a specific storage class

Suppose Account A owns a bucket and the account administrator wants to restrict Dave, a user in Account A, to be able to only upload objects to the bucket that will be stored with the STANDARD_IA storage class. The Account A administrator can accomplish this by using the s3:x-amz-storage-class condition key as shown in the following example bucket policy.

Copy to clipboard
{ "Version": "2012-10-17", "Statement": [ { "Sid": "statement1", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::AccountA-ID:user/Dave" }, "Action": "s3:PutObject", "Resource": [ "arn:aws:s3:::examplebucket/*" ], "Condition": { "StringEquals": { "s3:x-amz-storage-class": [ "STANDARD_IA" ] } } } ] }

Amazon S3 Condition Keys for Bucket Operations

The following table shows list of bucket operation–specific permissions you can grant in policies, and for each of the permissions, the available keys you can use in specifying a condition.

Permission Applicable Condition Keys Description

s3:CreateBucket

  • s3:x-amz-acl (for canned ACL permissions)

  • s3:x-amz-grant-permission (for explicit permissions), where permission can be:

    read, write,​ read-acp,​ write​-acp,​ ​full​-control

The Create Bucket API (see PUT Bucket) supports ACL-specific headers. Using these condition keys, you can require a user to set these headers in the request granting specific permissions.

s3:LocationConstraint

Using this condition key, you can restrict user to create bucket in a specific region. For a policy example, see Example 1: Allow a user to create a bucket but only in a specific region.

s3:ListBucket

s3:prefix

Using this condition key, you can limit the response of the Get Bucket (List Objects) API (see GET Bucket (List Objects)) to key names with specific prefix.

The Get Bucket (List Objects) API returns list of object keys in the specified bucket. This API supports the prefix header to retrieve only the object keys with a specific prefix. This condition key relates to the prefix header.

For example, the Amazon S3 console supports the folder concept using key name prefixes. So if you have two objects with key names public/object1.jpg and public/object2.jpg, the console shows the objects under the public folder. If you organize your object keys using such prefixes, you can grant s3:ListBucket permission with the condition that will allow the user to get a list of key names with a specific prefix.

For a policy example, see Example 2: Allow a user to get a list of objects in a bucket according to a specific prefix .

s3:delimiter

If you organize your object key names using prefixes and delimiters, you can use this condition key to require the user to specify the delimiter parameter in the Get Bucket (List Objects) request. In this case, the response Amazon S3 returns is a list of object keys with common prefixes grouped together. For an example of using prefixes and delimiters, go to Get Bucket (List Objects).

s3:max-keys

Using this condition, you can limit the number of keys Amazon S3 returns in response to the Get Bucket (List Objects) request by requiring the user to specify the max-keys parameter. By default the API returns up to 1000 key names.

For a list of numeric conditions you can use, see Numeric Condition Operators in the IAM User Guide.

s3:ListBucketVersions

s3:prefix

If your bucket is version-enabled, you can use the GET Bucket Object versions API (see GET Bucket Object versions) to retrieve metadata of all of the versions of objects. For this API, the bucket owner must grant the s3:ListBucketVersions permission in the policy.

Using this condition key, you can limit the response of the API to key names with a specific prefix by requiring the user to specify the prefix parameter in the request with a specific value.

For example, the Amazon S3 console supports the folder concept of using key name prefixes. If you have two objects with key names public/object1.jpg and public/object2.jpg, the console shows the objects under the public folder. If you organize your object keys using such prefixes, you can grant s3:ListBucket permission with the condition that will allow a use to get a list of key names with a specific prefix.

For a policy example, see Example 2: Allow a user to get a list of objects in a bucket according to a specific prefix .

s3:delimiter

If you organize your object key names using prefixes and delimiters, you can use this condition key to require the user to specify the delimiter parameter in the GET Bucket Object versions request. In this case, the response Amazon S3 returns is a list of object keys with common prefixes grouped together.

s3:max-keys

Using this condition you can limit the number of keys Amazon S3 returns in response to the GET Bucket Object versions request by requiring the user to specify the max-keys parameter. By default, the API returns up to 1000 key names. For a list of numeric conditions you can use, see Numeric Condition Operators in the IAM User Guide.

s3:PutBucketAcl

  • s3:x-amz-acl (for canned ACL permissions)

  • s3:x-amz-grant-permission (for explicit permissions), where permission can be:

    read, write,​ read-acp,​ write​-acp,​ ​full​-control

The PUT Bucket acl API (see PUT Bucket) supports ACL-specific headers. You can use these condition keys to require a user to set these headers in the request.

Example 1: Allow a user to create a bucket but only in a specific region

Suppose an AWS account administrator wants to grant its user (Dave), permission to create a bucket in the South America (São Paulo) region only. The account administrator can attach the following user policy granting the s3:CreateBucket permission with a condition as shown. The key-value pair in the Condition block specifies the s3:LocationConstraint key and the sa-east-1 region as its value.

Note

In this example, the bucket owner is granting permission to one of its users, so either a bucket policy or a user policy can be used. This example shows a user policy.

For a list of Amazon S3 regions, go to Regions and Endpoints in the Amazon Web Services General Reference.

Copy to clipboard
{ "Version":"2012-10-17", "Statement":[ { "Sid":"statement1", "Effect":"Allow", "Action":[ "s3:CreateBucket" ], "Resource":[ "arn:aws:s3:::*" ], "Condition": { "StringLike": { "s3:LocationConstraint": "sa-east-1" } } } ] }

This policy restricts the user from creating a bucket in any other region except sa-east-1. However, it is possible some other policy will grant this user permission to create buckets in another region. For example, if the user belongs to a group, the group may have a policy attached to it allowing all users in the group permission to create buckets in some other region. To ensure the user does not get permission to create buckets in any other region, you can add an explicit deny statement in this policy.

Copy to clipboard
{ "Version":"2012-10-17", "Statement":[ { "Sid":"statement1", "Effect":"Allow", "Action":[ "s3:CreateBucket" ], "Resource":[ "arn:aws:s3:::*" ], "Condition": { "StringLike": { "s3:LocationConstraint": "sa-east-1" } } }, { "Sid":"statement2", "Effect":"Deny", "Action":[ "s3:CreateBucket" ], "Resource":[ "arn:aws:s3:::*" ], "Condition": { "StringNotLike": { "s3:LocationConstraint": "sa-east-1" } } } ] }

The Deny statement uses the StringNotLike condition. That is, a create bucket request will be denied if the location constraint is not "sa-east-1". The explicit deny will not allow the user to create a bucket in any other region, no matter what other permission the user gets.

You can test the policy using the following create-bucket AWS CLI command. This example uses the bucketconfig.txt file to specify the location constraint. Note the Windows file path. You will need to update the bucket name and path as appropriate. You must provide user credentials using the --profile parameter. For more information about setting up and using the AWS CLI, see Setting Up the Tools for the Example Walkthroughs.

Copy to clipboard
aws s3api create-bucket --bucket examplebucket --profile AccountADave --create-bucket-configuration file://c:/Users/someUser/bucketconfig.txt

The bucketconfig.txt file specifies the configuration as follows

Copy to clipboard
{"LocationConstraint": "sa-east-1"}

Example 2: Allow a user to get a list of objects in a bucket according to a specific prefix

A bucket owner can restrict a user to list content of a specific folder in the bucket. This is useful if objects in the bucket are organized by key name prefixes, the Amazon S3 console then uses the prefixes to show a folder hierarchy (only the console supports the concept of folders; the Amazon S3 API supports only buckets and objects).

In this example, the bucket owner and the parent account to which the user belongs are the same. So the bucket owner can use either a bucket policy or a user policy. First, we show a user policy.

The following user policy grants the s3:ListBucket permission (see GET Bucket (List Objects)) with a condition that requires the user to specify the prefix in the request with the value projects.

Copy to clipboard
{ "Version":"2012-10-17", "Statement":[ { "Sid":"statement1", "Effect":"Allow", "Action":[ "s3:ListBucket" ], "Resource":[ "arn:aws:s3:::examplebucket" ], "Condition" : { "StringEquals" : { "s3:prefix": "projects" } } }, { "Sid":"statement2", "Effect":"Deny", "Action":[ "s3:ListBucket" ], "Resource":[ "arn:aws:s3:::examplebucket" ], "Condition" : { "StringNotEquals" : { "s3:prefix": "projects" } } } ] }

The condition restricts the user to listing object keys with the projects prefix. The added explicit deny will deny user request for listing keys with any other prefix no matter what other permissions the user might have. For example, it is possible that the user gets permission to list object keys without any restriction, for example either by updates to the preceding user policy or via a bucket policy. But because explicit deny always supersedes, the user request to list keys other than the project prefix will be denied.

The preceding policy is a user policy. If you add the Principal element to the policy, identifying the user, you now have a bucket policy as shown.

Copy to clipboard
{ "Version":"2012-10-17", "Statement":[ { "Sid":"statement1", "Effect":"Allow", "Principal": { "AWS": "arn:aws:iam::BucketOwner-accountID:user/user-name" }, "Action":[ "s3:ListBucket" ], "Resource":[ "arn:aws:s3:::examplebucket" ], "Condition" : { "StringEquals" : { "s3:prefix": "examplefolder" } } }, { "Sid":"statement2", "Effect":"Deny", "Principal": { "AWS": "arn:aws:iam::BucketOwner-AccountID:user/user-name" }, "Action":[ "s3:ListBucket" ], "Resource":[ "arn:aws:s3:::examplebucket" ], "Condition" : { "StringNotEquals" : { "s3:prefix": "examplefolder" } } } ] }

You can test the policy using the following list-object AWS CLI command. In the command, you provide user credentials using the --profile parameter. For more information about setting up and using the AWS CLI, see Setting Up the Tools for the Example Walkthroughs.

Copy to clipboard
aws s3api list-objects --bucket examplebucket --prefix examplefolder --profile AccountADave

Now if the bucket is version-enabled, to list the objects in the bucket, instead of s3:ListBucket permission, you must grant the s3:ListBucketVersions permission in the preceding policy. This permission also supports the s3:prefix condition key.