Help Center> Object Storage Service> Developer Guide> Permission Control> Bucket Policy> Policy Format
View PDF

Policy Format

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

{ 
"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 can consist of multiple statements or one statement. The structure of each statement contains the following contents:

Table 1 Statement elements

Element

Description

Mandatory

Sid

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

No

Principal

Optional keyword. Grantee of a statement. The value can be a wildcard character (*) that indicates all domains and users. When authorizing permissions to all users under a domain, the format of Principal is domain/domainid:user/*. When authorizing permissions to a specific user under a domain, the format of Principal is domain/domainid:user/userId or domain/domainid:user/userName.

No. 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. The value format is the same as Principal.

No. Select either NotPrincipal or Principal.

Action

Specifies the operation to which the statement applies. This parameter is optional. The Action field is a set of all operations supported by OBS. It is a string of case-insensitive characters, and supports a wildcard character (*) that indicates all operations. For example: "Action":["List*","Get*"].

No. Select either Action or NotAction.

NotAction

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

Specifies a group of resources on which the statement takes effect. The wildcard * is supported, indicating all resources.

No. Select either Resource or NotResource.

NotResource

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

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

Principal / NotPrincipal

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

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

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

  • Specific account

    When the account identifier is used as the authorizer in the policy, the permission in the policy statement can be granted to all roles contained in the account. This includes all subscribers under the account. The following example demonstrates how to specify an account as an authorized person.

    "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 user

    In the Principal element, the user name is case sensitive.

    "Principal": {"ID": "domain/domainIDxxx:user/user-name" }
"Principal": {
  "ID": [
    "domain/domainIDxxx:user/UserID1", 
    "domain/domainIDxxx:user/UserID2"
  ]
}
  • Federated user (using SAML identity provider) 
    "Principal": { "Federated": "domain/domainIDxxx:identity-provider/provider-name" }
"Principal": { "Federated": "domain/domainIDxxx:group/groupname" }
  • Agencies 
    "Principal": { "ID": "domain/domainIDxxx:agency/agencyname" }

Action / NotAction

OBS supports the following bucket Action or NotAction:

  • CreateBucket
  • DeleteBucket
  • HeadBucket
  • ListBucket
  • ListBucketVersions
  • ListBucketMultipartUploads
  • GetBucketAcl
  • PutBucketAcl
  • GetBucketCORS
  • PutBucketCORS
  • GetBucketVersioning
  • PutBucketVersioning
  • GetBucketLocation
  • GetBucketPolicy
  • DeleteBucketPolicy
  • PutBucketPolicy
  • GetBucketLogging
  • PutBucketLogging
  • GetBucketWebsite
  • PutBucketWebsite
  • DeleteBucketWebsite
  • GetLifecycleConfiguration
  • PutLifecycleConfiguration
  • GetBucketNotification
  • PutBucketNotification
  • GetReplicationConfiguration

The object Action or NotAction supported by OBS is as follows:

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

Resource / NotResource

The resources supported by the 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 operations on the bucket, set Resource to the bucket name.
  • bucketname/objectname (object operation): The Action drop-down list box contains the Supported Object Action list. If you want to respond to an object in a bucket, set Resource to bucketname/objectname. objectname supports wildcards. For example, if you have permission on the directory object in a bucket, set Resource to "bucketname/director/*". If you have permission on all objects in a bucket, set Resource to "bucketname/*". If permissions for both buckets and objects in the bucket need to be granted, set Resource to ["examplebucket/*","examplebucket"].

The following example policy grants all operation permissions (including bucket operations and object operations) of examplebucket to user1 whose user ID is 71f3901173514e6988115ea2c26d1999 in account b4bf1b36d9ca43d984fbcb9491b6fce9 (account ID).

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

Condition

The following table lists the general types of Condition that you can specify.

Table 2 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-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

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

Indicates that the date is earlier than a specific date. Short version: datelt

DateLessThanEquals

A point in time at which a key stops taking effect. Short version: datelteq

DateGreaterThan

A point in time at which a key starts taking effect Short version: dategt

DateGreaterThanEquals

A point in time at which a key starts taking effect. Short version: dategteq

Boolean

Bool

Strict Boolean matching

IP address

IpAddress

Approved based IP address or range

NotIpAddress

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

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

Each Condition block can contain multiple key-value combinations. 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"] 
  } 
}

A Condition block can contain two types of keys: general keys that have nothing to do with Action and Action related keys.

Keys irrelevant to Action are listed as follows:

Table 3 Common Condition Key

Condition Key

Condition Type

CurrentTime

Date

EpochTime

Numeric

SecureTransport

Bool

SourceIp

IP address

UserAgent

String

Referer

String

Keys in Condition must be used in certain actions. The following table lists the key pairs in Action and Condition.

Table 4 OBS Action Condition Key

Action

Optional Key

Description

CreateBucket

x-obs-acl

When a bucket is created, the value range of Canned ACL in the x-obs-acl header field is private| public-read| public-read-write | public-read-delivered | public-read-write-delivered.

ListBucket

prefix

String

delimiter

String

max-keys

Numeric

ListBucketVersions

prefix

String

delimiter

String

max-keys

Numeric

PutBucketAcl

x-obs-acl

When the bucket ACL is modified, the value range of Canned ACL in the x-obs-acl header field is private| public-read | public-read-write | public-read-delivered | public-read-write-delivered.

PutObject

x-obs-acl

When an object is uploaded, the value range of Canned ACL in the x-obs-acl header field is private | public-read| public-read-write.

x-obs-copy-source

Type: String. Format: /bucketname/keyname

x-obs-metadata-directive

Valid values: COPY | REPLACE

PutObjectAcl

x-obs-acl

When an object is modified, the value range of Canned ACL in the x-obs-acl header field is private | public-read| public-read-write.

GetObjectVersion

VersionId

String

GetObjectVersionAcl

VersionId

String

PutObjectVersionAcl

VersionId

String

x-obs-acl

When an object version is modified, the value range of Canned ACL in the x-obs-acl header field is private | public-read| public-read-write.

DeleteObjectVersion

VersionId

String

Policy Permission Determination 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 allows.

3. An allow overrides default denies.

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

Table 5 Statement Result

Property 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.

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

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

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

Parent topic: Bucket Policy