Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon S3 condition keys

The access policy language enables you to specify conditions when granting permissions. To specify conditions for when a policy is in effect, you can use the optional Condition element, or Condition block, to specify conditions for when a policy is in effect. You can use predefined Amazon‐wide keys and Amazon S3‐specific keys to specify conditions in an Amazon S3 access policy.

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. For example, when granting a user permission to upload an object, the bucket owner can require that the object be publicly readable by adding the StringEquals condition, as shown here.

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

In the example, 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 that you can use in expressing a condition. The example uses the s3:x-amz-acl condition key. This condition requires the user to include the x-amz-acl header with value public-read in every PUT object request.

Amazon‐wide condition keys

Amazon provides a set of common keys that are supported by all Amazon services that support policies. These keys are called Amazon‐wide keys and use the prefix aws:. For a complete list of Amazon‐wide condition keys, see Available Amazon Keys for Conditions in the IAM User Guide. You can use Amazon‐wide condition keys in 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.0.2.0.*), 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 Amazon‐wide key.

{
    "Version": "2012-10-17",
    "Id": "S3PolicyId1",
    "Statement": [
        {
            "Sid": "statement1",
            "Effect": "Allow",
            "Principal": "*",
            "Action":"s3:GetObject",
            "Resource": "arn:aws-cn:s3:::awsexamplebucket1/*",
            "Condition" : {
                "IpAddress" : {
                    "aws:SourceIp": "192.0.2.0/24" 
                },
                "NotIpAddress" : {
                    "aws:SourceIp": "192.0.2.188/32" 
                } 
            } 
        } 
    ]
} 

You can also use other Amazon‐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.

Amazon S3‐specific condition keys

You can use Amazon S3 condition keys with specific Amazon S3 actions. Each condition key maps to the same name request header allowed by the API on which the condition can be set. Amazon S3‐specific condition keys dictate the behavior of the same name request headers. For a complete list of Amazon S3‐specific condition keys, see Actions, resources, and condition keys for Amazon S3.

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.

The following bucket policy grants the s3:PutObject permission for two Amazon Web Services accounts if the request includes the x-amz-acl header making the object publicly readable. 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:.

{
    "Version":"2012-10-17",
    "Statement": [ 
        {
	        "Sid":"AddCannedAcl",
            "Effect":"Allow",
	        "Principal": {
                "AWS": [
                "arn:aws-cn:iam::Account1-ID:root",
				"arn:aws-cn:iam::Account2-ID:root"
				]
            },
	        "Action":"s3:PutObject",
            "Resource": ["arn:aws-cn:s3:::awsexamplebucket1/*"],
            "Condition": {
                "StringEquals": {
                    "s3:x-amz-acl":["public-read"]
                }
            }
        }
    ]
}