Create an access control list for a bucket

Edit online

A PUT issued to a bucket with the necessary query parameter creates or replaces an access control list (ACL) for that bucket. Access control lists allow for granting different sets of permissions to different storage accounts using the account’s ID, or by using a pre-made ACL.

ACLs can use pre-made permissions sets (or ‘canned ACLs’) or be customized in the body of the request. Pre-made ACLs are specified using the x-amz-acl header and custom ACLs are specified using XML in the request payload. Only one method (header or payload) can be used in a single request.

This operation does not make use of additional operation specific query parameters.

ACL grantees can be specified using any of the following methods:

Method	Description	Example
Canonical ID	User account UUID	`43a89ab8-a5e9-44bf-9671-d23a8729b2e0`
Email Address	Username of user account as set in COS Manager	`user1`
URI	Used for pre-defined groups. COS supports the All Users Group for bucket ACLs and the All Users Group and Authenticated Users URIs for Object ACLs. All other predefined groups are unsupported.	`http://acs.amazonaws.com/groups/global/AllUsers` or `http://acs.amazonaws.com/groups/global/AuthenticatedUsers`

The assigned permissions behave as follows:

Permission	When granted on a bucket	When granted on an object
READ	Allows grantee to list and read all objects in bucket	Allows grantee to read object data and metadata
WRITE	Allows grantee to create, overwrite and delete any object in bucket. Cannot be granted independently from READ permission.	N/A
READ_ACP	This permission does not exist for buckets; default setting is FULL_CONTROL	Allows grantee to read object ACL
WRITE_ACP	Default setting is FULL_CONTROL	Allows grantee to write ACL for applicable object
FULL_CONTROL	Allows grantee READ, WRITE, READ_ACP and WRITE_ACP permissions on bucket	Allows grantee READ, READ_ACP and WRITE_ACP permissions on object

Note: The READ_ACP, WRITE_ACP, and FULL_CONTROL permissions are implied by the bucket “own” permission. When any of these permissions are assigned to a grantee in a bucket ACL, that grantee will be granted the bucket “own” permission.

The following canned ACLs are supported by IBM COS. Values not listed below are not supported.

Canned ACL	Applies to	Notes
private	Bucket and object	When set on a bucket, the requestor is interpreted as the bucket owner.
public-read	Bucket and object	When set on a bucket, the requestor is interpreted as the bucket owner.
public-read-write	Bucket and object	When set on a bucket, the requestor is interpreted as the bucket owner.
authenticated-read	Bucket and object	Supported when set on an object only. Not supported as a bucket ACL.

Syntax


PUT https://{endpoint}/{bucket-name}?acl= # path style
PUT https://{bucket-name}.{endpoint}?acl= # virtual host style

Sample request of a basic pre-made ACL

This is an example of specifying a pre-made ACL to allow for public-read access to the “example” bucket. This allows any storage account to view the bucket’s contents and ACL details.


PUT /example?acl= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161011T190354Z
x-amz-acl: public-read
Host: 67.228.254.193

Sample response


HTTP/1.1 200 OK
Date: Tue, 4 Oct 2016 19:03:55 GMT
X-Clv-Request-Id: 73d3cd4a-ff1d-4ac9-b9bb-43529b11356a
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.129
X-Clv-S3-Version: 2.5
x-amz-request-id: 73d3cd4a-ff1d-4ac9-b9bb-43529b11356a
Content-Length: 0

Sample request Custom ACL

This is an example of specifying a custom ACL to allow for another user using their username to view the ACL for the “example” bucket, but not to list objects stored inside the bucket. A third account is given full access to the same bucket as another element of the same ACL. All authenticated users of the system can list objects in the bucket.


PUT /example?acl= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161011T190354Z
Host: 67.228.254.193


<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>{owner-storage-account-uuid}</ID>
    <DisplayName>OwnerDisplayName</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail">
        <ID>{username}</ID>
        <DisplayName>Grantee1DisplayName</DisplayName>
      </Grantee>
      <Permission>READ_ACP</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>{second-grantee-storage-account-uuid}</ID>
        <DisplayName>Grantee2DisplayName</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
        <ID>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</ID>
      </Grantee>
      <Permission>READ</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

Sample response


HTTP/1.1 200 OK
Date: Tue, 4 Oct 2016 19:03:55 GMT
X-Clv-Request-Id: 73d3cd4a-ff1d-4ac9-b9bb-43529b11356a
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.129
X-Clv-S3-Version: 2.5
x-amz-request-id: 73d3cd4a-ff1d-4ac9-b9bb-43529b11356a