Bucket Policies

Bucket policies provide centralized access control to buckets and objects based on a variety of conditions, including OBS operations, requesters, resources, and elements (for example IP addresses) of the request. The permissions granted to a bucket apply to all the objects in that bucket.

Individuals as well as companies can use bucket policies. When a company registers with OBS, they create an account. Thereafter, the company becomes synonymous with the account. Accounts are financially responsible for the OBS resources they (and their employees) create. Accounts have the power to grant bucket policy permissions and assign employees permissions based on a variety of conditions. For example, an account can create a policy that gives a user the write permission:

  • To an account's particular bucket
  • To an account in a particular network
  • To an account's custom applications

Different from ACLs which can add (grant) permissions only on individual objects, bucket policies can either add or deny permissions on all objects within a bucket. With one request, an account can set permissions for any number of objects in a bucket. An account can use wildcards (similar to regular expression operators) on Amazon resource names (ARNs) and other values, so that an account can control access to a group of objects.

A bucket owner can perform the PUT Bucket Policy operation to set a bucket access policy. However, a new policy will override the existing one. A bucket owner can also perform the GET Bucket Policy or DELETE Bucket Policy operation to obtain or delete a bucket policy. After a policy is set for a bucket, all subsequent accesses to the bucket are controlled by the policy. Requests for accessing the bucket are accepted or denied based on the policy.

In the following bucket policy example, accounts 783fc6652cf246c096ea836694f71855 (domain ID) and 219d520ceac84c5a98b237431a2cf4c2 (domain ID) are granted the GetObject permission for all objects in mybucket.

{
  "Version":"2008-10-17",
  "Id":"aaaa-bbbb-cccc-dddd",
  "Statement" : [
     {
      "Effect":"Allow",
      "Sid":"1", 
      "Principal" : {
        "AWS":["arn:aws:iam::783fc6652cf246c096ea836694f71855:root","arn:aws:iam::219d520ceac84c5a98b237431a2cf4c2:root"]
      },
      "Action":["s3:GetObject"],
      "Resource":"arn:aws:s3:::mybucket/*"
     }
  ] 
}

Policy Format

A policy is described in the JSON format, as shown in the following syntax:

{
"Version" : "version",
"Id" : "id",
"Statement" : [statement]
}

The Id and Version parameters are optional.

Table 1 Policy

Element

Description

Id

Indicates the ID of a policy. The value is a string that describes the policy.

Version

Must be 2008-10-17. It is an optional key word.

A policy can contain multiple statements and each statement contains the following elements:

Table 2 Statement elements

Element

Description

Required

Sid

Indicates the ID of a statement. The value is a string that describes the statement.

No

Principal

Indicates the grantee of a statement. The value can be a wildcard character (*) that indicates all users. When the grantee is a domain, Principal is in the AWS:domainidAWS:arn:aws:iam::domainid:root, or CanonicalUser:domainid format. When the grantee is a user, Principal is in the AWS:arn:aws:iam::domainid:user/userId or AWS:arn:aws:iam::domainid:user/userName format.

No. Select either Principal or NotPrincipal.

NotPrincipal

Indicates an exception to a list of principals in the statement. You can deny access to all principals except the one named in the NotPrincipal element. The value of this element is similar to that of Principal.

No. Select either NotPrincipal or Principal.

Action

Indicates operations that a grantee can perform. The value is a case-insensitive string consisting of a set of operations supported by OBS.

The value can be a wildcard character (*) that indicates all operations.

Example:

"Action":["s3:List*", "s3:Get*"]

No. Select either Action or NotAction.

NotAction

Indicates an exception to a list of actions in the statement. All actions are performed except the one specified in NotAction. The value of this element is similar to Action.

No. Select either Action or NotAction.

Effect

Indicates whether permission in a statement is Allow or Deny.

Yes

Resource

Indicates resources that the statement covers. A resource is defined in the ARN format. You can use a wildcard character (*) to represent all resources.

No. Select either Resource or NotResource.

NotResource

Indicates an exception to a list of resources in the statement. A policy is not applied to resources specified in NotResource. The value of this parameter is similar to that of Resource.

No. Select either Resource or NotResource.

Condition

Indicates the conditions for a statement to take effect.

No

NOTE:

A statement contains either:

  • Action or NotAction
  • Resource or NotResource
  • Principal or NotPrincipal

In OBS, Action can be the following operations on buckets:

  • s3:CreateBucket
  • s3:DeleteBucket
  • s3:ListBucket
  • s3:ListBucketVersions
  • s3:ListBucketMultipartUploads
  • s3:GetBucketAcl
  • s3:PutBucketAcl
  • s3:GetBucketCORS
  • s3:PutBucketCORS
  • s3:GetBucketVersioning
  • s3:PutBucketVersioning
  • s3:GetBucketLocation
  • s3:GetBucketPolicy
  • s3:DeleteBucketPolicy
  • s3:PutBucketPolicy
  • s3:GetBucketLogging
  • s3:PutBucketLogging
  • s3:GetBucketWebsite
  • s3:PutBucketWebsite
  • s3:DeleteBucketWebsite
  • s3:GetLifecycleConfiguration
  • s3:PutLifecycleConfiguration

