Bucket policy examples using condition keys

You can use access policy language to specify conditions when you grant permissions. You can use the optional Condition element, or Condition block, to specify conditions for when a policy is in effect.

For policies that use Amazon S3 condition keys for object and bucket operations, see the following examples. For more information about condition keys, see Policy condition keys for Amazon S3. For a complete list of Amazon S3 actions, condition keys, and resources that you can specify in policies, see Actions, resources, and condition keys for Amazon S3 in the Service Authorization Reference.

For more information about the permissions to S3 API operations by S3 resource types, see Required permissions for Amazon S3 API operations.

Examples: Amazon S3 condition keys for object operations

The following examples show how you can use Amazon S3‐specific condition keys for object operations. For a complete list of Amazon S3 actions, condition keys, and resources that you can specify in policies, see Actions, resources, and condition keys for Amazon S3 in the Service Authorization Reference.

For more information about the permissions to S3 API operations by S3 resource types, see Required permissions for Amazon S3 API operations.

Several of the example policies show how you can use conditions keys with PUT Object operations. PUT Object operations allow access control list (ACL)–specific headers that you can use to grant ACL-based permissions. By using these condition keys, you can set a condition to require specific access permissions when the user uploads an object. You can also grant ACL–based permissions with the PutObjectAcl operation. For more information, see PutObjectAcl in the Amazon S3 Amazon Simple Storage Service API Reference. For more information about ACLs, see Access control list (ACL) overview.

Example 1: Granting s3:PutObject permission requiring that objects be stored using server-side encryption

Suppose that Account A owns a bucket. The account administrator wants to grant Jane, a user in Account A, permission to upload objects with the condition that Jane always request server-side encryption with Amazon S3 managed keys (SSE-S3). The Account A administrator can specify this requirement by using the s3:x-amz-server-side-encryption condition key as shown. The key-value pair in the following Condition block specifies the s3:x-amz-server-side-encryption condition key and SSE-S3 (AES256) as the encryption type:

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

When testing this permission by using the AWS CLI, you must add the required encryption by using the --server-side-encryption parameter, as shown in the following example. To use this example command, replace the user input placeholders with your own information.

aws s3api put-object --bucket amzn-s3-demo-bucket --key HappyFace.jpg --body c:\HappyFace.jpg --server-side-encryption "AES256" --profile AccountAadmin

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

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

