Access Control List (ACL)

Last updated: 2021-07-13 14:35:27

    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 Name 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.

    Use case

    Set a bucket to allow public-read:

    cos.putBucketAcl({
       Bucket: 'examplebucket-1250000000',                               /* Required */
       Region: 'COS_REGION',     /* Bucket region. Required */
       ACL: 'public-read'
    }, function(err, data) {
       console.log(err || data);
    });
    

    Grant a user full permission for a bucket:

    cos.putBucketAcl({
       Bucket: 'examplebucket-1250000000',                               /* Required */
       Region: 'COS_REGION',     /* Bucket region. Required */
       GrantFullControl: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000011:uin/100000000011"' // 100000000001 is uin.
    }, function(err, data) {
       console.log(err || data);
    });
    

    Modify bucket permission with AccessControlPolicy:

    cos.putBucketAcl({
       Bucket: 'examplebucket-1250000000',                               /* Required */
       Region: 'COS_REGION',     /* Bucket region. Required */
       AccessControlPolicy: {
           "Owner": { // `Owner` is required in `AccessControlPolicy`.
               "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the UIN of the bucket owner
           },
           "Grants": [{
               "Grantee": {
                   "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is UIN
               },
               "Permission": "WRITE"
           }]
       }
    }, function(err, data) {
       console.log(err || data);
    });
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, please see Regions and Access Endpoints. String Yes
    ACL Defines the access control list (ACL) attribute of the bucket. For the enumerated values, such as private (default) and public-read, please see the Preset ACL section in ACL Overview. String No
    GrantRead Grants a user read access in the format: id="[OwnerUin]".
    Use a comma (,) to separate multiple users.
    To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>".
    To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    GrantWrite Grants a user write access in the format: id="[OwnerUin]".
    Use a comma (,) to separate multiple users.
    To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>".
    To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>".
    Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    GrantReadAcp Grants a user read permission for bucket ACL and policies in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
  • To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>".
  • To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>".
    Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
  • String No
    GrantWriteAcp Grants a user write permission for bucket ACL and policies in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
  • To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>".
  • To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>".
    Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
  • String No
    GrantFullControl Grants full permission in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
  • To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>".
  • To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>".
    Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
  • String No
    AccessControlPolicy A list of all the information about the CORS configuration Object No
    - Owner Object representing the bucket owner Object No
    - - ID Complete ID of the bucket owner in the format: qcs::cam::uin/[OwnerUin]:uin/[OwnerUin],
    such as `qcs::cam::uin/100000000001:uin/100000000001’, where 100000000001 is uin
    String No
    - Grants List of information on the authorized user and granted permissions ObjectArray No
    - - Permission Permission granted. Valid values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL. For the enumerated values, please see the Action permissions section in ACL Overview. String No
    - - Grantee Authorized user information Object No
    - - - ID Complete ID of the grantee in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]
    Example: qcs::cam::uin/100000000001:uin/100000000001 where 100000000001 is the uin
    String No
    - - - DisplayName String representing the username, which is usually the same as the string you enter for ID String No
    - - - URI Preset user groups. For more information, see the Identity (Grantee) section in ACL Overview, such as
    http://cam.qcloud.com/groups/global/AllUsers or
    http://cam.qcloud.com/groups/global/AuthenticatedUsers
    String No

    Callback function description

    function(err, data) { ... }
    
    Parameter Name Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Object returned when the request is successful. If the request fails, this parameter is left empty. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object

    Querying a bucket ACL

    Feature description

    This API (GET Bucket acl) is used to query the ACL of a bucket. To call this API, you need to have permission to read the ACL of the bucket.

    Use case

    cos.getBucketAcl({
       Bucket: 'examplebucket-1250000000',                               /* Required */
       Region: 'COS_REGION',     /* Bucket region. Required */
    }, function(err, data) {
       console.log(err || data);
    });
    

    Sample response

    {
      "GrantFullControl": "",
      "GrantWrite": "",
      "GrantRead": "",
      "GrantReadAcp": "id=\"qcs::cam::uin/100000000011:uin/100000000011\"",
      "GrantWriteAcp": "id=\"qcs::cam::uin/100000000011:uin/100000000011\"",
      "ACL": "private",
      "Owner": {
          "ID": "qcs::cam::uin/100000000001:uin/100000000001",
          "DisplayName": "qcs::cam::uin/100000000001:uin/100000000001"
      },
      "Grants": [{
          "Grantee": {
              "ID": "qcs::cam::uin/100000000011:uin/100000000011",
              "DisplayName": "qcs::cam::uin/100000000011:uin/100000000011"
          },
          "Permission": "READ"
      }],
      "statusCode": 200,
      "headers": {}
    }
    

    Parameter description

    Parameter Name Description Type Required
    Bucket Bucket name in the format: BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, please see Regions and Access Endpoints. String Yes

    Callback function description

    function(err, data) { ... }
    
    Parameter Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Returns headers Object
    data Returns data when the request is successful. If the request fails, this is empty. Object
    - statusCode Returns an HTTP status code, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    x-cos-acl Defines the access control list (ACL) attribute of the bucket. For the enumerated values such as private and public-read, see the Preset ACLs for buckets section in ACL Overview. Default value: private Enum
    - GrantRead ID information of the user granted read access String
    - GrantWrite ID information of the user granted write access String
    - GrantReadAcp ID information of the user granted read access to the ACL and Policies String
    - GrantWriteAcp ID information of the user granted write access to the ACL and Policies String
    - GrantFullControl ID information of the user granted full access String
    - Owner Bucket owner information Object
    - - DisplayName Bucket owner username String
    - - ID Bucket owner ID in the format: qcs::cam::uin/<owneruin>:uin/<subuin>.
    For root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.
    String
    - Grants List of information on the authorized user and granted permissions ObjectArray
    - - Permission Specifies the permission granted to the user. Enumerated values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL String
    - - Grantee Authorized user information Object
    - - - DisplayName Authorized user’s username String
    - - - ID User ID of the authorized user
    For root accounts, the format is qcs::cam::uin/<owneruin>:uin/<owneruin>
    or qcs::cam::anyone:anyone representing all users.
    For sub-accounts, the format is qcs::cam::uin/<owneruin>:uin/<subuin>
    String
    - - - URI Preset user groups. For more information see the Identity (Grantee) section in ACL Overview, such as
    http://cam.qcloud.com/groups/global/AllUsers or
    http://cam.qcloud.com/groups/global/AuthenticatedUsers
    String

    Object ACLs

    Setting object ACL

    Feature description

    This API (PUT Object acl) is used to set the ACL of an object in a bucket.

    Note:

    The total number of policies associated with bucket ACL, Policy, and CAM under a single root account (i.e., under the same APPID) cannot exceed 1,000. There is no upper limit on the number of object ACL rules. If you do not need access control for an object, do not make any configuration, and the object will inherit the permissions of its bucket.

    Use case

    cos.putObjectAcl({
       Bucket: 'examplebucket-1250000000',                               /* Required */
       Region: 'COS_REGION',     /* Bucket region. Required */
       Key: 'exampleobject',              /* Required */
       ACL: 'public-read', /*Optional*/
    }, function(err, data) {
       console.log(err || data);
    });
    

    Grant a user all permissions for an object:

    cos.putObjectAcl({
       Bucket: 'examplebucket-1250000000',                               /* Required */
       Region: 'COS_REGION',     /* Bucket region. Required */
       Key: 'exampleobject',              /* Required */
       GrantFullControl: 'id="100000000001"' // 100000000001 is the uin of the root account.
    }, function(err, data) {
       console.log(err || data);
    });
    

    Grant the user permission to write the object via AccessControlPolicy:

    cos.putObjectAcl({
       Bucket: 'examplebucket-1250000000',                               /* Required */
       Region: 'COS_REGION',     /* Bucket region. Required */
       Key: 'exampleobject',              /* Required */
       AccessControlPolicy: {
           "Owner": { // `Owner` is required in `AccessControlPolicy`.
               "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the UIN of the bucket owner
           },
           "Grants": [{
               "Grantee": {
                   "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is the UIN of the sub-account of the bucket owner
               },
               "Permission": "WRITE"
           }]
       }
    }, function(err, data) {
       console.log(err || data);
    });
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name, formatted as BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, please see Regions and Access Endpoints. String Yes
    Key Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview String Yes
    ACL Defines the ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Default value: default
    Note: If you do not need access control for the object, set default for this parameter or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in.
    String No
    GrantRead Grants a user read permission for an object in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
    • To authorize a sub-account, use id="qcs::cam::uin/:uin/".
    • To authorize a root account, use id="qcs::cam::uin/:uin/".
      Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    GrantFullControl Grants a user full access in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
    • To authorize a sub-account, use id="qcs::cam::uin/:uin/".
    • To authorize a root account, use id="qcs::cam::uin/:uin/".
      Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    AccessControlPolicy Sets the object's ACL attributes. Object No
    - Owner Information about the object owner Object No
    - - ID ID of the object owner in the format: qcs::cam::uin/<owneruin>:uin/<subuin>
    For root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.
    String No
    - - DisplayName Name of the object owner String No
    - Grants A list of information about the grantee and granted permissions ObjectArray No
    - - Permission Permission granted. Enumerated values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL String No
    - - Grantee Information about the grantee Object No
    - - - DisplayName Name of the grantee String No
    - - - ID ID of the authorized user in the format: qcs::cam::uin/<owneruin>:uin/<subuin>
    For root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.
    String No

    Callback function description

    function(err, data) { ... }
    
    Parameter Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Object returned when the request is successful. If the request fails, this parameter is left empty. Object
    - statusCode HTTP status code returned by the request, such as 200, 204, 403, and 404 Number
    - headers Headers returned by the request Object

    Querying object ACL

    Feature description

    The API is used to query the ACL of an object. Only the owner of the bucket has the permission to use this API.

    Use case

    cos.getObjectAcl({
       Bucket: 'examplebucket-1250000000',                               /* Required */
       Region: 'COS_REGION',     /* Bucket region. Required */
       Key: 'exampleobject',              /* Required */
    }, function(err, data) {
       console.log(err || data);
    });
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name, formatted as BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, please see Regions and Access Endpoints. String Yes
    Key Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview. String Yes

    Callback function description

    function(err, data) { ... }
    
    Parameter Description Type
    err Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Object returned when the request is successful. If the request fails, this parameter is left empty. Object
    - statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    - ACL Defines the ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Default value: default
    Note: If you do not need access control for the object, set default for this parameter or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in.
    String
    - Owner Owner of the resource Object
    - - ID Object owner ID in the format of qcs::cam::uin/<owneruin>:uin/<subuin>
    For root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.
    String
    - - DisplayName Object owner name String
    - Grants List of information on the grantee and permissions ObjectArray
    - - Permission Permission granted. Enumerated values: READ, READ_ACP, WRITE_ACP, FULL_CONTROL String
    - - Grantee Grantee information Object
    - - - DisplayName Name of the user String
    - - - ID User ID in the format: qcs::cam::uin/<owneruin>:uin/<subuin>
    For root accounts, and have the same value.
    String