In OBS, Action can be the following operations on objects:

  • s3:GetObject (applicable to GET Object and HEAD Object)
  • s3:GetObjectVersion
  • s3:PutObject (applicable to PUT Object, POST Object, Initiate Multipart Upload, Upload Part, and Complete Multipart Upload)
  • s3:GetObjectAcl
  • s3:GetObjectVersionAcl
  • s3:PutObjectAcl
  • s3:PutObjectVersionAcl
  • s3:DeleteObject
  • s3:DeleteObjectVersion
  • s3:ListMultipartUploadParts
  • s3:AbortMultipartUpload
  • s3:RestoreObject

OBS supports S3 resources in the ARN format:

  • arn:aws:s3:::bucketname (operations on buckets)
  • arn:aws:s3:::bucketname/path/objectname (operations on objects)

The following policy grants all permissions (including bucket and object operations) for bucket examplebucket to 71f3901173514e6988115ea2c26d1999 (user ID) in b4bf1b36d9ca43d984fbcb9491b6fce9 (domain ID).

{
    "Statement":[
    {
      "Sid":"test",
      "Effect":"Allow",
      "Principal": {"AWS": ["arn:aws:iam::b4bf1b36d9ca43d984fbcb9491b6fce9:user/71f3901173514e6988115ea2c26d1999"]},
      "Action":["s3:*"],
      "Resource":[
        "arn:aws:s3:::examplebucket/*",
        "arn:aws:s3:::examplebucket"
      ]
    }
  ]
}

or

{ 
    "Statement":[ 
    { 
      "Sid":"test", 
      "Effect":"Allow", 
      "Principal": {"AWS": ["arn:aws:iam::b4bf1b36d9ca43d984fbcb9491b6fce9:user/user1"]}, 
      "Action":["s3:*"], 
      "Resource":[ 
        "arn:aws:s3:::examplebucket/*", 
        "arn:aws:s3:::examplebucket" 
      ] 
    } 
  ] 
}
NOTE:

If you do not specify a path when uploading an object, omit /path in the ARN.

Table 3 lists the general types of Condition that you can specify.

Table 3 Condition

Type

Element

Description

String

StringEquals

Strict matching

Short version: streq

StringNotEquals

Strict negated matching

Short version: strneq

StringEqualsIgnoreCase

Strict matching, ignoring case

Short version: streqi

StringNotEqualsIgnoreCase

Strict negated matching, ignoring case

Short version: strneqi

StringLike

Loose case-insensitive matching. The values can include a multi-character match wildcard (*) or a single-character match wildcard (?) anywhere in the string.

Short version: strl

StringNotLike

Negated loose case-insensitive matching. The values can include a multi-character match wildcard (*) or a single-character match wildcard (?) anywhere in the string.

Short version: strnl

Numeric

NumericEquals

Strict matching

Short version: numeq

NumericNotEquals

Strict negated matching

Short version: numneq

NumericLessThan

"Less than" matching

Short version: numlt

NumericLessThanEquals

"Less than or equals" matching

Short version: numlteq

NumericGreaterThan

"Greater than" matching

Short version: numgt

NumericGreaterThanEquals

"Greater than or equals" matching

Short version: numgteq

Date

DateEquals

Strict matching

Short version: dateeq

DateNotEquals

Strict negated matching

Short version: dateneq

DateLessThan

"Less than" matching

Short version: datelt

DateLessThanEquals

"Less than or equals" matching

Short version: datelteq

DateGreaterThan

"Greater than" matching

Short version: dategt

DateGreaterThanEquals

"Greater than or equals" matching

Short version: dategteq

Boolean

Bool

Strict Boolean matching

IP address

IpAddress

Specified IP address or IP address range

NotIpAddress

All IP addresses exclude the specified IP address or IP address range

NOTE:

Elements in Condition are case-sensitive. Date conditions must comply with ISO 8601 specifications. For details, see http://www.w3.org/TR/NOTE-datetime.

A Condition block (element) can contain multiple key value pairs. The following example Condition block specifies requests initiated between 2009-04-16T12:00:00Z and 2009-04-16T15:00:00Z from IP addresses on network segment 192.168.176.0/24 or 192.168.143.0/24:

"Condition" : {
  "DateGreaterThan" : {
  "aws:CurrentTime" : "2009-04-16T12:00:00Z"
  },
  "DateLessThan": {
  "aws:CurrentTime" : "2009-04-16T15:00:00Z"
  },
  "IpAddress" : {
  "aws:SourceIp" : ["192.168.176.0/24","192.168.143.0/24"]
  }
}

A Condition block can contain two types of keys:

  • General keys irrelevant to Action.
  • Keys associated with Action.

Table 4 lists keys irrelevant to Action.

Table 4 Common Condition Key

Condition Key

Condition Type

aws:CurrentTime

Date

aws:EpochTime

