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 list below describes XML elements in an ACL request body. The elements are listed in alphabetical order.
AccessControlList
Child of the
AccessContolPolicy
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
AccessControlPolicy
element must include this XML namespace specification:xmlns="http://s3.amazonaws.com/doc/2006-03-01/"
DisplayName
Child of the
Owner
element or of theGrantee
element when the identifier type isCanonicalUser
.The value of the
DisplayName
element can be:- User name of an HCP user account
- User name 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.EmailAddress
Child of the
Owner
element or of theGrantee
element when the identifier type isAmazonCustomerByEmail
.The value of the
DisplayName
element can be:- User name 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 theGrantee
andPermission
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, theDisplayName
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.
- xsi:type="CanonicalUser"
ID
Child of the
Owner
element or of theGrantee
element when the identifier type isCanonicalUser
.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 theOwner
element and in the context of theGrantee
element when the identifier type in theGrantee
element isCanonicalUser
.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 thePermission
element are:- READ
- READ_ACP
- WRITE
- WRITE_ACP
- FULL_CONTROL
These values are case sensitive.
URI
Child of the
Owner
element or of theGrantee
element when the identifier type isGroup
.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.
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>