< Previous | Contents | Next >

Specifying an ACL in the request body


An ACL request body can specify one or more permission grants and/or an owner for the bucket or object. If the specified owner is not the current owner, the owner changes to the specified owner (provided that you change owner permission for the bucket).


For the content of an ACL request body, you use XML in this format:


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> To specify the current owner or change the owner, include the Owner element.

<Owner>

<ID>user-id</ID>

<DisplayName>username</DisplayName>

</Owner>

<AccessControlList>

Include one Grant element for each combination of grantee and permission.

<Grant>

<Grantee identifier-type

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

To identify the grantee, use either the ID and, optionally, DisplayName elements, the URI element, or the EmailAddress element.

<ID>user-id</ID>

<DisplayName>username</DisplayName>

<URI>group-uri</URI>

<EmailAddress>username</EmailAddress>

</Grantee>

<Permission>permission</Permission>

</Grant>

</AccessControlList>

</AccessControlPolicy>


30 Chapter 2: Bucket and object properties

Access control lists



The table below describes XML elements in an ACL request body. The elements are listed in alphabetical order.


Element

Description

AccessControlList

Child of the AccessControlPolicy element and container for zero or more grants of permissions to individual users or groups.


Each grant is represented by a Grant element.


The AccessControlList element is required in an ACL request body.

AccessControlPolicy

Root element. This must be the first element in the ACL request body.


The AcessControlPolicy element must include this XML namespace specification:


xmlns="http://s3.amazonaws.com/doc/2006-03-01/"


The AcessControlPolicy element is a container for the Owner and AccessControlList elements, which can occur in either order.

DisplayName

Child of the Owner element or of the Grantee element when the identifier type is CanonicalUser.


The value of the DisplayName element can be:


• Username of an HCP user account


• Username of an AD user account followed by an at sign (@) and the AD domain name


• authenticated


• all_users


The DisplayName element is optional and ignored.


The ID and DisplayName elements can occur in either order.

EmailAddress

Child of the Owner element or of the Grantee element when the identifier type is AmazonCustomerByEmail.


The value of the DisplayName element can be:


• Username of an HCP user account


• For object ACLs only, username of an AD user account followed by an at sign (@) and the AD domain name


Chapter 2: Bucket and object properties 31

Access control lists

(Continued)

Element

Description

Grant

Child of the AccessControlList element and container for the Grantee and Permission elements, which can occur in either order.


Each occurrence of the Grant element grants one permission to one grantee.

Grantee

Child of the Grant element and container for the grantee identifier.


The Grantee element must include this XML namespace specification:


xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"


The Grantee element must also include one of these specifications of identifier type to indicate how the grantee is identified:


• xsi:type="CanonicalUser"


The grantee is identified by the ID and, optionally, the DisplayName element. If present, the DisplayName element is ignored.


• xsi:type="Group"


The grantee is identified by the URI element.


• xsi:type="AmazonCustomerByEmail"


The grantee is identified by the EmailAddress element.

ID

Child of the Owner element or of the Grantee element when the identifier type is CanonicalUser.


The value of the ID element can be the user ID of an HCP user account or, for object ACLs only, the SID of an AD user account.


The ID element is required in the context of the Owner element and in the context of the Grantee element when the identifier type in the Grantee element is CanonicalUser.


To learn the ID or SID for a user account, see your tenant administrator.


32 Chapter 2: Bucket and object properties

Access control lists



(Continued)

Element

Description

Owner

Child of the AccessControlPolicy element and container for the owner identifier.


The owner is identified by the ID and, optionally, DisplayName

elements.


The Owner element is optional in an ACL request body. If you omit it, the bucket or object owner does not change.

Permission

Child of the Grant element. Valid values for the Permission

element are:


• READ


• READ_ACP


• WRITE


• WRITE_ACP


• FULL_CONTROL


These values are case sensitive.


For more information on these values, see “ACL permissions” on page 26.

URI

Child of the Owner element or of the Grantee element when the identifier type is Group.


Valid values for the URI element are the URI for the group of all authenticated users and the URI for the group of all users. For these URIs, see “ACL grantees” on page 27.


Chapter 2: Bucket and object properties 33

Access control lists


Here’s a sample ACL that sets the owner to the user named lgreen and grants read permission to all users and write permission to the user named pdgrey:


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">

<Owner>

<ID>53344e3b-00de-494b-962e-827ac143fa84</ID>

<DisplayName>lgreen</DisplayName>

</Owner>

<AccessControlList>

<Grant>

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

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

</Grantee>

<Permission>READ</Permission>

</Grant>

<Grant>

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

<EmailAddress>pdgrey</EmailAddress>

</Grantee>

<Permission>WRITE</Permission>

</Grant>

</AccessControlList>

</AccessControlPolicy>