Updated on 2024-05-31 GMT+08:00

Bucket Policy Parameters

A policy in JSON format is described as follows:

{ 
"Statement" : [{
     statement1
  },
  {
     statement2
  },
  ......
 ]
}
Example:
{ 
"Statement" : [{
     "Sid": "ExampleStatementID1",
     "Principal": "*",
     "Effect": "Allow",   
     "Action": ["ListBucket"],
     "Resource": "examplebucket",
     "Condition": "some conditions"
  },
  {
     "Sid": "ExampleStatementID2",
     "Principal": "*",
     "Effect": "Allow",   
     "Action": ["PutObject"],
     "Resource": "examplebucket",
     "Condition": "some conditions"
  },
......
]
}

A policy is comprised of one or more statements. Each statement contains the following elements:

Table 1 Statement elements

Element

Description

Mandatory/Optional

Sid

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

Optional

Principal

Domains and users to which a statement applies. The wildcard (*) is supported, indicating all users. When permissions are authorized to all users under a domain, the format of Principal is domain/domainid:user/*. When permissions are authorized to a specific user under a domain, the format of Principal is domain/domainid:user/userId or domain/domainid:user/userName.

Optional. Select either Principal or NotPrincipal.

NotPrincipal

An exception to a list of principals in the statement. You can deny access to all principals except the ones named in the NotPrincipal element. This parameter has the same value format as Principal.

Optional. Select either NotPrincipal or Principal.

Action

Actions which a statement applies to. This parameter specifies a set of all the operations supported by OBS. Its values are case insensitive. The value supports a wildcard character (*) that indicates all actions, for example, "Action":["List*", "Get*"].

Optional. Select either Action or NotAction.

NotAction

An exception to a list of actions in the statement. All actions are performed except the ones specified in NotAction. This parameter has the same value format as Action.

Optional. Select either Action or NotAction.

Effect

Whether the permission in a statement is allowed or denied. The value is Allow or Deny.

Mandatory

Resource

Resources on which the statement takes effect. The wildcard (*) is supported, indicating all resources.

Optional. Select either Resource or NotResource.

NotResource

An exception to a list of resources in a statement. A policy is not applied to the resources specified in NotResource. This parameter has the same value format as Resource.

Optional. Select either Resource or NotResource.

Condition

Conditions for a statement to take effect.

Optional

A statement must contain either Action or NotAction, either Resource or NotResource, and either Principal or NotPrincipal.

Principal/NotPrincipal

Principal or NotPrincipal supported by OBS includes anonymous users, specific tenants, specific users, federated users, and agencies.

  • All (anonymous users)
    "Principal": {"ID": "*"}

    In the example, the wildcard (*) is used as a placeholder for Everyone/Anonymous. We strongly recommend that you do not use wildcards in the Principal element of the role's trust policy unless you have restricted access by using the Condition element in the policy.

  • Specific tenants

    If the tenant identifier is used as the authorizer in the policy, permissions in the policy statement can be granted to all roles, including all the users, contained in this tenant. The following example demonstrates how to specify a tenant as an authorizer.

    "Principal": { "ID": " domain/domainIdxxxx:user/*" }

    You can grant permissions to multiple tenants, as described in the following example:

    "Principal": { 
      "ID": [
        "domain/domainIDxx1:user/useridxxxx",
        "domain/domainIDxx2:user/*"
      ]
    }
  • Specific users

    In the Principal element, user names are case sensitive.

    "Principal": {"ID": "domain/domainIDxxx:user/user-name" }
    "Principal": {
      "ID": [
        "domain/domainIDxxx:user/UserID1", 
        "domain/domainIDxxx:user/UserID2"
      ]
    }
  • Federated users (using SAML identity provider)
    "Principal": { "Federated": "domain/domainIDxxx:identity-provider/provider-name" }
    "Principal": { "Federated": "domain/domainIDxxx:group/groupname" }
  • Agencies
    * indicates all agencies of a tenant.
    "Principal": { "ID": "domain/domainIDxxx:agency/agencyname" }
    "Principal": { "ID": "domain/domainIDxxx:agency/*" }

The principals on OBS Console refer to the users which the bucket policies apply to. These users can be accounts and IAM users. Principals can be specified in either of the following ways:

  • Include: The policy applies to specified users.
  • Exclude: The policy applies to users except the specified ones.

Specifying IAM users under the current account

With Principal set to Current account, you can select one or more users for IAM user, so the bucket policy applies to the selected IAM users under this account.

Specifying another account

With Principals set to Other accounts, you can enter one or more account IDs. If you want to apply the bucket policy to only the IAM users under that account, enter one or more IAM user IDs.

To obtain the account ID and IAM user ID, log in to the console as an IAM user and go to the My Credentials page.

Specifying anonymous users

To grant the bucket access to anyone, set Principal to Anonymous user.

Exercise caution when granting bucket access permissions to anonymous users. If you grant the access permissions to anonymous users, anyone can access your bucket, and all the traffic and storage fees incurred will be borne by the bucket owner. You are advised to set restrictions on access requests. For example, you can allow the access requests from only one IP address.

Action/NotAction

If a policy applies to a bucket, configure bucket-related actions; if the policy applies to the objects in a bucket, configure object-related actions.

Actions can be specified in either of the following ways:

  • Include: The bucket policy applies to specified actions.
  • Exclude: The bucket policy applies to actions except the specified ones.

Bucket Actions

Table 2 Action description

Type

Value

Description

General

*

Indicates that all operations can be performed on a resource.

Get*

Indicates that all GET operations can be performed on a resource.

Put*

Indicates that all PUT operations can be performed on a resource.

List*

Indicates that all LIST operations can be performed on a resource.

Bucket

HeadBucket

Checks whether a bucket exists and obtains the bucket metadata.

CreateBucket

Creates a bucket.

DeleteBucket

Deletes a bucket.

ListBucket

Lists objects in a bucket, and obtains the bucket metadata.

ListBucketVersions

Lists versioned objects in a bucket.

ListBucketMultipartUploads

Lists multipart upload tasks.

GetBucketAcl

Gets the bucket ACL information.

PutBucketAcl

Configures a bucket ACL.

GetBucketCORS

Gets the CORS configuration of a bucket.

PutBucketCORS

Configures CORS for a bucket.

GetBucketVersioning

Gets the bucket versioning information.

PutBucketVersioning

Configures versioning for a bucket.

GetBucketLocation

Gets the bucket location.

GetBucketLogging

Gets the bucket logging information.

PutBucketLogging

Configures logging for a bucket.

GetBucketWebsite

Obtains the static website configuration information of a bucket.

PutBucketWebsite

Configures static website hosting for a bucket.

DeleteBucketWebsite

Cancels the static website hosting of a bucket.

GetLifecycleConfiguration

Obtains the lifecycle rules of a bucket.

PutLifecycleConfiguration

Configures a lifecycle rule for a bucket.

GetBucketInventoryConfiguration

Gets the inventory configuration of a bucket.

PutBucketInventoryConfiguration

Configures inventories for a bucket.

DeleteBucketInventoryConfiguration

Deletes the inventory configuration of a bucket.

PutBucketPolicy

Configures a bucket policy.

NOTE:

Granting this permission is risky.

Users with the PutBucketPolicy permission can modify bucket policies and can use this permission to further obtain other permissions, including deleting bucket policies.

GetBucketPolicy

Gets a bucket policy.

DeleteBucketPolicy

Deletes a bucket policy.

PutBucketNotification

Configures event notifications for a bucket.

GetBucketNotification

Gets event notifications of a bucket.

PutBucketStoragePolicy

Configures the default storage class for a bucket.

GetBucketStoragePolicy

Gets the default storage class of a bucket.

PutReplicationConfiguration

Configures cross-region replication for a bucket.

GetReplicationConfiguration

Gets the cross-region replication configuration of a bucket.

DeleteReplicationConfiguration

Deletes the cross-region replication configuration of a bucket.

PutBucketTagging

Configures tags for a bucket.

GetBucketTagging

Gets bucket tags.

DeleteBucketTagging

Deletes bucket tags.

PutBucketQuota

Configures bucket storage quota.

GetBucketQuota

Gets bucket storage quota.

PutBucketCustomDomainConfiguration

Binds a user-defined domain name to a bucket.

GetBucketCustomDomainConfiguration

Gets the custom domain name of a bucket.

DeleteBucketCustomDomainConfiguration

Unbinds a user-defined domain name from a bucket.

PutDirectColdAccessConfiguration

Configures direct reading for a bucket.

GetDirectColdAccessConfiguration

Gets the direct reading configuration of a bucket.

DeleteDirectColdAccessConfiguration

Deletes the direct reading configuration of a bucket.

GetEncryptionConfiguration

Gets the default encryption configuration of a bucket.

PutEncryptionConfiguration

Configures default encryption for a bucket.

Object Actions

Table 3 Action description

Type

Value

Description

General

*

Indicates that all operations can be performed on a resource.

Get*

Indicates that all GET operations can be performed on a resource.

Put*

Indicates that all PUT operations can be performed on a resource.

List*

Indicates that all LIST operations can be performed on a resource.

Object

GetObject

Gets the content and metadata of an object.

GetObjectVersion

Gets the content and metadata of a specified object version.

PutObject

Performs PUT upload, POST upload, multipart upload, initialization of uploaded parts, and merging of parts.

GetObjectAcl

Gets the object ACL information.

GetObjectVersionAcl

Gets the ACL information of a specified object version.

PutObjectAcl

Configures the ACL for an object.

PutObjectVersionAcl

Configures the ACL for a specified object version.

DeleteObject

Deletes an object.

DeleteObjectVersion

Deletes a specified object version.

ListMultipartUploadParts

Lists uploaded parts.

AbortMultipartUpload

Cancels a multipart upload.

RestoreObject

Restores an object from Archive storage class.

ModifyObjectMetadata

Modifies object metadata.

Resource/NotResource

The resources supported by OBS are as follows:

  • bucketname (bucket operation): The Action drop-down list box contains the list of supported bucket actions. If you want to perform the listed operations on the bucket, set Resource to the bucket name.
  • bucketname/objectname (object operation): The Action drop-down list box contains the list of supported object actions. If you want to respond to an object in a bucket, set Resource to bucketname/objectname. objectname supports wildcards. For example, if you have permissions on the directory object in a bucket, set Resource to "bucketname/directory/*". If you have permissions on all the objects in a bucket, set Resource to "bucketname/*". If permissions for both a bucket and its objects need to be granted, set Resource to ["examplebucket/*","examplebucket"].

The following example policy grants all operation permissions on examplebucket (including the bucket and its objects) to user1 whose user ID is 71f3901173514e6988115ea2c26d1999 under account b4bf1b36d9ca43d984fbcb9491b6fce9 (account ID).

{ 
    "Statement":[ 
    { 
      "Sid":"test", 
      "Effect":"Allow", 
      "Principal": {"ID": ["domain/b4bf1b36d9ca43d984fbcb9491b6fce9:user/71f3901173514e6988115ea2c26d1999"]}, 
      "Action":["*"], 
      "Resource":["examplebucket/*","examplebucket"]
    } 
  ] 
}

On OBS Console, you can apply a bucket policy to the following resources: the current bucket, and all objects in a bucket.

Resources can be specified in either of the following ways:

  • Include: The bucket policy applies to specified OBS resources.
  • Exclude: The bucket policy applies to OBS resources except the specified ones.

Applying a bucket policy to a bucket

To apply a bucket policy to the current bucket, keep the resource text box empty. When configuring actions for the policy, select bucket related actions.

Applying a bucket policy to specified objects

To apply the bucket policy to specified objects in a bucket, object-related actions must be configured in the policy. The configuration format is as follows:

  • For an object, enter the object name (including its folder name if any). For example, if the specified resource is the example.jpg file in the imgs-folder folder in the bucket, enter the following content in the resource text box:

    imgs-folder/example.jpg

  • For an object set, the wildcard asterisk (*) should be used. The asterisk (*) indicates an empty string or any combination of multiple characters. The format rules are as follows:
    • Use only one asterisk (*) to indicate all objects in a bucket.
    • Use Object name prefix* to indicate objects starting with this prefix in a bucket. Example:

      imgs*

    • Use *Object name suffix to indicate objects ending with this suffix in a bucket. Example:

      *.jpg

Condition

In addition to the effect, principals, resources, and actions, you can also specify the conditions under which a bucket policy takes effect. The bucket policy takes effect only when its condition expressions match values contained in the request. Conditions are optional. You can choose whether to configure them.

For example, if account A needs to have full control over an object uploaded by account B to bucket example of account A, the x-obs-acl key must be specified in the upload request and the policy effect must be set to Allow for account A. The complete condition expression is as follows:

Condition Operator

Key

Value

StringEquals

x-obs-acl

bucket-owner-full-control

A condition consists of three parts: condition operator, key, and value. If there are multiple identical keys in the same condition operator, only the last key is retained. Condition operators and keys are mutually restricted. If you select a condition operator of the string type, for example, StringEquals, the key can only be of the string type, for example, UserAgent. Likewise, if a key of the date type is selected, for example, CurrentTime, the condition operator can only be of the date type, for example, DateEquals.

  • Condition operators

    A condition operator, a condition key, and a condition value together constitute a complete condition statement. A policy can be applied only when its request conditions are met. Table 4 lists the condition operators available for statements. String condition operators are not case-sensitive unless otherwise specified.

Table 4 Condition operators

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-sensitive 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-sensitive 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

Numeric indicates a data type expressed in numbers.

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

The date is earlier than a specific date. Short version: datelt

DateLessThanEquals

The date is earlier than or equal to a specific date. Short version: datelteq

DateGreaterThan

The date is later than a specific date. Short version: dategt

DateGreaterThanEquals

The date is later than or equal to a specific date. Short version: dategteq

Boolean

Bool

Strict Boolean matching

IP address

IpAddress

Specified IP address or IP address range

NotIpAddress

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

Elements in a condition are case sensitive. The date format complies with the ISO 8601 standard, for example, 2015-07-01T12:00:00Z.

Each condition can contain multiple key-value pairs. The Condition combination in the following figure indicates that the request time ranges from 2015-07-01T12:00:00Z to 2018-04-16T15:00:00Z and the request IP address range is 192.168.176.0/24 or 192.168.143.0/24.

"Condition" : { 
  "DateGreaterThan" : { 
  "CurrentTime" : "2015-07-01T12:00:00Z" 
  }, 
  "DateLessThan": { 
  "CurrentTime" : "2018-04-16T15:00:00Z" 
  }, 
  "IpAddress" : { 
  "SourceIp" : ["192.168.176.0/24","192.168.143.0/24"] 
  } 
}
  • Condition keys

Keys in a condition can be classified into three types: general keys, keys related to bucket actions, and keys related to object actions.

The following table lists the keys that are not related to actions.

Table 5 General keys

Key

Type

Description

CurrentTime

Date

Date when the request is received by the server. The date format must comply with ISO 8601.

EpochTime

Numeric

Time when the request is received by the server, which is expressed as seconds since 1970.01.01 00:00:00 UTC, regardless of the leap seconds

SecureTransport

Bool

Whether requests are encrypted using SSL

NOTE:

The value can be either true or false. Any other values you enter will become false by default.

SourceIp

IP address

Source (client) IP address of the request

UserAgent

String

Requested client software agent

Referer

String

Link from which the request is sent

Keys in a condition must be used in certain actions. The following table lists the mapping between actions and the keys in a condition.

Table 6 Keys related to bucket actions

Action

Optional Key

Description

Remarks

ListBucket

prefix

Type: String. Lists objects that begin with the specified prefix.

If prefix, delimiter, and max-keys are configured, the key-value pair meeting the conditions must be specified in the List operation for the bucket policy to take effect.

For example, if a bucket policy (with the condition operator set to NumericEquals, the key to max-keys, and the value to 100) that allows anonymous users to read data is configured for a bucket, the anonymous users must add ?max-keys=100 to the end of the bucket domain name for listing objects. The listed objects are the first 100 objects in alphabetic order.

delimiter

Type: String. Groups objects in a bucket.

max-keys

Type: Numeric. Sets the maximum number of objects. Returned objects are listed in alphabetic order.

ListBucketVersions

prefix

Type: String. Lists multi-version objects whose name starts with the specified prefix.

delimiter

Type: String. Groups objects of different versions in a bucket.

max-keys

Type: Numeric. Sets the maximum number of objects. Returned objects are listed in alphabetic order.

PutBucketAcl

x-obs-acl

Type: String. Configures the bucket ACL. When modifying a bucket ACL, you can use the request that contains a canned ACL setting in its header. Value options of a canned ACL setting: private|public-read|public-read-write|bucketowner-read|log-delivery-write.

None

Table 7 Keys related to object actions

Action

Optional Key

Description

PutObject

x-obs-acl

Type: String. Configures the object ACL. When uploading an object, you can use the request that contains a canned ACL setting in its header. Value options of a canned ACL setting: private|public-read|public-read-write|bucketowner-read|bucket-owner-full-control|log-delivery-write.

x-obs-copy-source

Type: String. Specifies names of the source bucket and the source object. Format: /bucketname/keyname

x-obs-metadata-directive

Type: String. Specifies whether to copy the metadata from the source object or replace with the metadata in the request. The value can be COPY or REPLACE.

x-obs-server-side-encryption

Type: String. Specifies that objects in a bucket are encrypted using SSE-KMS before they are stored. The value is kms.

PutObjectAcl

x-obs-acl

Type: String. Configures the object ACL. When uploading an object, you can use the request that contains a canned ACL setting in its header. Value options of a canned ACL setting: private|public-read|public-read-write|bucketowner-read|bucket-owner-full-control|log-delivery-write.

GetObjectVersion

versionId

Type: String. Obtains the object with the specified version ID.

GetObjectVersionAcl

versionId

Type: String. Obtains the ACL of the object with the specified version ID.

PutObjectVersionAcl

versionId

Type: String. Specifies a version ID.

x-obs-acl

Type: String. Configures the ACL of the object with the specified version ID. When uploading an object, you can use the request that contains a canned ACL setting in its header. Value options of a canned ACL setting: private|public-read|public-read-write|bucketowner-read|bucket-owner-full-control|log-delivery-write.

DeleteObjectVersion

versionId

Type: String. Deletes the object with the specified version ID.

Policy Permission Judgment Logic

A policy may pose any of the three results for each statement: Explicit Deny, Allow, 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 an allow.

3. An allow overrides a default deny.

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

Table 8 Statement results

Result

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.

If an ACL and a bucket policy are applied together to an account, an explicit deny in the bucket policy overrides the allow in the ACL.

If a bucket policy and an IAM policy are applied together to an account, an explicit deny overrides the allow, and an allow overrides the default deny.

SSE-KMS server-side encrypted object does not support Bucket ACL/Policy for cross-tenant authorization.