Numeric

aws:SecureTransport

Bool

aws:SourceIp

IP address

aws:UserAgent

String

aws:Referer

String

Table 5 lists the OBS service-specific keys.

Table 5 OBS Action Condition Key

Action

Key

Description

s3:CreateBucket

s3:x-amz-acl

x-amz-acl can contain the canned ACL.

Valid values: private| public-read| public-read-write|authenticated-read|bucket-owner-read|bucket-owner-full-control|log-delivery-write

s3:x-amz-grant-permission

Not supported

s3:LocationConstraint

Not supported

s3:ListBucket

s3:prefix

String

s3:delimiter

String

s3:max-keys

Numeric

s3:ListBucketVersions

s3:prefix

String

s3:delimiter

String

s3:max-keys

Numeric

s3:PutBucketAcl

s3:x-amz-acl

x-amz-acl can contain the canned ACL.

Valid values: private| public-read| public-read-write|authenticated-read|bucket-owner-read|bucket-owner-full-control|log-delivery-write

s3:x-amz-grant-permission

Not supported

s3:PutObject

s3:x-amz-acl

x-amz-acl can contain the canned ACL.

Valid values: private| public-read| public-read-write|authenticated-read|bucket-owner-read|bucket-owner-full-control|log-delivery-write

s3:x-amz-copy-source

String

Format:

/bucketname/keyname

s3:x-amz-metadata-directive

Valid values: COPY| REPLACE

s3:x-amz-grant-permission

Not supported

s3:x-amz-storage-class

Not supported

s3:PutObjectAcl

s3:x-amz-acl

x-amz-acl can contain the canned ACL.

Valid values: private| public-read| public-read-write|authenticated-read|bucket-owner-read|bucket-owner-full-control|log-delivery-write

s3:x-amz-grant-permission

Not supported

s3:GetObjectVersion

s3:VersionId

String

s3:GetObjectVersionAcl

s3:VersionId

String

s3:PutObjectVersionAcl

s3:VersionId

String

s3:x-amz-acl

x-amz-acl can contain the canned ACL.

Valid values: private| public-read| public-read-write|authenticated-read|bucket-owner-read|bucket-owner-full-control|log-delivery-write

s3:x-amz-grant-permission

Not supported

s3:DeleteObjectVersion

s3:VersionId

String

s3:*

(Actions or any of the S3 Actions)

s3:signatureversion

Not supported

s3:authType

Not supported

s3:signatureAge

Not supported

s3:x-amz-content-sha256

Not supported

Policy Permission Judgment Logic

A policy may pose any of the three results for each statement: explicit denyallow, and default deny. If a bucket policy contains multiple statements, the policy determines which statement prevails according to the following rules:

1. If conditions in any statement of a policy are not met, the policy poses a default deny result.

2. An explicit deny overrides allows.

3. An allow overrides default denies.

4. Statements can be in any order in a policy.

Table 6 Statement Result

Name

Description

explicit deny

A statement defines effect="deny".

All requests for resources to which the statement applies are denied. No permission is returned.

allow

A statement defines effect="allow".

All requests for resources to which the statement applies are allowed.

default deny

Conditions defined in a statement are not met. Requests are denied.

URL Validation Settings

OBS is charged based on usage. To prevent user data from being stolen, OBS supports URL validation based on HTTP headers. OBS also supports both whitelist and blacklist settings.

  • Whitelist settings

    Users can set a whitelist to allow requests from the websites added in the whitelist and deny requests from any other website.

    For the requests that are initialized from browsers' address boxes, that is, those HTTP requests with a blank referer, users can add the ${null} field to "aws:Referer" of Condition to specify whether to allow the requests with a blank referer.

    Set a whitelist based on the following policy setting:

    "Statement":[
        {"Sid": "1",
         "Effect": "Allow",
         "Principal": {"CanonicalUser":["*"]},
         "Action": "s3:*",
         "Resource":["arn:aws:s3:::bucket/*"],
        },
        {"Sid":"2",
         "Effect":"Deny",
         "Principal":{"CanonicalUser":["*"]},
         "Action":["s3:*"],
         "Resource":["arn:aws:s3:::bucket/*"],                             "Condition":{
             "StringNotEquals":
             {"aws:Referer":["www.example01.com","${null}"]}
          }
        }
    ]

    If you set a whitelist in this way, you can perform operations on resources in buckets only when the value of the referer parameter is www.example01.com or is blank.

  • Blacklist settings

    You can refer to the following policy settings to set a blacklist for access.

    "Statement":[
        {"Sid":"1",
         "Effect":"Deny",
         "Principal":{"CanonicalUser":["*"]},
         "Action":["s3:*"],
         "Resource":["arn:aws:s3:::bucket/*"],                             
         "Condition":{
             "StringEquals":
                {"aws:Referer":["www.example01.com","www.example02.com"]}
          }
        }
    ]

    If you set a blacklist in this way, you cannot perform operations on resources in buckets when the value of the referer parameter is www.example01.com or www.example02.com.

Registration