Amazon S3 condition key examples

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 Amazon S3 condition keys. 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.

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.

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.

Example 1: Granting s3:PutObject permission with a condition requiring the bucket owner to get 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.

Suppose that 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 do this by granting the s3:PutObject permission to Dave, with a condition that the request include ACL-specific headers that either grant full permission explicitly or use a canned ACL. For more information, see PUT Object.

Require the x-amz-full-control header

You can 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.

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

Add explicit deny

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, you explicitly deny the 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 with explicit deny added.

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

Test the policy with the Amazon CLI

If you have two Amazon Web Services accounts, you can test the policy using the Amazon Command Line Interface (Amazon CLI). You attach the policy and use Dave's credentials to test the permission using the following Amazon 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 Amazon CLI, see Developing with Amazon S3 using the Amazon CLI.

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

You can 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 in the following example.

"Condition": {
    "StringEquals": {
        "s3:x-amz-acl": "bucket-owner-full-control"
    }
}

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

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

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-cn:iam::123456789012:user/Dave"
            },
            "Action": "s3:PutObject",
            "Resource": "arn:aws-cn:s3:::awsexamplebucket1/*"
        },
        {
            "Sid": "Deny your user permission to upload object if copy source is not /bucket/folder",
            "Effect": "Deny",
            "Principal": {
                "AWS": "arn:aws-cn:iam::123456789012:user/Dave"
            },
            "Action": "s3:PutObject",
            "Resource": "arn:aws-cn:s3:::awsexamplebucket1/*",
            "Condition": {
                "StringNotLike": {
                    "s3:x-amz-copy-source": "awsexamplebucket1/public/*"
                }
            }
        }
    ]
}

Test the policy with the Amazon CLI

You can test the permission using the Amazon 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 Amazon CLI, see Developing with Amazon S3 using the Amazon CLI.

aws s3api copy-object --bucket awsexamplebucket1 --key HappyFace.jpg 
--copy-source examplebucket/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 4: 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-cn:iam::123456789012:user/Dave"
            },
            "Action": "s3:GetObjectVersion",
            "Resource": "arn:aws-cn:s3:::examplebucketversionenabled/HappyFace.jpg"
        },
        {
            "Sid": "statement2",
            "Effect": "Deny",
            "Principal": {
                "AWS": "arn:aws-cn:iam::123456789012:user/Dave"
            },
            "Action": "s3:GetObjectVersion",
            "Resource": "arn:aws-cn:s3:::examplebucketversionenabled/HappyFace.jpg",
            "Condition": {
                "StringNotEquals": {
                    "s3:VersionId": "AaaHbAQitwiL_h47_44lRO2DDfLlBO5e"
                }
            }
        }
    ]
}

Test the policy with the Amazon CLI

You can test the permissions using the Amazon 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-id AaaHbAQitwiL_h47_44lRO2DDfLlBO5e --profile AccountADave

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

Suppose that Account A, represented by account ID 123456789012, owns a bucket. The account administrator wants to restrict Dave, a user in Account A, to be able to only upload objects to the bucket that are stored with the STANDARD_IA storage class. To restrict object uploads to a specific storage class, the Account A administrator can use the s3:x-amz-storage-class condition key,as shown in the following example bucket policy.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "statement1",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws-cn:iam::123456789012:user/Dave"
      },
      "Action": "s3:PutObject",
      "Resource": "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET1/*",
      "Condition": {
        "StringEquals": {
          "s3:x-amz-storage-class": [
            "STANDARD_IA"
          ]
        }
      }
    }
  ]
}

Example 6: 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 7: Restricting access by the Amazon Web Services 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 Amazon Web Services 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 Amazon services rely on access to Amazon 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:

Example 8: 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.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Principal": "*",
            "Action": "s3:PutObject",
            "Resource": [
                "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET1",
                "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET1/*"
            ],
            "Condition": {
                "NumericLessThan": {
                    "s3:TlsVersion": 1.2
                }
            }
        }
    ]
}
					

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:PutObject",
            "Resource": [
                "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET1",
                "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET1/*"
            ],
            "Condition": {
                "NumericGreaterThan": {
                    "s3:TlsVersion": 1.1
                }
            }
        }
    ]
}
					

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.

Example 1: Granting a user permission to create a bucket only in a specific Region

Suppose that an Amazon Web Services 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.

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

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

Add explicit deny

The preceding policy restricts the user from creating a bucket in any other Region except sa-east-1. However, some other policy might grant this user permission to create buckets in another Region. For example, if the user belongs to a group, the group might have a policy attached to it that allows all users in the group permission to create buckets in another Region. To ensure that the user does not get permission to create buckets in any other Region, you can add an explicit deny statement in the above policy.

The Deny statement uses the StringNotLike condition. That is, a create bucket request is denied if the location constraint is not sa-east-1. The explicit deny does not allow the user to create a bucket in any other Region, no matter what other permission the user gets. The below policy includes an explicit deny statement.

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

Test the policy with the Amazon CLI

You can test the policy using the following create-bucket Amazon CLI command. This example uses the bucketconfig.txt file to specify the location constraint. Note the Windows file path. You 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 Amazon CLI, see Developing with Amazon S3 using the Amazon CLI.

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.

{"LocationConstraint": "sa-east-1"}

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-cn:s3:::awsexamplebucket1",
         "Condition" : {
             "StringEquals" : {
                 "s3:prefix": "projects" 
             }
          } 
       },
      {
         "Sid":"statement2",
         "Effect":"Deny",
         "Action": "s3:ListBucket",
         "Resource": "arn:aws-cn: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-cn:iam::123456789012:user/bucket-owner"
         },  
         "Action":  "s3:ListBucket",
         "Resource": "arn:aws-cn:s3:::awsexamplebucket1",
         "Condition" : {
             "StringEquals" : {
                 "s3:prefix": "projects" 
             }
          } 
       },
      {
         "Sid":"statement2",
         "Effect":"Deny",
         "Principal": {
            "AWS": "arn:aws-cn:iam::123456789012:user/bucket-owner"
         },  
         "Action": "s3:ListBucket",
         "Resource": "arn:aws-cn:s3:::awsexamplebucket1",
         "Condition" : {
             "StringNotEquals" : {
                 "s3:prefix": "projects"  
             }
          } 
       }         
    ]
}

Test the policy with the Amazon CLI

You can test the policy using the following list-object Amazon CLI command. In the command, you provide user credentials using the --profile parameter. For more information about setting up and using the Amazon CLI, see Developing with Amazon S3 using the Amazon 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.