Prev Feedback Next

Setting Access Policy with REST

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.

Setting the ACL on an Existing Bucket or Object

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.

Example

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, 01 Mar  2006 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>

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, 01 Mar  2006 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.

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, 01 Mar  2006 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, 01 Mar  2006 12:00:00 GMT
ETag: "aba878a8"
Content-Length: 0
Connection: close
Server: AmazonS3
Prev Copyright Information Next
 Home