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>

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

Identifier type Type
AccessControlList

Child of the AccessContolPolicyelement 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 AccessControlPolicy 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

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.

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.

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.

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>

Trademarks and Legal Disclaimer

© 2017 Hitachi Data Systems Corporation. All rights reserved.