Help Center/ Object Storage Service/ API Reference (ME-Abu Dhabi Region)/ APIs/ Advanced Bucket Settings/ Configuring a Bucket ACL
Updated on 2024-01-02 GMT+08:00
View PDF
Share

Configuring a Bucket ACL

Functions

This operation controls access permissions for buckets. By default, only the creator of a bucket has the permission to read and write the bucket. You can also set other access permissions. For example, you can set a public read policy to grant the read permission to all users.

You can configure an ACL when creating a bucket, and modify or obtain the ACLs of existing buckets using the API operations. A bucket ACL supports a maximum of 100 grants. The PUT method is idempotent. With this method, a new bucket ACL will overwrite the previous bucket ACL. To modify or delete an ACL, you just need to create a new one using the PUT method.

Request Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
 
PUT /?acl HTTP/1.1 
Host: bucketname.obs.region.example.com
Date: date
Authorization: authorization
Content-Type: application/xml 
Content-Length: length

<AccessControlPolicy> 
    <Owner> 
        <ID>ID</ID> 
    </Owner> 
    <AccessControlList> 
        <Grant> 
            <Grantee>
               <ID>domainId</ID>
            </Grantee> 
            <Permission>permission</Permission> 
            <Delivered>false</Delivered>
        </Grant>
    </AccessControlList> 
</AccessControlPolicy>

Request Parameters

This request contains no parameters.

Request Headers

You can change the ACL of a bucket by using the header settings. Each ACL configured with the header setting has a set of predefined grantees and authorized permissions. If you want to authorize access permissions by adding the header to a request, you must add the following header and specify the value.

Table 1 Optional header for specifying canned ACLs

Name

Description

Mandatory

x-obs-acl

Uses the canned ACL for a bucket.

Value options: private, public-read, public-read-write, public-read-delivered, public-read-write-delivered

Type: string

No

Request Elements

This request carries ACL information in elements to specify an ACL. Table 3 describes the elements.

Table 2 Additional request elements

Element

Description

Mandatory

Owner

Bucket owner information, including the ID

Type: XML

Yes

ID

Account ID of the authorized user

Type: string

Yes

Grant

Container for the grantee and the granted permissions A single bucket ACL can contain no more than 100 grants.

Type: XML

No

Grantee

Grantee information

Type: XML

No

Canned

Grants permissions to all users.

Value range: Everyone

Type: string

No

Delivered

Indicates whether the bucket ACL is applied to all objects in the bucket.

Type: boolean

Default value: false

No

Permission

Permissions to be granted.

Value options: READ, READ_ACP, WRITE, WRITE_ACP, FULL_CONTROL

Type: string

No

AccessControlList

Indicates an ACL, which consists of three elements: Grant, Grantee, and Permission.

Type: XML

Yes

Response Syntax

1
2
3
 
HTTP/1.1 status_code
Date: date
Content-Length: length

Response Headers

The response to the request uses common headers. For details, see Table 1.

Response Elements

This response contains no elements.

Error Responses

No special error responses are returned. For details, see Table 2.

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 
PUT /?acl HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 02:37:22 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4=
Content-Length: 727

<AccessControlPolicy xmlns="http://obs.example.com/doc/2015-06-30/">  
  <Owner> 
    <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID> 
  </Owner>  
  <AccessControlList> 
    <Grant> 
      <Grantee> 
        <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID> 
      </Grantee>  
      <Permission>FULL_CONTROL</Permission> 
    </Grant>  
    <Grant> 
      <Grantee> 
        <ID>783fc6652cf246c096ea836694f71855</ID> 
      </Grantee>  
      <Permission>READ</Permission>  
      <Delivered>false</Delivered> 
    </Grant>  
    <Grant> 
      <Grantee> 
        <Canned>Everyone</Canned> 
      </Grantee>  
      <Permission>READ_ACP</Permission> 
    </Grant> 
  </AccessControlList> 
</AccessControlPolicy>

Sample Response

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF2600000164361F2954B4D063164704
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCT78HTIBuhe0FbtSptrb/akwELtwyPKs
Date: WED, 01 Jul 2015 02:37:22 GMT
Content-Length: 0
Parent topic: Advanced Bucket Settings