Adding an ACL to a bucket

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

You use the HTTP PUT method with the acl query parameter to add an ACL to an existing bucket. Adding an ACL to a bucket replaces any existing ACL in its entirety. You cannot modify an existing ACL in place.

To add an ACL to a bucket, you need write ACL permission for the bucket.

To add an ACL to a bucket, you can use either request headers or an ACL request body. You cannot use ACL headers and an ACL request body in the same request.

With ACL headers, you can specify either a canned ACL or individual x-amz-grant- headers. You cannot specify both a canned ACL and an x-amz-grant- header in the same request.

You can use an ACL request body to change the owner of a bucket you own. You cannot use ACL headers to do this. To change the owner of a bucket, you need both write ACL and change owner permission for the bucket.

If you try to add an ACL that specifies a user account that does not exist, HCP returns a 400 (Bad Request) status code and does not add the ACL to the bucket.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to add an ACL to a bucket has either of these formats:

  • With the bucket name included in the hostname:
    PUT /?acl HTTP/1.1
  • With the bucket name following the hostname:
    PUT /bucket-name?acl HTTP/1.1

The acl query parameter is not case sensitive.

Required headers

Authorization
Specifies user credentials or requests anonymous access.
Content-Length
Specifies the size, in bytes, of the request body.
This header is required when you’re using an ACL request body to add an ACL to the bucket. If you’re using ACL headers to add the ACL, the Content-Length header is invalid.
Date
Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.
The date and time must always be specified using Greenwich Mean Time (GMT).
To specify the date and time, use this format:
DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)
In this format:
DDD
The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).
dd
The two-digit day of the month.
MMM
The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).
yyyy
The four-digit year.
HH
The hour on a 24-hour clock.
mm
The number of minutes.
ss
The number of seconds.
For example:
Thu, 23 Mar 2017 14:27:05 +0000
All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.
Host
Specifies the hostname for the request. The host name identifies either a tenant or a bucket.
For a tenant, use this format:
tenant-name.hcp-domain-name
For a bucket, use this format:
bucket-name.tenant-name.hcp-domain-name
x-amz-date
Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.
For the valid values for this header, see the description of the Date header above.

Optional headers

Content-Type
Specifies the Internet media type of the request body. This header is valid only when the ACL is specified in the request body. The only valid values are application/xml and text/xml.
x-amz-acl
Adds a canned ACL to the bucket.
This header is used only to add a canned ACL to a bucket. If you’re using individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid.
x-amz-grant-full-control
Grants full control over the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-full-control header is invalid.
x-amz-grant-read
Grants the browse and read data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read header is invalid.
x-amz-grant-read-acp
Grants the read ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read-acp header is invalid.
x-amz-grant-write
Grants the write and delete data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write header is invalid.
x-amz-grant-write-acp
Grants the write ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write-acp header is invalid.

Response headers

The list below describes the headers returned in response to a successful request to add an ACL to a bucket.

Content-length
Specifies the size, in bytes, of the response body. In response to a successful request to store an object, the value of this header is always 0 (zero).
Date
The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:
DDD dd MMM yyyy HH:mm:ss GMT
For example:
Fri, 18 Sep 2020 14:27:05 GMT

Status codes

The table below describes HTTP status codes that can be returned in response to a request to add an ACL to a bucket.

Code Meaning Description
200 OK HCP successfully added the ACL to the bucket.
400 Bad Request

Possible reasons include:

  • You are trying to add an ACL that contains more than one hundred permission grants.
  • A specified grantee does not exist.
  • The specified owner does not exist.
  • Two grants of the same permission specify the same grantee.
  • The x-amz-acl header specifies an invalid value.
  • An x-amz-grant- header specifies an invalid identifier type.
  • The XML in the ACL request body is malformed or contains an invalid value.
403 Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to add an ACL to the bucket.
  • The specified bucket does not currently support the requested operation.
  • The S3 compatible API is currently disabled for the specified bucket..
  • The tenant does not currently support use of the S3 compatible API for adding ACLs to a buckets.
404 Not Found The specified bucket does not exist.
500 Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503 Service Unavailable

HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

If this error persists, contact your tenant administrator.

Example: Adding an ACL to a bucket by specifying individual grants

Here’s a sample PUT request that adds an ACL to the finance bucket by using x-amz-grant- headers. The ACL grants read permission to all users, write permission to user pdgrey, and write, read ACL, and write ACL permission to user mwhite.

Request with s3curl command line

./s3curl.pl --id=lgreen --put ~ -- -k "https://europe.hcp.example.com/finance?acl"
     -H "x-amz-grant-read: emailAddress=all_users"
     -H "x-amz-grant-write: emailAddress=pdgrey, emailAddress=mwhite"
     -H "x-amz-grant-read-acp: emailAddress=mwhite"
     -H "x-amz-grant-write-acp: emailAddress=mwhite"

Request headers

PUT /finance?acl HTTP/1.1
Host: europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:RuKD8rwRevmwLo+ZMhF5beGq7Qk=
x-amz-grant-read: emailAddress=all_users
x-amz-grant-write: emailAddress=pdgrey, emailAddress=mwhite
x-amz-grant-read-acp: emailAddress=mwhite
x-amz-grant-write-acp: emailAddress=mwhite

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Content-Length: 0

Example: Adding an ACL to a bucket by using an ACL request body

Here’s a sample PUT request that uses an ACL request body to add an ACL to the finance bucket and, at the same time, change the owner of the bucket. The ACL grants read and write access to the bucket to user lgreen and changes the bucket owner to user mwhite. The ACL request body is in a file named acl-7.xml.

Request body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Owner>
          <ID>b9d39144-a081-4760-b0e8-b8fb51e10192</ID>
          <DisplayName>mwhite</DisplayName>
     </Owner>
     <AccessControlList>
          <Grant>
               <Grantee xsi:type="CanonicalUser"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
                    <DisplayName>lgreen</DisplayName>
               </Grantee>
               <Permission>READ</Permission>
          </Grant>
          <Grant>
               <Grantee xsi:type="CanonicalUser"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Grantee>
          <Permission>WRITE</Permission>
          </Grant>
      </AccessControlList>
</AccessControlPolicy>

Request with s3curl command line

./s3curl.pl --id=lgreen --put acl-7.xml -- -k
     "https://europe.hcp.example.com/finance?acl"

Request headers

PUT /finance?acl HTTP/1.1
Host: europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:mVNu4YolbdvK+PVzmafhOvd1VgU=
Content-Length: 727

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Content-Length: 0