REST Access Control Policy

Topics

There are two ways to set the access control policy with REST. You can set the access control policy (ACP) for an existing bucket or object by requesting a PUT to /bucket?acl or /bucket/key?acl. Or, at the time you are writing a bucket or object you can include an x-amz-acl header with your PUT request that stores a canned ACP with the written resource.

REST Access Policy Existing Bucket

You can set the ACL on an existing bucket or object with an HTTP PUT to /bucket?acl, or /bucket/key?acl, where the body of the operation is the new ACL. To edit an existing ACL, fetch /bucket?acl or /bucket/key?acl to get the existing ACL, edit it locally, and then PUT the modified version back to ?acl.

Following is an example that demonstrates how to set an existing object ACL so that only the owner has full access to the object.

First, we get the owner's canonical user grant information.

GET /Neo?acl HTTP/1.1
Host: quotes.s3.amazonaws.com
Date: Wed, 25 Nov 2009 12:00:00 GMT
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

HTTP/1.1 200 OK

<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>314133b66967d86f031c7249d1d9a80249109428335cd0ef1cdc487b4566cb1b</ID>
    <DisplayName>s3-nickname</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>314133b66967d86f031c7249d1d9a80249109428335cd0ef1cdc487b4566cb1b</ID>
        <DisplayName>s3-nickname</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

Then, we set an existing object ACL so that only the owner has full access to the object.

PUT /Neo?acl HTTP/1.1
Host: quotes.s3.amazonaws.com
Content-Length: 214
Date: Wed, 25 Nov 2009 12:00:00 GMT
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

<AccessControlPolicy>
  <Owner>
    <ID>a9a7b886d6fd24a52fe8ca5bef65f89a64e0193f23000e241bf9b1c61be666e9</ID>
    <DisplayName>chriscustomer</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xsi:type="CanonicalUser">
        <ID>a9a7b886d6fd24a52fe8ca5bef65f89a64e0193f23000e241bf9b1c61be666e9</ID>
        <DisplayName>chriscustomer</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

Canned Access Policies

Because of restrictions in what can be sent via http headers, Amazon S3 supports the concept of canned access policies for REST. A canned access policy can be included with the x-amz-acl header as part of a PUT operation to provide shorthand representation of a full access policy. When Amazon S3 sees the x-amz-acl header as part of a PUT operation, it will assign the respective access policy to the resource created as a result of the PUT. If no x-amz-acl header is included with a PUT request, then the bucket or object is written with the private access control policy (even if, in the case of an object, the object already exists with some other pre-existing access control policy).

Following are canned ACLs that are supported for REST.

private—Owner gets FULL_CONTROL.
No one else has access rights (default).
public-read—Owner gets FULL_CONTROL and the anonymous principal is granted READ access.
If this policy is used on an object, it can be read from a browser with no authentication.
public-read-write—Owner gets FULL_CONTROL, the anonymous principal is granted READ and WRITE access.
This can be a useful policy to apply to a bucket, but is generally not recommended.
authenticated-read—Owner gets FULL_CONTROL, and any principal authenticated as a registered Amazon S3 user is granted READ access.
bucket-owner-read—Object Owner gets FULL_CONTROL, Bucket Owner gets READ
This ACL applies only to objects and is equivalent to private when used with PUT Bucket. You use this ACL to let someone other than the bucket owner write content (get full control) in the bucket but still grant the bucket owner read access to the objects.
bucket-owner-full-control—Object Owner gets FULL_CONTROL, Bucket Owner gets FULL_CONTROL
This ACL applies only to objects and is equivalent to private when used with PUT Bucket. You use this ACL to let someone other than the bucket owner write content (get full control) in the bucket but still grant the bucket owner full rights over the objects.

Following is an example that shows how to write data to an object and makes the object readable by anonymous principals.

Sample Request

PUT /Neo HTTP/1.1
x-amz-acl: public-read
Content-Length: 4
Host: quotes.s3.amazonaws.com
Date: Wed, 25 Nov 2009 12:00:00 GMT
Content-Type: text/plain
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

woah

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
Date: Wed, 25 Nov 2009 12:00:00 GMT
ETag: "aba878a8"
Content-Length: 0
Connection: close
Server: AmazonS3