The following bucket policy grants a user (Dave) the s3:PutObject permission. This policy allows him to copy objects only with a condition that the request include the s3:x-amz-copy-source header and that the header value specify the /amzn-s3-demo-source-bucket/public/* key name prefix. To use this example policy, replace the user input placeholders with your own information.

Test the policy with the AWS CLI

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 the prefix allowed in the policy. You need to provide the user Dave credentials using the --profile parameter. For more information about setting up the AWS CLI, see Developing with Amazon S3 using the AWS CLI in the Amazon S3 API Reference.

aws s3api copy-object --bucket amzn-s3-demo-source-bucket --key HappyFace.jpg --copy-source amzn-s3-demo-source-bucket/public/PublicHappyFace1.jpg --profile AccountADave

Give permission to copy only a specific object

The preceding policy uses the StringNotLike condition. To grant permission to copy only a specific object, you must change the condition from StringNotLike to StringNotEquals and then specify the exact object key, as shown in the following example. To use this example command, replace the user input placeholders with your own information.

"Condition": { "StringNotEquals": { "s3:x-amz-copy-source": "amzn-s3-demo-source-bucket/public/PublicHappyFace1.jpg" } }

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

Suppose that Account A owns a versioning-enabled bucket. The bucket has several versions of the HappyFace.jpg object. The Account A administrator now wants to grant the user Dave permission to get only a specific version of the object. The account administrator can accomplish this by granting the user Dave the s3:GetObjectVersion permission conditionally, as shown in the following example. The key-value pair in the Condition block specifies the s3:VersionId condition key. In this case, to retrieve the object from the specified versioning-enabled bucket, Dave needs to know the exact object version ID. To use this example policy, replace the user input placeholders with your own information.

For more information, see GetObject in the Amazon Simple Storage Service API Reference.

Test the policy with the AWS CLI

You can test the permissions in this policy by using the AWS CLI get-object command with the --version-id parameter to identify the specific object version to retrieve. The command retrieves the specified version of the object and saves it to the OutputFile.jpg file.

aws s3api get-object --bucket amzn-s3-demo-bucket --key HappyFace.jpg OutputFile.jpg --version-id AaaHbAQitwiL_h47_44lRO2DDfLlBO5e --profile AccountADave

Example 4: Granting permissions based on object tags

For examples of how to use object tagging condition keys with Amazon S3 operations, see Tagging and access control policies.

Example 5: Restricting access by the AWS account ID of the bucket owner

You can use either the aws:ResourceAccount or s3:ResourceAccount condition key to write IAM or virtual private cloud (VPC) endpoint policies that restrict user, role, or application access to the Amazon S3 buckets that are owned by a specific AWS account ID. You can use these condition keys to restrict clients within your VPC from accessing buckets that you don't own.

However, be aware that some AWS services rely on access to AWS managed buckets. Therefore, using the aws:ResourceAccount or s3:ResourceAccount key in your IAM policy might also affect access to these resources. For more information, see the following resources:

For more information about the aws:ResourceAccount and s3:ResourceAccount condition keys and examples that show how to use them, see Limit access to Amazon S3 buckets owned by specific AWS accounts in the AWS Storage Blog.

Example 6: Requiring a minimum TLS version

You can use the s3:TlsVersion condition key to write IAM, virtual private cloud endpoint (VPCE), or bucket policies that restrict user or application access to Amazon S3 buckets based on the TLS version that's used by the client. You can use this condition key to write policies that require a minimum TLS version.

{ "Effect": "Deny", "Action": "s3:*", "Resource": "*", "Condition": { "Bool": { "aws:SecureTransport": "false", "aws:PrincipalIsAWSService": "false" } } }

Example 7: Excluding certain principals from a Deny statement

The following bucket policy denies s3:GetObject access to the amzn-s3-demo-bucket, except to principals with the account number 123456789012. To use this example policy, replace the user input placeholders with your own information.

Example 8: Enforcing clients to conditionally upload objects based on object key names or ETags

With conditional writes, you can add an additional header to your WRITE requests in order to specify preconditions for your S3 operation. This header specifies a condition that, if not met, will result in the S3 operation failing. For example you can prevent overwrites of existing data by validating there is no object with the same key name already in your bucket during object upload. You can alternatively check an object's entity tag (ETag) in Amazon S3 before writing an object.

For bucket policy examples that use conditions in a bucket policy to enforce conditional writes, see Enforce conditional writes on Amazon S3 buckets.

Examples: Amazon S3 condition keys for bucket operations

The following example policies show how you can use Amazon S3 specific condition keys for bucket operations.

Example 1: Granting s3:GetObject permission with a condition on an IP address

You can give authenticated users permission to use the s3:GetObject action if the request originates from a specific range of IP addresses (for example, 192.0.2.*), unless the IP address is one that you want to exclude (for example, 192.0.2.188). In the Condition block, IpAddress and NotIpAddress are conditions, and each condition is provided a key-value pair for evaluation. Both of the key-value pairs in this example use the aws:SourceIp AWS wide key. To use this example policy, replace the user input placeholders with your own information.

You can also use other AWS‐wide condition keys in Amazon S3 policies. For example, you can specify the aws:SourceVpce and aws:SourceVpc condition keys in bucket policies for VPC endpoints. For specific examples, see Controlling access from VPC endpoints with bucket policies.

Example 2: Getting a list of objects in a bucket with a specific prefix

You can use the s3:prefix condition key to limit the response of the ListObjectsV2 API operation to key names with a specific prefix. If you are the bucket owner, you can use this condition key to restrict a user to list the contents of a specific prefix in the bucket. The s3:prefix condition key is useful if the objects in the bucket are organized by key name prefixes.

The Amazon S3 console uses key name prefixes to show a folder concept. Only the console supports the concept of folders; the Amazon S3 API supports only buckets and objects. For example, if you have two objects with the key names public/object1.jpg and public/object2.jpg, the console shows the objects under the public folder. In the Amazon S3 API, these are objects with prefixes, not objects in folders. For more information about using prefixes and delimiters to filter access permissions, see Controlling access to a bucket with user policies.

In the following scenario, 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 to grant access. For more information about other condition keys that you can use with the ListObjectsV2 API operation, see ListObjectsV2.

User policy

The following user policy grants the s3:ListBucket permission (see ListObjectsV2) with a Condition statement that requires the user to specify a prefix in the request with a value of projects. To use this example policy, replace the user input placeholders with your own information.

The Condition statement restricts the user to listing only object keys that have the projects prefix. The added explicit Deny statement denies the user from listing keys with any other prefix, no matter what other permissions the user might have. For example, it's possible that the user could get permission to list object keys without any restriction, either through updates to the preceding user policy or through a bucket policy. Because explicit Deny statements always override Allow statements, if the user tries to list keys other than those that have the projects prefix, the request is denied.

Bucket policy

If you add the Principal element to the above user policy, identifying the user, you now have a bucket policy, as shown in the following example. To use this example policy, replace the user input placeholders with your own information.

Test the policy with the AWS CLI

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 Developing with Amazon S3 using the AWS CLI in the Amazon S3 API Reference.

aws s3api list-objects --bucket amzn-s3-demo-bucket --prefix projects --profile AccountA

Example 3: Setting the maximum number of keys

You can use the s3:max-keys condition key to set the maximum number of keys that a requester can return in a ListObjectsV2 or ListObjectVersions request. By default, these API operations return up to 1,000 keys. For a list of numeric condition operators that you can use with s3:max-keys and accompanying examples, see Numeric Condition Operators in the IAM User Guide.