Amazon Simple Storage Service
Developer Guide (API Version 2006-03-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Access Control List (ACL) Overview

Amazon S3 Access Control Lists (ACLs) enable you to manage access to buckets and objects. Each bucket and object has an ACL attached to it as a subresource. It defines which AWS accounts or groups are granted access and the type of access. When a request is received against a resource, Amazon S3 checks the corresponding ACL to verify the requester has the necessary access permissions.

When you create a bucket or an object, Amazon S3 creates a default ACL that grants the resource owner full control over the resource as shown in the following sample bucket ACL (the default object ACL has the same structure).

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>*** Owner-Canonical-User-ID ***</ID>
    <DisplayName>owner-display-name</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xsi:type="Canonical User">
        <ID>*** Owner-Canonical-User-ID ***</ID>
        <DisplayName>display-name</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy> 

The sample ACL includes an Owner element identifying the owner via the AWS account's canonical user ID. The Grant element identifies the grantee (either an AWS account or a predefined group), and the permission granted. This default ACL has one Grant element for the owner. You grant permissions by adding Grant elements, each grant identifying the grantee and the permission.

Note

An ACL can have up to 100 grants.

Who Is a Grantee?

A grantee can be an AWS account or one of the predefined Amazon S3 groups. You grant permission to an AWS account by the email address or the canonical user ID. However, if you provide an email in your grant request, Amazon S3 finds the canonical user ID for that account and adds it to the ACL. The resulting ACLs will always contain the canonical user ID for the AWS account, not the AWS account's email address.

Finding an AWS Account Canonical User ID

The canonical user ID is associated with your AWS account. You can find this ID by using the following procedure.

To find the canonical user ID for your AWS account

  1. Go to http://aws.amazon.com/console.

  2. Click Sign into the AWS Management Console and sign in with your AWS account credentials (not as an IAM user).

  3. Go to Security Credentials.

  4. Go to the Account Identifier section to see the canonical user ID associated with your AWS account.

You can also look up the canonical user ID of an AWS account by reading the ACL of a bucket or an object to which the AWS account has access permissions. When an individual AWS account is granted a permission by a grant request, a grant entry is added to the ACL with the AWS account's canonical user ID. For more information about the canonical user ID, go to AWS Account Identifiers.

Amazon S3 Predefined Groups

Amazon S3 has a set of predefined groups. When granting account access to a group, you specify one of our URIs instead of a canonical user ID. We provide the following predefined groups:

  • Authenticated Users group – Represented by http://acs.amazonaws.com/groups/global/AuthenticatedUsers.

    This group represents all AWS accounts. Access permission to this group allows any AWS account to access the resource. However, all requests must be signed (authenticated).

  • All Users group – Represented by http://acs.amazonaws.com/groups/global/AllUsers.

    Access permission to this group allows anyone to access the resource. The requests can be signed (authenticated) or unsigned (anonymous). Unsigned requests omit the Authentication header in the request.

  • Log Delivery group – Represented by http://acs.amazonaws.com/groups/s3/LogDelivery.

    WRITE permission on a bucket enables this group to write server access logs (see Server Access Logging) to the bucket.

Note

When using ACLs, a grantee can be an AWS account or one of the predefined Amazon S3 groups. However, the grantee cannot be an Identity and Access Management (IAM) user. For more information about AWS users and permissions within IAM, go to Using AWS Identity and Access Management.

Note

When you grant other AWS accounts access to your resources, be aware that the AWS accounts can delegate their permissions to users under their accounts. This is known as cross-account access. For information about using cross-account access, go to Enabling Cross-Account Access in Using Identity and Access Management.

What Permissions Can I Grant?

The following table lists the set of permissions Amazon S3 supports in an ACL. Note that the set of ACL permissions is same for object ACL and bucket ACL. However, depending on the context (bucket ACL or object ACL), these ACL permissions grant permissions for specific bucket or the object operations. The table lists the permission and describes what they mean in the context of object and bucket permissions.

PermissionWhen granted on a bucketWhen granted on an object
READAllows grantee to list the objects in the bucketAllows grantee to read the object data and its metadata
WRITEAllows grantee to create, overwrite, and delete any object in the bucketNot applicable
READ_ACPAllows grantee to read the bucket ACLAllows grantee to read the object ACL
WRITE_ACPAllows grantee to write the ACL for the applicable bucketAllows grantee to write the ACL for the applicable object
FULL_CONTROLAllows grantee the READ, WRITE, READ_ACP, and WRITE_ACP permissions on the bucketAllows grantee the READ, READ_ACP, and WRITE_ACP permissions on the object

Mapping of ACL Permissions and Access Policy Permissions

As shown in the preceding table, ACL allows only a finite set of permissions, compared to the number of permissions you can set in an access policy (see Specifying Permissions in a Policy). Each of these permissions allow one or more Amazon S3 operations. The following table shows how each of the ACL permissions map to the corresponding access policy permissions. As you can see, access policy allows more permissions than ACL does, you use ACL to primarily grant basic read/write permissions, similar to file system permissions. For more information about when to use ACL, see Guidelines for Using the Available Access Policy Options.

ACL PermissionCorresponding access policy permissions when the ACL permission is granted on a bucket Corresponding access policy permissions when the ACL permission is granted on an object
READs3:ListBucket, s3:ListBucketVersions, and s3:ListBucketMultipartUploads s3:GetObject, s3:GetObjectVersion, and s3:GetObjectTorrent
WRITE

s3:PutObject and s3:DeleteObject.

In addition, when the grantee is the bucket owner, granting WRITE permission in a bucket ACL allows the s3:DeleteObjectVersion action to be performed on any version in that bucket.

Not applicable
READ_ACPs3:GetBucketAcl s3:GetObjectAcl and s3:GetObjectVersionAcl
WRITE_ACPs3:PutBucketAcls3:PutObjectAcl and s3:PutObjectVersionAcl
FULL_CONTROLIt is equivalent to granting READ, READ_ACP, and WRITE_ACP ACL permissions. Accordingly, this ACL permission maps to combination of corresponding access policy permissions.It is equivalent to granting READ, READ_ACP, and WRITE_ACP ACL permissions. Accordingly, this ACL permission maps to combination of corresponding access policy permissions.

Sample ACL

The following sample ACL on a bucket identifies the resource owner and a set of grants. The format is the XML representation of an ACL in the Amazon S3 REST API. The bucket owner has FULL_CONTROL of the resource. In addition, the ACL shows how permissions are granted on a resource to two AWS accounts, identified by canonical user ID, and two of the predefined Amazon S3 groups discussed in the preceding section.

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>Owner-canonical-user-ID</ID>
    <DisplayName>display-name</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>Owner-canonical-user-ID</ID>
        <DisplayName>display-name</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
    
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>user1-canonical-user-ID</ID>
        <DisplayName>display-name</DisplayName>
      </Grantee>
      <Permission>WRITE</Permission>
    </Grant>

    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>user2-canonical-user-ID</ID>
        <DisplayName>display-name</DisplayName>
      </Grantee>
      <Permission>READ</Permission>
    </Grant>

    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
        <URI>http://acs.amazonaws.com/groups/global/AllUsers</URI> 
      </Grantee>
      <Permission>READ</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
        <URI>http://acs.amazonaws.com/groups/s3/LogDelivery</URI>
      </Grantee>
      <Permission>WRITE</Permission>
    </Grant>

  </AccessControlList>
</AccessControlPolicy>

Canned ACL

Amazon S3 supports a set of predefined grants, known as canned ACLs. Each canned ACL has a predefined a set of grantees and permissions. The following table lists the set of canned ACLs and the associated predefined grants.

Canned ACLApplies toPermissions added to ACL
privateBucket and objectOwner gets FULL_CONTROL. No one else has access rights (default).
public-readBucket and objectOwner gets FULL_CONTROL. The AllUsers group ( see Who Is a Grantee?) gets READ access.
public-read-writeBucket and objectOwner gets FULL_CONTROL. The AllUsers group gets READ and WRITE access. Granting this on a bucket is generally not recommended.
authenticated-readBucket and objectOwner gets FULL_CONTROL. The AuthenticatedUsers group gets READ access.
bucket-owner-readObjectObject owner gets FULL_CONTROL. Bucket owner gets READ access. If you specify this canned ACL when creating a bucket, Amazon S3 ignores it.
bucket-owner-full-controlObject Both the object owner and the bucket owner get FULL_CONTROL over the object. If you specify this canned ACL when creating a bucket, Amazon S3 ignores it.
log-delivery-writeBucket The LogDelivery group gets WRITE and READ_ACP permissions on the bucket. For more information on logs, see (Server Access Logging).

Note

You can specify only one of these canned ACLs in your request.

You specify a canned ACL in your request using the x-amz-acl request header. When Amazon S3 receives a request with a canned ACL in the request, it adds the predefined grants to the ACL of the resource.

How to Specify an ACL

Amazon S3 APIs enable you to set an ACL when you create a bucket or an object. Amazon S3 also provides API to set an ACL on an existing bucket or an object. These API provide you with the following methods to set an ACL:

  • Set ACL using request headers— When you send a request to create a resource (bucket or object), you set an ACL using the request headers. Using these headers, you can either specify a canned ACL or specify grants explicitly (identifying grantee and permissions explicitly).

  • Set ACL using request body— When you send a request to set an ACL on a existing resource, you can set the ACL either in the request header or in the body.

For more information, see Managing ACLs.