Access Control Lists

Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.

An ACL is a list of grants. A grant consists of one grantee and one permission. ACLs only grant permissions; they do not deny them.

Note

Bucket and object ACLs are completely independent; an object does not inherit the ACL from its bucket. For example, if you create a bucket and grant write access to another user, you will not be able to access the user’s objects unless the user explicitly grants access. This also applies if you grant anonymous write access to a bucket. Only the user "anonymous" will be able to access objects the user created unless permission is explicitly granted to the bucket owner.

	Important
	We highly recommend that you do not grant the anonymous group write access to your buckets as you will have no control over the objects others can store and their associated charges. For more information, see Grantees and Permissions

Grantees

Following are five types of grantees that can access a bucket or object within Amazon S3.

• Owner

• User by E-mail

• User by Canonical Representation

• AWS User Group

• Anonymous Group

Owner

Every bucket and object in Amazon S3 has an owner, the user that created the bucket or object. The owner of a bucket or object cannot be changed. However, if the object is overwritten by another user (deleted and rewritten), the new object will have a new owner.

	Note
	Even the owner is subject to the ACL. For example, if an owner does not have READ access to an object, the owner cannot read that object. However, the owner of an object always has write access to the access control policy (WRITE_ACP) and can change the ACL to read the object.

User by E-mail

You can grant access to buckets and objects within your Amazon S3 account to anyone with an Amazon Web Services account. Any users that you grant access will be able to access buckets and objects using their AWS Access Key IDs and Secret Access Keys.

Following is an example that shows the XML format for granting access to a user through an Amazon customer e-mail address.

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail">

  <EmailAddress>chriscustomer@email.com</EmailAddress>

</Grantee>

E-mail grants are internally converted to the CanonicalUser representation when you create the ACL. If the grantee changes his or her e-mail address, it will not affect the existing Amazon S3 permissions.

Adding a grantee by e-mail address only works if exactly one Amazon account corresponds to the specified e-mail address. If multiple Amazon accounts are associated with the e-mail address, an AmbiguousGrantByEmail error message is returned. This is rare but usually occurs if a user created an Amazon account in the past, forgot the password, and created another Amazon account using the same e-mail address. If this occurs, the user should contact Amazon.com customer service to have the accounts merged or you should grant user access specifying the CanonicalUser representation.

User by Canonical Representation

You can grant access to buckets and objects within your Amazon S3 account to anyone with an Amazon Web Services account. Any users that you grant access will be able to access buckets and objects using their AWS Access Key IDs and Secret Access Keys.

	Note
	To locate the CanonicalUser ID for a user, the user must perform the ListAllMyBuckets operation in his or her Amazon S3 account and copy the ID from the Owner XML object.

Following is an example that example shows the XML format for granting access to a user through an Amazon customer CanonicalUser ID.

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">

  <ID>a9a7b886d6fd24a52fe8ca5bef65f89a64e0193f23000e241bf9b1c61be666e9</ID>

  <DisplayName>chriscustomer</DisplayName>

</Grantee>

The ID string specifies the CanonicalUser ID and must exactly match the ID of the user that you are adding. The DisplayName element is read-only. If you specify a DisplayName, it will be ignored and replaced with the name stored by Amazon.

AWS User Group

You can grant access to buckets or objects to anyone with an Amazon AWS account. Although this inherently insecure as any AWS user who is aware of the bucket or object will be able to access it, you might find this authentication method useful.

All AWS users can be specified as a grantee using the following example XML representation.

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">

  <URI>http://acs.amazonaws.com/groups/global/AuthenticatedUsers<URI>

</Grantee>

AllUsers Group

You can grant anonymous access to any Amazon S3 object or bucket. Any user will be able to access the object by omitting the AWS Key ID and Signature from a request.

AllUsers can be specified as a grantee using the following example XML representation:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">

 <<URI>http://acs.amazonaws.com/groups/global/AllUsers<URI>

</Grantee>

Using ACLs

An ACL can contain up to 100 grants. If no ACL is provided when a bucket is created or an object written, a default ACL is created. The default ACL consists of a single grant that gives the owner (i.e., the creator) the FULL_CONTROL permission. If you overwrite an existing object, the ACL for the existing object is overwritten and will default to FULL_CONTROL for the owner if no ACL is specified.

You can change the ACL of a resource without changing the resource itself. However, like Amazon S3 objects, there is no way to modify an existing ACL—you can only overwrite it with a new version. Therefore, to modify an ACL, read the ACL from Amazon S3, modify it locally, and write the entire updated ACL back to Amazon S3.

	Note
	The method of reading and writing ACLs differs depending on which API you are using. For more information, see the API-specific documentation for details.

Regardless of which API you are using, the XML representation of an ACL stored in Amazon S3 (and returned when the ACL is read) is the same. In the following example ACL, the owner has the default FULL_CONTROL, the "Frank" and "Jose" users both have WRITE and READ_ACP permissions, and all users have permission to READ.

<AccessControlPolicy>

  <Owner>

    <ID>a9a7b886d6fd24a52fe8ca5bef65f89a64e0193f23000e241bf9b1c61be666e9</ID>

    <DisplayName>chriscustomer</DisplayName>

  </Owner>

  <AccessControlList>

    <Grant>

      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">

        <ID>a9a7b886d6fd24a52fe8ca5bef65f89a64e0193f23000e241bf9b1c61be666e9</ID>

        <DisplayName>chriscustomer</DisplayName>

      </Grantee>

      <Permission>FULL_CONTROL</Permission>

    </Grant>

    <Grant>

      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">

        <ID>79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be</ID>

        <DisplayName>Frank</DisplayName>

      </Grantee>

      <Permission>WRITE</Permission>

    </Grant>

    <Grant>

      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">

        <ID>79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be</ID>

        <DisplayName>Frank</DisplayName>

      </Grantee>

      <Permission>READ_ACP</Permission>

    </Grant>

    <Grant>

      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">

        <ID>e019164ebb0724ff67188e243eae9ccbebdde523717cc312255d9a82498e394a</ID>

        <DisplayName>Jose</DisplayName>

      </Grantee>

      <Permission>WRITE</Permission>

    </Grant>

    <Grant>

      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">

        <ID>e019164ebb0724ff67188e243eae9ccbebdde523717cc312255d9a82498e394a</ID>

        <DisplayName>Jose</DisplayName>

      </Grantee>

      <Permission>READ_ACP</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>

  </AccessControlList>

</AccessControlPolicy>

	Note
	When you write an ACL to Amazon S3 that AmazonCustomerByEmail grantees, they will be converted to the CanonicalUser type prior to committing the ACL.