ACL (Access Control List)

S3 ACL stands for Amazon S3 Access Control List, which is used to set permissions on S3 buckets and objects and it's fully supported by Cubbit.

ACLs are used to grant permissions to specific Cubbit Projects or groups to perform specific actions on a bucket or object. Two types of ACLs can be used with S3:

Bucket ACLs: these ACLs are used to grant permissions for actions on an S3 bucket.
Object ACLs: these ACLs are used to grant permissions for actions on an individual S3 object within a bucket.

Main concepts

Let's quickly go through some ACL main concepts and terminology. We'll cover what are grantees and how they can be identified, which permissions can be granted, and what is a canned ACL.

Grantee

A grantee is the Cubbit Project or group that is granted permission by an S3 ACL. There are two ways to identify a grantee when setting an S3 ACL:

Cubbit Project ID: you can specify the grantee as an Cubbit Project ID, using the id parameter. For example: id=111122223333.
Predefined group: you can specify the grantee as a predefined group, using the URI parameter. S3 provides the following predefined groups:
- AuthenticatedUsers: any Cubbit Project that is authenticated.
- AllUsers: any users on the internet.
To specify a predefined group, you can use the URI parameter and the URL of the group. For example: uri=http://acs.amazonaws.com/groups/global/AllUsers.

Permissions that can be granted

S3 ACLs can be used to grant the following permissions:

READ: allows the grantee to list the contents of the bucket and read the contents of the objects.
WRITE: allows the grantee to create, overwrite, and delete objects in the bucket.
READ_ACP: allows the grantee to read the bucket's ACL.
WRITE_ACP: allows the grantee to write the bucket's ACL.
FULL_CONTROL: allows the grantee to have all of the above permissions.

Canned ACLs

S3 also provides a set of predefined ACLs, known as "canned ACLs", that you can use to quickly set common permissions on a bucket or object. The available canned ACLs are:

private: grants permissions to the owner only.
public-read: grants read permissions to the AllUsers group, which consists of any user on the internet.
public-read-write: grants read and write permissions to the AllUsers group, which consists of any user on the internet.
authenticated-read: grants read permissions to the AuthenticatedUsers group, which consists of any Cubbit Projects that are authenticated.
bucket-owner-read: grants read permissions to the owner of the bucket.
bucket-owner-full-control: grants full control to the owner of the bucket.

APIs involved

Several S3 APIs are related to ACLs:

GetBucketAcl: used to retrieve the ACL for a bucket.
PutBucketAcl: used to set the ACL for a bucket.
GetObjectAcl: used to retrieve the ACL for an object.
PutObjectAcl: used to set the ACL for an object.

Limitations of S3 ACLs

There are a few limitations to using S3 ACLs:

Only the owner of a bucket or object can set the ACL. This means that other users cannot grant permissions to themselves or others using ACLs.
ACLs can only grant permissions to specific Cubbit Projects or predefined groups (such as AuthenticatedUsers or AllUsers).
ACLs apply to the bucket or object as a whole, and cannot be used to grant permissions on a per-object basis within a bucket.

Ownership Controls to the rescue

To overcome these limitations, you can use the S3 Ownership Controls to enable object ownership controls on a bucket. This allows you to specify who can own objects in a bucket, and how ownership is transferred between users.

For example, you might use object ownership controls to allow some users to upload objects to a bucket and to specify that the objects will be owned by the bucket owner when they are uploaded. This would allow the users to upload objects to the bucket, but would still give the bucket owner full control over the objects.

To enable object ownership controls on a bucket, you can use the PutOwnershipControls API with the BucketOwnerEnforced or BucketOwnerPreferred values:

aws s3api put-ownership-controls --bucket my-bucket --ownership-controls BucketOwnerEnforced

This will enable the BucketOwnerEnforced object ownership control on the bucket, which specifies that the bucket owner will be the owner of any objects that are uploaded to the bucket.

caution

Please note that this feature is still under development. Thus, Cubbit applies a default value of ObjectWriter for the ownership controls, which means that whoever uploads an object is the owner, even if the bucket is owned by someone else.

Usage

Here are some examples of how you might use S3 ACLs with the s3api CLI.

Granting read and write permissions to a specific Cubbit Project for a bucket

aws s3api put-bucket-acl --endpoint https://s3.cubbit.eu --bucket my-bucket --acl private --grant-read id=111122223333 --grant-write id=111122223333

