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.
Examples — Amazon S3 condition keys for object operations
This section provides examples that show you 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.
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. Using these keys, the bucket owner 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.
Topics
- Example 1: Granting s3:PutObject permission requiring objects stored using server-side encryption
- Example 2: Granting s3:PutObject permission to copy objects with a restriction on the copy source
- Example 3: Granting access to a specific version of an object
- Example 4: Granting permissions based on object tags
- Example 5: Restricting access by the AWS account ID of the bucket owner
- Example 6: Requiring a minimum TLS version
Example 1: Granting s3:PutObject permission requiring objects 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 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.
"Condition": { "StringNotEquals": { "s3:x-amz-server-side-encryption": "AES256" }}
When testing the permission using the AWS CLI, you must add the required
parameter using the --server-side-encryption
parameter.
aws s3api put-object --bucket example1bucket --key HappyFace.jpg --body c:\HappyFace.jpg --server-side-encryption "AES256" --profile AccountBadmin
Example 2: 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 source bucket and only the objects whose key name prefix starts 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. It allows him to copy objects only with a condition that the
request include the s3:x-amz-copy-source
header and the header
value specify the /awsexamplebucket1/public/*
key name prefix.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "cross-account permission to user in your own account", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::
123456789012
:user/Dave" }, "Action": "s3:PutObject", "Resource": "arn:aws:s3:::awsexamplebucket1
/*" }, { "Sid": "Deny your user permission to upload object if copy source is not /bucket/folder", "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::123456789012
:user/Dave" }, "Action": "s3:PutObject", "Resource": "arn:aws:s3:::awsexamplebucket1
/*", "Condition": { "StringNotLike": { "s3:x-amz-copy-source": "awsexamplebucket1
/public/*" } } } ] }
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.
aws s3api copy-object --bucket
awsexamplebucket1
--key HappyFace.jpg --copy-sourceexamplebucket
/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.
"Condition": { "StringNotEquals": { "s3:x-amz-copy-source": "
awsexamplebucket1
/public/PublicHappyFace1.jpg" } }
Example 3: Granting access to a specific version of an object
Suppose that 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 below. The key-value pair in the
Condition
block specifies the s3:VersionId
condition key. In this case, Dave needs to know the exact object version ID
to retrieve the object.
For more information, see GetObject in the Amazon Simple Storage Service API Reference.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "statement1", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::
123456789012
:user/Dave" }, "Action": "s3:GetObjectVersion", "Resource": "arn:aws:s3:::examplebucketversionenabled
/HappyFace.jpg" }, { "Sid": "statement2", "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::123456789012
:user/Dave" }, "Action": "s3:GetObjectVersion", "Resource": "arn:aws:s3:::examplebucketversionenabled
/HappyFace.jpg", "Condition": { "StringNotEquals": { "s3:VersionId": "AaaHbAQitwiL_h47_44lRO2DDfLlBO5e
" } } } ] }
Test the policy with the AWS CLI
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.
aws s3api get-object --bucket
examplebucketversionenabled
--key HappyFace.jpg OutputFile.jpg --version-idAaaHbAQitwiL_h47_44lRO2DDfLlBO5e
--profile AccountADave
Example 4: Granting permissions based on object tags
For examples on 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
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 this condition key to restrict clients
within your VPC from accessing buckets that you do not 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 and examples, see the following resources:
-
Restrict access to buckets in a specified AWS account in the AWS PrivateLink Guide
-
Restrict access to buckets that Amazon ECR uses in the Amazon ECR Guide
-
Provide required access to Systems Manager for AWS managed Amazon S3 buckets in the AWS Systems Manager Guide
-
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 used by the client. You can use this condition key to write policies that require a minimum TLS version.
This example bucket policy denies PutObject requests by clients that have a TLS version lower than 1.2, for example, 1.1 or 1.0.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Principal": "*", "Action": "s3:PutObject", "Resource": [ "arn:aws:s3:::
", "arn:aws:s3:::
DOC-EXAMPLE-BUCKET1
/*" ], "Condition": { "NumericLessThan": { "s3:TlsVersion": 1.2 } } } ] }
DOC-EXAMPLE-BUCKET1
This example bucket policy allows PutObject requests by clients that have a TLS version higher than 1.1, for example, 1.2, 1.3 or higher.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "s3:PutObject", "Resource": [ "arn:aws:s3:::
", "arn:aws:s3:::
DOC-EXAMPLE-BUCKET1
/*" ], "Condition": { "NumericGreaterThan": { "s3:TlsVersion": 1.1 } } } ] }
DOC-EXAMPLE-BUCKET1
Examples — Amazon S3 condition keys for bucket operations
This section provides example policies that show you how you can use Amazon S3‐specific condition keys for bucket operations.
Topics
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 (192.0.2.*), unless the IP address is
192.0.2.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, see http://www.rfc-editor.org/rfc/rfc4632.txt
{ "Version": "2012-10-17", "Id": "S3PolicyId1", "Statement": [ { "Sid": "statement1", "Effect": "Allow", "Principal": "*", "Action":"s3:GetObject", "Resource": "arn:aws:s3:::
awsexamplebucket1
/*", "Condition" : { "IpAddress" : { "aws:SourceIp": "192.0.2.0/24" }, "NotIpAddress" : { "aws:SourceIp": "192.0.2.188/32" } } } ] }
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.
Note
For some AWS global condition keys, only certain resource types are supported. Therefore, check whether Amazon S3 supports the global condition key and resource type that you want to use, or if you'll need to use an Amazon S3-specific condition key instead. For a complete list of supported resource types and condition keys for Amazon S3, see Actions, resources, and condition keys for Amazon S3 in the Service Authorization Reference.
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 GET Bucket
(ListObjects) API to key names with a specific prefix. If you
are the bucket owner, you can restrict a user to list the contents of a
specific prefix in the bucket. This condition key is useful if 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 more
information about using prefixes and delimiters to filter access
permissions, see Controlling access to a bucket with user policies.
For example, if you have two objects with 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. However, in the Amazon S3 API, if
you organize your object keys using such prefixes, you can grant
s3:ListBucket
permission with the s3:prefix
condition that will allow the user to get a list of key names with those
specific prefixes.
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. For more information about other condition keys that you can use with the GET Bucket (ListObjects) API, see ListObjects.
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
.
{ "Version":"2012-10-17", "Statement":[ { "Sid":"statement1", "Effect":"Allow", "Action": "s3:ListBucket", "Resource":"arn:aws:s3:::
awsexamplebucket1
", "Condition" : { "StringEquals" : { "s3:prefix": "projects" } } }, { "Sid":"statement2", "Effect":"Deny", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::awsexamplebucket1
", "Condition" : { "StringNotEquals" : { "s3:prefix": "projects" } } } ] }
The condition restricts the user to listing object keys with the
projects
prefix. The added explicit deny denies the 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, either by
updates to the preceding user policy or via a bucket policy. Because
explicit deny always supersedes, the user request to list keys other than
the projects
prefix 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.
{ "Version":"2012-10-17", "Statement":[ { "Sid":"statement1", "Effect":"Allow", "Principal": { "AWS": "arn:aws:iam::
123456789012
:user/bucket-owner
" }, "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::awsexamplebucket1
", "Condition" : { "StringEquals" : { "s3:prefix": "projects" } } }, { "Sid":"statement2", "Effect":"Deny", "Principal": { "AWS": "arn:aws:iam::123456789012
:user/bucket-owner
" }, "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::awsexamplebucket1
", "Condition" : { "StringNotEquals" : { "s3:prefix": "projects" } } } ] }
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.
aws s3api list-objects --bucket
awsexamplebucket1
--prefix examplefolder --profile AccountADave
If the bucket is version-enabled, to list the objects in the bucket, you
must grant the s3:ListBucketVersions
permission in the
preceding policy, instead of s3:ListBucket
permission. This
permission also supports the s3:prefix
condition key.
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 requester can return in a GET Bucket
(ListObjects) or ListObjectVersions request. By default, the API returns 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.