REST Access Control Policy

Amazon Simple Storage Service: 2006-03-01

previous page next page

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.

Existing Buckets or Objects

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>

</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, 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.

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.

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

previous page start next page