In this example, the put-bucket-acl command is used to set the ACL for the my-bucket bucket. The --acl parameter is set to private, which means that only the owner of the bucket has permission to access it. The --grant-read and --grant-write parameters are used to grant read and write permissions to the Cubbit Project with the ID 111122223333.

Granting read and write permissions to the authenticated users group for a bucket

aws s3api put-bucket-acl --endpoint https://s3.cubbit.eu --bucket my-bucket --acl private --grant-read uri=<http://acs.amazonaws.com/groups/global/AuthenticatedUsers> --grant-write uri=<http://acs.amazonaws.com/groups/global/AuthenticatedUsers>

Granting read and write permissions to the all users group for an object

aws s3api put-object-acl --endpoint https://s3.cubbit.eu --bucket my-bucket --key my-object --acl public-read-write --grant-read uri=http://acs.amazonaws.com/groups/global/AllUsers --grant-write uri=http://acs.amazonaws.com/groups/global/AllUsers

In this example, the put-object-acl command is used to set the ACL for the my-object object in the my-bucket bucket. The --acl parameter is set to public-read-write, which means that any user can read and write the object. The --grant-read and --grant-write parameters are used to grant read and write permissions to the AllUsers group, which consists of any user on the internet.

FAQ

May I give the same permission to the same Grantee more than once?

Yes, you may give the same permission to the same Grantee more than once.

See user Luigi from the example below.

aws s3api get-bucket-acl --endpoint https://s3.cubbit.eu --profile cubbit --bucket my-bucket | cat
{
    "Owner": {
        "DisplayName": "Mario",
        "ID": "eb91a08c-988f-48bb-ab17-f66d90ff4971"
    },
    "Grants": [
        {
            "Grantee": {
                "DisplayName": "Mario",
                "ID": "eb91a08c-988f-48bb-ab17-f66d90ff4971",
                "Type": "CanonicalUser"
            },
            "Permission": "FULL_CONTROL"
        },
        {
            "Grantee": {
                "DisplayName": "Luigi",
                "ID": "23e5661e-71a1-4f75-b8df-4e0a504df356",
                "Type": "CanonicalUser"
            },
            "Permission": "FULL_CONTROL"
        },
        {
            "Grantee": {
                "DisplayName": "Luigi",
                "ID": "23e5661e-71a1-4f75-b8df-4e0a504df356",
                "Type": "CanonicalUser"
            },
            "Permission": "FULL_CONTROL"
        }
    ]
}

May I give `READ`, `WRITE` and `FULL_CONTROL` permissions to the same Grantee?

Yes, you may give READ, WRITE and FULL_CONTROL permissions to the same Grantee.

See user Luigi from the example below.

{
    "Owner": {
        "DisplayName": "Mario",
        "ID": "eb91a08c-988f-48bb-ab17-f66d90ff4971"
    },
    "Grants": [
        {
            "Grantee": {
                "DisplayName": "Mario",
                "ID": "eb91a08c-988f-48bb-ab17-f66d90ff4971",
                "Type": "CanonicalUser"
            },
            "Permission": "FULL_CONTROL"
        },
        {
            "Grantee": {
                "DisplayName": "Luigi",
                "ID": "23e5661e-71a1-4f75-b8df-4e0a504df356",
                "Type": "CanonicalUser"
            },
            "Permission": "READ"
        },
        {
            "Grantee": {
                "DisplayName": "Luigi",
                "ID": "23e5661e-71a1-4f75-b8df-4e0a504df356",
                "Type": "CanonicalUser"
            },
            "Permission": "WRITE"
        },
        {
            "Grantee": {
                "DisplayName": "Luigi",
                "ID": "23e5661e-71a1-4f75-b8df-4e0a504df356",
                "Type": "CanonicalUser"
            },
            "Permission": "FULL_CONTROL"
        }
    ]
}

Main concepts​

Grantee​

Permissions that can be granted​

Canned ACLs​

APIs involved​

Limitations of S3 ACLs​

Ownership Controls to the rescue​

Usage​

Granting read and write permissions to a specific Cubbit Project for a bucket​

Granting read and write permissions to the authenticated users group for a bucket​

Granting read and write permissions to the all users group for an object​

FAQ​

May I give the same permission to the same Grantee more than once?​

May I give READ, WRITE and FULL_CONTROL permissions to the same Grantee?​