ACL#

Access Control Lists (ACLs) specify operations, which users can perform. ACLs can apply to both buckets and objects, and, therefore, the same permissions can have different meanings.

Supported grants#

Each grant has a different meaning depending on whether it applies to a bucket or an object.

Permission

Bucket

Object

READ

Grantee can list the objects in the bucket.

Grantee can read the object.

WRITE

Grantee can write or delete objects in the bucket.

N/A

READ_ACP

Grantee can read bucket ACL.

Grantee can read the object ACL.

WRITE_ACP

Grantee can edit bucket ACL.

Grantee can write to the object ACL.

FULL_CONTROL

User has all the above rights to the bucket

User has all the above rights to the object

Configuring ACL#

You can configure ACL using PUT requests in two ways:

  • by describing access policy in the request body;

  • by setting access rights in the request headers.

The following headers can be used to assign access rights:

  • x-amz-acl to specify Canned ACL.

  • x-amz-grant-read, x-amz-grant-write, x-amz-grant-read-acp, x-amz-grant-write-acp, and x-amz-grant-full-control to grant access rights explicitly.

Note

You can either opt for Canned ACLs or set ACLs explicitly, but cannot use both types of headers at the same time.

Canned ACL#

NGN Cloud supports a set of pre-configured access policies (Canned ACLs) for specific user categories.

ACL name

Applies to

Permissions added to ACL

private

Bucket/object

Owner gets FULL_CONTROL. No one else has access rights.

public-read

Bucket/object

Owner gets FULL_CONTROL. Anonymous users get READ access.

public-read-write

Bucket/object

Owner gets FULL_CONTROL. Anonymous users get READ and WRITE access.

authenticated-read

Bucket/object

Owner gets FULL_CONTROL. Authorized users get READ access.

PutBucketAcl#

Sets the ACL for the bucket. To configure the ACL, you must have WRITE_ACP permission. Any ACL you have set earlier will be overwritten.

Sample Request (using headers)#

Grants full control over the bucket bucket1 to the bucket owner user1, read access to anonymous users, write accessto authenticated users, and ACL read acess to users with the specified email address and ID.

Note

Don’t forget to grant full access (FULL_CONTROL) to the bucket owner, otherwise he/she will lose read and write access to the bucket. Unlike canned ACLs, these permissions are not assigned automatically when you explicitly specify access rights.

Request
PUT /bucket1/?acl=null HTTP/1.1
Host: s3.cloud.ngn.com.tr
x-amz-grant-full-control: emailAddress="user1@company"
x-amz-grant-read: uri="http://acs.amazonaws.com/groups/global/AllUsers"
x-amz-grant-write: uri="http://acs.amazonaws.com/groups/global/AuthenticatedUsers"
x-amz-grant-read-acp: emailAddress="user2@company", id="89d5ca16-be63-4139-afe0-795c0a45eb1c"
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20220531T102625Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user1@company/20220531/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date;x-amz-grant-full-control;x-amz-grant-write, Signature=66b32114ac08a5d6d77907e5ab8a9c1f0022cff6692f1f3475168bf8d0559be3

Sample Response#

Response
HTTP/1.1 200 OK
x-amz-request-id: tx000000000000003b72815-006295ed50-41e5801e-default
content-type: application-xml
content-length: 0
date: Tue, 31 May 2022 10:26:24 GMT

Sample Request (using request body)#

Grants full control over the bucket bucket1 to the bucket owner user1 and read/write access to authenticated users.

Request
PUT /bucket1/?acl=null HTTP/1.1
Host: s3.cloud.ngn.com.tr
X-Amz-Content-Sha256: beaead3198f7da1e70d03ab969765e0821b24fc913697e929e726aeaebf0eba3
X-Amz-Date: 20220531T103904Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user1@company/20220531/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=bc145fe2bd555a44119afcd01f538da372c3e9ee7159ecdb78f89d63092c1d4c
Content-Type: text/plain
Content-Length: 1249

