Basic Concepts
An Access Control List (ACL) is described in XML. It is a list associated with a resource that specifies grantees and grants permissions. Each bucket and object has an associated ACL, which supports granting basic read and write permissions to anonymous users or other Tencent Cloud root accounts.
Note:
Using ACLs associated with resources has the following limitations:
The owner of a resource always has the full control permissions over the resource, which cannot be revoked or modified.
Anonymous users cannot become resource owners. In this case, the owner of an object resource is the creator of the bucket (a Tencent Cloud root account).
Permissions can only be granted to Tencent Cloud CAM (Cloud Access Management) root accounts or preset user groups. They cannot be granted to custom user groups, and granting permissions to sub-users is not recommended.
Conditions cannot be attached to permissions.
The deny permissions cannot be displayed.
A resource can have at most 100 ACL policies.
Applicable Scenarios
Note:
Opening anonymous access (public read) is a high-risk operation that may lead to traffic theft. When public read must be enabled, you can set hotlink protection as a security measure.
When you only need to set simple access permissions for buckets and objects or open anonymous access, you can choose ACLs. However, in most cases, you are advised to preferably use bucket policies or user policies for higher flexibility. ACLs apply to the following scenarios:
Only set simple access permissions.
Quickly set access permissions in the console.
If you need to grant access to an object, directory, or bucket to all anonymous users on the Internet, choose ACL operations, which are more convenient.
ACL Elements
Identity Grantee
The supported authorized identities can be a CAM root account or a preset CAM user group.
Note:
When you grant access permissions to other Tencent Cloud root accounts, the authorized root accounts can grant access permissions to their sub-users, user groups, or roles.
COS (Cloud Object Storage) strongly advises against granting WRITE, WRITE_ACP, or FULL_CONTROL permissions to anonymous users or CAM user groups. Once granted, these user groups can perform actions such as uploading, downloading, and deleting your resources, which may lead to risks like data loss and unexpected charges.
The identities that can be granted in bucket or object ACLs include:
Cross-account: Use the root account ID and obtain the account ID through Account Center > Account Information, for example, 100000000001.
Preset user groups: Use URI tags to tag preset user groups. Supported user groups include:
Anonymous user group -
http://cam.qcloud.com/groups/global/AllUsers represents that anyone can access resources without authorization, regardless of whether the request is signed or unsigned.Authenticated user group -
http://cam.qcloud.com/groups/global/AuthenticatedUsers represents that all users authenticated by Tencent Cloud CAM accounts can access resources.Operation Permissions
The operations supported by Tencent Cloud COS on resource ACLs are actually a set of operations, which have different meanings for bucket ACLs and object ACLs.
Bucket operations
The following table lists the operations supported in bucket ACLs.
Operation Set | Description | Permitted Action |
READ | List objects | HeadBucket,GetBucketObjectVersions,ListMultipartUploads |
WRITE | Upload, overwrite, and delete an object. | PutObject,PutObjectCopy,PostObject,InitiateMultipartUpload,UploadPart,UploadPartCopy,CompleteMultipartUpload, DeleteObject |
READ_ACP | Read ACLs in a bucket. | GetBucketACL |
WRITE_ACP | Write ACLs to a bucket. | PutBucketACL |
FULL_CONTROL | Combine the above four permissions. | The set of all the above actions |
Note:
Exercise caution when granting WRITE, WRITE_ACP, or FULL_CONTROL permission to a bucket. When WRITE permission is granted to a bucket, the grantee can overwrite or delete any existing objects.
Object operations
The following table lists the operations supported in object ACLs.
Operation Set | Description | Permitted Action |
READ | Read an object. | GetObject,GetObjectVersion,HeadObject |
READ_ACP | Read ACLs of an object. | GetObjectACL,GetObjectVersionACL |
WRITE_ACP | Write ACLs to an object. | PutObjectACL,PutObjectVersionACL |
FULL_CONTROL | Combine the above three permissions. | The set of all the above actions |
Note:
Objects do not support granting the WRITE permission set.
Preset ACLs
COS supports a series of preset ACLs for authorization, facilitating the description of simple permissions. When using preset ACLs for description, you need to include the x-cos-acl header in PUT Bucket/Object or PUT Bucket/Object acl and describe the required permissions. If the request body also includes an XML description, the header description is prioritized and the XML description in the request body is ignored.
Preset ACLs for buckets
Preset Name | Description |
private | The creator (root account) has FULL_CONTROL permission, while others have no permissions (default). |
public-read | The creator has FULL_CONTROL permission, and anonymous user groups have READ permission. |
public-read-write | Both the creator and the anonymous user groups have FULL_CONTROL permission. Granting this permission is generally not recommended. |
authenticated-read | The creator has FULL_CONTROL permission, and authenticated user groups have READ permission. |
Preset ACLs for objects
Preset Name | Description |
default | No description is specified. In this case, whether a request is allowed is determined by the explicit settings at all levels of directories and the bucket settings, which is the default option. |
private | The creator (root account) has FULL_CONTROL permission, while others have no permissions. |
public-read | The creator has FULL_CONTROL permission, and anonymous user groups have READ permission. |
authenticated-read | The creator has FULL_CONTROL permission, and authenticated user groups have READ permission. |
bucket-owner-read | The creator has FULL_CONTROL permission, and the bucket owner has READ permission. |
bucket-owner-full-control | Both the creator and the bucket owner have FULL_CONTROL permission. |
Note:
Objects do not support granting public-read-write permissions.
Examples
Bucket ACLs
During bucket creation, COS creates a default ACL to grant the resource owner FULL_CONTROL permission as shown in the following example:
<AccessControlPolicy><Owner><ID>Owner-Cononical-CAM-User-Id</ID></Owner><AccessControlList><Grant><Grantee><ID>Owner-Cononical-CAM-User-Id</ID></Grantee><Permission>FULL_CONTROL</Permission></Grant></AccessControlList></AccessControlPolicy>
Object ACLs
When an object is created, COS does not create an ACL by default, and the owner of the object is the bucket owner. The object inherits the permissions of the bucket and has consistent access permissions as the bucket. Since the object has no default ACL, it follows the definitions of visitors and their actions in the bucket policies to determine whether a request is permitted. For details, see the Access Policy Language Overview article.
If you need to grant additional access permissions to an object, you can add more ACLs to describe the access permissions of the object. For example, to grant anonymous users read-only permission to a single object, see following example:
<AccessControlPolicy><Owner><ID>Owner-Cononical-CAM-User-Id</ID></Owner><AccessControlList><Grant><Grantee><ID>Owner-Cononical-CAM-User-Id</ID></Grantee><Permission>FULL_CONTROL</Permission></Grant><Grant><Grantee><URI>http://cam.qcloud.com/groups/global/AllUsers</URI></Grantee><Permission>READ</Permission></Grant></AccessControlList></AccessControlPolicy>
Usage
Using the COS Console
Setting Bucket Access Permissions
You can set or modify bucket access permissions through the COS console. COS supports two permission types:
Public Permissions: private read/write, public read/private write, and public read/write. For details about public permissions, see Permission Types in the bucket overview.
User Permissions: The root account has all bucket permissions (that is, FULL_CONTROL) by default. In addition, COS supports granting sub-accounts permissions for data read, data write, permission read (that is, granting users the permission to read "bucket access permissions"), permission write (that is, granting users the permission to write "bucket access permissions"), and even the highest permission of FULL_CONTROL.
Note:
When a bucket has the private read/write permission or user permissions are granted to specified accounts, a signature must be carried in the request for objects to authenticate identities. For details about a signature, see Request Signature.
When a bucket has the public read/private write or public read/write permission, a signature does not need to be carried in the request for objects. Anonymous users can directly access objects through links, which may expose your data to leakage risks. Exercise caution when setting these permissions.
Single Authorization
1. Log in to the COS Console.
2. In the left sidebar, click Bucket List.
3. Locate the bucket for which you need to set or modify access permissions and click its bucket name.
4. On the bucket configuration page, click Permission Management > Bucket Access Permissions to configure public permissions and user permissions for the bucket (for example, to add a sub-account, whose ID can be viewed in the CAM console).
Note:
If you must use the public read/private write or public read/write permissions and have not configured a default alarm, we recommend that you enable an alarm policy. If a default alarm is already configured, no further configuration is required and no prompt will be displayed.
5. Click Save to complete the bucket access permission configuration.
Batch Authorization
1. Log in to the COS Console.
2. In the left sidebar, click Bucket List.
3. Click Authorization Management above the list.
4. In the pop-up window, select the bucket you wish to authorize. Then configure the bucket's public permissions and user permissions (for example, to add a sub-account, whose ID can be viewed in the CAM console).
Note:
Authorization Management will modify both public permissions and user permissions simultaneously.
If you only need to modify user permissions, you must first check whether the public permissions of your bucket match the current configuration. Otherwise, the previous permissions will be overwritten.
5. After configuration is complete, click OK to complete the access permission configuration for multiple buckets.
Setting Object Access Permission
COS (Cloud Object Storage) provides access permission configuration at the object level, and this permission takes precedence over bucket access permissions.
Note:
An object's access permissions are only effective when a user accesses it via the default domain name. When the object is accessed via a CDN-accelerated domain name or a custom domain name, the bucket's access permissions take precedence.
Access policy rules are subject to quantity limits. For details, see Specifications and Limits.
Operation Steps
1. Log in to the COS Console.
2. In the left sidebar, click Bucket List to go to the bucket list page.
3. Find the bucket where the object is located and click the bucket name to enter the bucket management page.
4. In the left sidebar, select File List to go to the file list page.
5. Locate the object for which you want to set permissions and click Details on the right to go to the file details page. (For a folder, you can click Set Permissions on the right instead).
6. In the "Object Access Permissions" field, set the access permissions according to your actual needs.
The COS supports two types of permissions for objects:
Public Permissions: inherited permissions, private read/write, and public read/private write. For details about public permissions, see Permission Types in the object overview.
User Permissions: The root account has all permissions on objects (that is, full control) by default.
7. Click Save to set the object's access permissions.
If you need to set or modify access permissions for multiple objects in batches, select the objects and click More Actions > Modify Access Permissions above to set them.
Using REST API/SDK
You can manage bucket/object ACLs using the following APIs:
Manage bucket ACLs.
Manage object ACLs.
You can directly call the SDK to manage bucket/object ACLs. For details, see the following SDK documentation for each language:
Using Tools
You can use tools to manage bucket/object ACLs, such as COSBrowser, COSCMD, and COSCLI. For more tool introductions, see Tool Overview.