Access Control

Last updated: 2021-01-26 18:24:17

    Overview

    This document provides an overview of APIs and SDK code samples related to the access control lists (ACLs) for buckets and objects.

    Bucket ACL

    API Operation Description
    PUT Bucket acl Setting a bucket ACL Sets an ACL for a bucket
    GET Bucket acl Querying a bucket ACL Queries the ACL of a bucket

    Object ACL

    API Operation Description
    PUT Object acl Setting an object ACL Sets an ACL for an object in a bucket
    GET Object acl Querying an object ACL Queries the ACL of an object

    Bucket ACL

    Setting a bucket ACL

    Feature description

    This API (PUT Bucket acl) is used to set an ACL for a bucket. This operation will overwrite existing permission configurations. ACL includes predefined permission policies (CannedAccessControlList) or custom permission policies (AccessControlList). If both types of policies are set, predefined policies are ignored and custom policies will be used.

    Method prototype

    // Method 1 (Set custom policy.)
    public void setBucketAcl(String bucketName, AccessControlList acl)
      throws CosClientException, CosServiceException;
    // Method 2 (Set predefined policy.)
    public void setBucketAcl(String bucketName, CannedAccessControlList acl) throws CosClientException, CosServiceException;
    // Method 3 (Encapsulate the two methods above, allowing you to set both policies. In this case, the custom policy prevails.)
    public void setBucketAcl(SetBucketAclRequest setBucketAclRequest) 
      throws CosClientException, CosServiceException;

    Sample request

    The bucket name entered must be in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Set custom ACL.
    AccessControlList acl = new AccessControlList();
    Owner owner = new Owner();
    owner.setId("qcs::cam::uin/100000000001:uin/100000000001");
    acl.setOwner(owner);
    String id = "qcs::cam::uin/100000000001:uin/100000000001";
    UinGrantee uinGrantee = new UinGrantee("qcs::cam::uin/100000000001:uin/100000000001");
    uinGrantee.setIdentifier(id);
    acl.grantPermission(uinGrantee, Permission.FullControl);
    cosClient.setBucketAcl(bucketName, acl);
    
    // Set predefined ACL.
    // Set private read and write (New buckets are configured with private read and write by default).
    cosClient.setBucketAcl(bucketName, CannedAccessControlList.Private);
    // Set public read and private write.
    cosClient.setBucketAcl(bucketName, CannedAccessControlList.PublicRead);
    // Set public read and write.
    cosClient.setBucketAcl(bucketName, CannedAccessControlList.PublicReadWrite);

    Parameter description

    Parameters in method 3 include those in methods 1 and 2. Therefore, method 3 is used as an example.

    Parameter Description Type
    setBucketAclRequest Class for requesting permission configuration SetBucketAclRequest

    Request members:

    Request Member Set Method Description Type
    bucketName Constructor or set method Bucket name in the format of BucketName-APPID. For more information, please see Bucket Overview. String
    acl Constructor or set method Custom ACL policy AccessControlList
    cannedAcl Constructor or set method Predefined ACL policy, such as public read, public read and write, private read CannedAccessControlList
    Member Name Description Type
    List<Grant> Contains information about all granted permissions. Array
    owner Owner of the object Owner class

    Grant class members:

    Member Name Description Type
    grantee Grantee information Grantee
    permission Permission granted (such as read, write, or read/write) Permission

    Owner class members:

    Member Name Description Type
    id Identity information of the owner String
    displayname Name of the owner (same as id) String

    CannedAccessControlList indicates the preset policy for everyone. It is of the enumeration type with the following enumerated values:

    Enumerated Value Description
    Private Private read and write (only the owner can read and write)
    PublicRead Public read and private write (the owner can read and write, other users can read)
    PublicReadWrite Public read and write (everyone can read and write)

    Response description

    • Success: No value is returned.
    • Failure: An error occurs (such as authentication failure), throwing the CosClientException or CosServiceException exception. For more information, please see Troubleshooting.

    Querying a bucket ACL

    Feature description

    This API is used to query the ACL of a bucket.

    Method prototype

    public AccessControlList getBucketAcl(String bucketName)
           throws CosClientException, CosServiceException

    Sample request

    The bucket name entered must be in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    AccessControlList accessControlList = cosClient.getBucketAcl(bucketName);
    // Change the ACL policy type to predefined ACL. Valid values: Private, PublicRead, PublicReadWrite
    CannedAccessControlList cannedAccessControlList = accessControlList.getCannedAccessControl();

    Parameter description

    Parameter Description Type
    bucketName Bucket name in the format of BucketName-APPID. For more information, please see Naming Conventions. String

    Response description

    • Successful: The ACL of a bucket is returned.
    • Failure: An error (such as authentication failure) occurs, throwing the CosClientException or CosServiceException exception. For more information, please see Troubleshooting.

    Object ACLs

    Setting object ACL

    Feature description

    This API is used to set an ACL for an object in a bucket.

    There are two types of ACL policies: predefined ACLs (CannedAccessControlList) and custom ACLs (AccessControlList). If both of them are set, the custom ACL prevails over the predefined ACL.

    Method prototype

    // Method 1 (Set custom policy.)
    public void setObjectAcl(String bucketName, String key, AccessControlList acl)
           throws CosClientException, CosServiceException
    // Method 2 (Set predefined policy.)
    public void setObjectAcl(String bucketName, String key, CannedAccessControlList acl)
           throws CosClientException, CosServiceException
    // Method 3 (Encapsulate the two methods above, allowing you to set both policies. In this case, the custom policy prevails.)
    public void setObjectAcl(SetObjectAclRequest setObjectAclRequest)
      throws CosClientException, CosServiceException;

    Sample request

    // The grantee information must be formatted. The format for the root account and sub-account differs as follows:
    // In this example, both root_uin and sub_uin below are valid QQ numbers.
    // The root account "qcs::cam::uin/<root_uin>:uin/<root_uin>" indicates that permission is granted to the root account "root_uin" itself.
    // Example: qcs::cam::uin/100000000001:uin/100000000001
    // The sub-account "qcs::cam::uin/<root_uin>:uin/<sub_uin>" indicates that permission is granted by the root account "root_uin" to the sub account "sub_uin"
    // Example: qcs::cam::uin/100000000001:uin/100000000011 
    // Bucket name in the format: BucketName-APPID
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    // Set custom ACL.
    AccessControlList acl = new AccessControlList();
    Owner owner = new Owner();
    // Set the owner, which can only be a root account.
    owner.setId("qcs::cam::uin/100000000001:uin/100000000001");
    acl.setOwner(owner);
    
    // Grant the root account 100000000001 the read and write permissions.
    UinGrantee uinGrantee1 = new UinGrantee("qcs::cam::uin/100000000001:uin/100000000001");
    acl.grantPermission(uinGrantee1, Permission.FullControl);
    cosClient.setObjectAcl(bucketName, key, acl);
    
    // Set predefined ACL.
    // Set private read and write (The object inherits bucket permissions by default).
    cosClient.setObjectAcl(bucketName, key, CannedAccessControlList.Private);
    // Set public read and private write.
    cosClient.setObjectAcl(bucketName, key, CannedAccessControlList.PublicRead);
    // Set public read and write.
    cosClient.setObjectAcl(bucketName, key, CannedAccessControlList.PublicReadWrite);

    Parameter description

    • Parameters in method 3 include those in methods 1 and 2. Therefore, method 3 is used as an example.
    Parameter Description Type
    SetObjectAclRequest Request class setObjectAclRequest

    Request members:

    Request Member Set Method                     Description Type
    bucketName Constructor or set method Bucket name in the format of BucketName-APPID. For ,more information, please see Naming Conventions. String
    key Constructor or set method Unique identifier of the object in the bucket. For example, in the object’s access endpoint examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg, the object key is doc/picture.jpg. For more information, please see Object Key. String
    acl Constructor or set method Custom ACL policy AccessControlList
    cannedAcl Constructor or set method Predefined ACL policy, such as public read, public read and write, private read CannedAccessControlList
    Member Name Description Type
    List<Grant> Contains information about all granted permissions. Array
    owner Owner of the object Owner class

    Grant class members:

    Member Name Description Type
    grantee Grantee information Grantee
    permission Permission granted (such as read, write, or read/write) Permission

    Owner class members:

    Member Name Description Type
    id Identity information of the owner String
    displayname Name of the owner (same as id) String

    CannedAccessControlList indicates a preset policy for everyone. It is of the enumeration type with the following enumerated values:

    Enumerated Value Description
    Private Private read and write (only the owner can read and write)
    PublicRead Public read and private write (the owner can read and write, other users can read)
    PublicReadWrite Public read and write (everyone can read and write)

    Response description

    • Success: No value is returned.
    • Failure: An error (such as authentication failure) occurs, throwing the CosClientException or CosServiceException exception. For more information, please see Troubleshooting.

    Querying an object ACL

    Feature description

    This API is used to query the ACL of an object.

    Method prototype

    public AccessControlList getObjectAcl(String bucketName, String key)
      throws CosClientException, CosServiceException;

    Sample request

    // Bucket name in the format: BucketName-APPID
    String bucketName = "examplebucket-1250000000";
    String key = "exampleobject";
    AccessControlList accessControlList = cosClient.getObjectAcl(bucketName, key);
    // Change the ACL policy type to predefined ACL. Value values: Private, PublicRead, Default
    CannedAccessControlList cannedAccessControlList = accessControlList.getCannedAccessControl();

    Parameter description

    Parameter Description Type
    bucketName Bucket name in the format of BucketName-APPID. For more information, please see Naming Conventions. String
    key Unique identifier of the object in the bucket. For example, in the object's access endpoint examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For more information, please see Object Key. String

    Response description

    • Success: returns the ACL of the object.
    • Failure: An error (such as authentication failure) occurs, throwing the CosClientException or CosServiceException exception. For more information, please see Troubleshooting.