<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
        <ID>b5e1b8d4-4886-4d03-a1b4-e03682a4ed8e</ID>
        <DisplayName>user1@company</DisplayName>
    </Owner>
    <AccessControlList>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
                <URI>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</URI>
            </Grantee>
            <Permission>READ</Permission>
        </Grant>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
                <URI>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</URI>
            </Grantee>
            <Permission>WRITE</Permission>
        </Grant>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
                <ID>b5e1b8d4-4886-4d03-a1b4-e03682a4ed8e</ID>
                <DisplayName>user1@company</DisplayName>
            </Grantee>
            <Permission>FULL_CONTROL</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>

Sample Response#

Response
HTTP/1.1 200 OK
x-amz-request-id: tx000000000000003b96b32-006295f047-415d7a1d-default
content-type: application-xml
content-length: 0
date: Tue, 31 May 2022 10:39:03 GMT

PutObjectAcl#

Sets the ACL for the existing object. To configure the ACL, you must have WRITE_ACP access. Any ACL you have set earlier will be overwritten.

Sample Request#

Grants full control over the object picture.png in the bucket bucket1 to the bucket owner user1 and read/write access to authenticated users.

Request
PUT /bucket1/picture.png?acl=null HTTP/1.1
Host: s3.cloud.ngn.com.tr
X-Amz-Content-Sha256: beaead3198f7da1e70d03ab969765e0821b24fc913697e929e726aeaebf0eba3
X-Amz-Date: 20220531T125146Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user1@company/20220531/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=71b45463e753131c736a1f70c5469d4a1bbd98456d440848f05b203f26210aad
Content-Type: text/plain
Content-Length: 1249

<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
         <DisplayName>user1@company</DisplayName>
    </Owner>
    <AccessControlList>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
                <URI>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</URI>
            </Grantee>
            <Permission>READ</Permission>
        </Grant>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
                <URI>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</URI>
            </Grantee>
            <Permission>WRITE</Permission>
        </Grant>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
                <ID>b5e1b8d4-4886-4d03-a1b4-e03682a4ed8e</ID>
                <DisplayName>user1@company</DisplayName>
            </Grantee>
            <Permission>FULL_CONTROL</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>

Sample Response#

Response
HTTP/1.1 200 OK
x-amz-request-id: tx000000000000003c8ffb2-0062960f61-41e6f988-default
content-type: application-xml
content-length: 0
date: Tue, 31 May 2022 12:51:45 GMT

GetBucketAcl#

Returns the access control policy for the bucket. READ_ACP access is required to execute the request.

Sample Request#

Request
GET /bucket1?acl=null HTTP/1.1
Host: s3.cloud.ngn.com.tr
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20220531T132612Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user1@company/20220531/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=b87b4f3d2900a9e199780d1fc9840ca87e63e9995d250855ded4307ec398e9ad

Sample Response#

Response
HTTP/1.1 200 OK
x-amz-request-id: tx000000000000006fafe36-0062961774-37d64f12-default
content-type: application-xml
content-length: 1394
date: Tue, 31 May 2022 13:26:12 GMT

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
        <ID>b5e1b8d4-4886-4d03-a1b4-e03682a4ed8e</ID>
        <DisplayName>user1@company</DisplayName>
    </Owner>
    <AccessControlList>
        <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>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
                <ID>b5e1b8d4-4886-4d03-a1b4-e03682a4ed8e</ID>
                <DisplayName>user1@company</DisplayName>
            </Grantee>
            <Permission>FULL_CONTROL</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>

GetObjectAcl#

Returns the access control policy for the bucket. READ_ACP access is required to execute the request.

Sample Request#

Request
GET /bucket1/picture.png?acl=null HTTP/1.1
Host: s3.cloud.ngn.com.tr
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20220531T135448Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user1@company/20220531/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=735bed2d244ab7a4a714dc111a442cbb3af63cc7ef0f22d93b1c8ae7df7bc783

Sample Response#

Response
HTTP/1.1 200 OK
x-amz-request-id: tx00000000000000702e51a-0062961f74-40173986-default
content-type: application-xml
content-length: 721
date: Tue, 31 May 2022 14:00:20 GMT

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
        <ID>b5e1b8d4-4886-4d03-a1b4-e03682a4ed8e</ID>
        <DisplayName>user1@company</DisplayName>
    </Owner>
    <AccessControlList>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
                <URI>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</URI>
            </Grantee>
            <Permission>READ</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>