Skip to main content

Access Control List (ACL)

Intro​

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

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

  • Bucket ACLs: these ACLs are used to grant permissions for actions on a bucket.
  • Object ACLs: these ACLs are used to grant permissions for actions on an individual 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 ACL. There are two ways to identify a grantee when setting a ACL:

  • Cubbit Project ID: you can specify the grantee as a 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 protocol 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
    • when granted on a bucket allows the grantee to list the objects of the bucket
    • when granted on an object allows the grantee to read the content of the object
  • WRITE
    • when granted on a bucket allows the grantee to create, overwrite, and delete objects in the bucket
    • not applicable to objects
  • READ_ACP
    • when granted on a bucket allows the grantee to read the bucket's ACL
    • when granted on an object allows the grantee to read the object's ACL
  • WRITE_ACP
    • when granted on a bucket allows the grantee to write the bucket's ACL
    • when granted on an object allows the grantee to write the object's ACL
  • FULL_CONTROL: allows the grantee to have all of the above permissions on the bucket or the object where the permission is applied
note

WRITE operations are a no-op on Objects: once uploaded, there is no other write action you can perform against them. Example: a PutObject operation would simply replace the object, or create a new version in the case of versioned Buckets.

note

An ACL permission granted on a bucket is not inherited by the objects within it.

Required permission by APIs​

APIBucket grantObject grant
HeadBucket, ListObjects, ListObjectsV2, ListObjectVersionsREAD-
HeadObject, GetObject, GetObjectVersion-READ
PutObject, CreateMultipartUpload, UploadPart, CompleteMultipartUpload, DeleteObjectsWRITEnot applicable
GetBucketAclREAD_ACP-
GetObjectAcl-READ_ACP
PutBucketAclWRITE_ACP-
PutObjectAcl-WRITE_ACP
CopyObjectWRITE (on the destination bucket)READ (on the source object)
ListPartsWRITE-
ListMultipartUploadsFULL_CONTROL-
note

Other APIs, like PutBucketLifecycleConfiguration, require you to be the owner of the bucket.

Canned ACLs​​

The S3 protocol 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 ACLs​

There are a few limitations to using 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.

To overcome these limitations, you can use the Ownership Controls to enable object ownership controls on a bucket.

How to​

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

Updating the ACL overwrites existing configurations

Please note that by performing PutBucketAcl (or PutObjectAcl) operations, you're overwriting the existing one.

If you'd like to preserve the existing configuration, you should first GetBucketAcl (or GetObjectAcl), note the existing configuration and provide it along with the new one.

Reading current permissions attached to a given Bucket, or Object​​

Bucket​

aws s3api get-bucket-acl --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket | cat

The last part (| cat) is optional: it just lets you print the result as standard terminal output.

Object​

aws s3api get-object-acl --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket --key my-object | cat

The last part (| cat) is optional: it just lets you print the result as standard terminal output.

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-cubbit-bucket --grant-read id=111122223333 --grant-write id=111122223333

In this example above, 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-cubbit-bucket --grant-read uri=<http://acs.amazonaws.com/groups/global/AuthenticatedUsers> --grant-write uri=<http://acs.amazonaws.com/groups/global/AuthenticatedUsers>

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 AuthenticatedUsers group, which consists of any Cubbit Projects that are authenticated.

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

aws s3api put-object-acl --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket --key my-object --acl public-read-write

In this example, the put-object-acl command is used to set the ACL for the my-object object in the my-cubbit-bucket bucket. The --acl parameter is set to public-read-write, which means that any user can read and write the object.

An equivalent command is the following:

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

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​

How can I change previously set ACLs of an object or a bucket?​

To change previously set ACLs of a bucket or an object you just need to overwrite them.

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-cubbit-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"
        }
    ]
}
Last updated on