Signature Authentication and Access

Baidu AI Cloud adopts the unified API authentication mechanism. For details, see Authentication Mechanism.

Original AK/SK Authentication

The original AK/SK means the AK(Access Key ID)/SK(Secret Access Key) that the system automatically assigns to you when you register “BOS”. It is mainly used for authenticating the users' calling behavior, which is equivalent to the user name and password dedicated to the Baidu AI Cloud API. Every request you send to BOS needs to be authenticated before BOS processes your request.

The interactive process of the original AK/S authentication in the mobile terminal scenario is shown in the figure below:

There is a certain security risk for you to send your original AK/SK to the mobile terminal. Therefore, it is only recommended that you use the original AK/SK authentication for the test and the STS authentication for the formal service provision.

Temporary Authorization for Access

STS Introduction

BOS can authorize a third party the temporary access privilege through the STS mechanism. STS (Security Token Service) is the temporary authorization service provided by Baidu AI Cloud. With the help of STS, you can grant a third-party user an access token with the custom valid time and privilege. The third-party users can use this credential to directly call Baidu AI Cloud API to access the Baidu AI Cloud resources.

Descriptions:

Here, the third-party user mainly refers to the end-user of your developed App. For example, if you are a mobile App developer, your App end user is called the third-party user.

The following takes the access to the BOS service via a mobile client as an example:

If you are a mobile App developer, and have enabled the BOS service and need to provide your App client with the permission to access the BOS service, you can authenticate the mobile client in the following two ways:

STS Authentication

To enable the mobile terminal to enjoy the BOS service conveniently and securely, Baidu AI Cloud has developed the STS service to meet the security requirements in mobile scenarios. The temporary authorization can be implemented through STS only, without the need to open your AK/SK.

The process of using STS for the temporary authorization to the App client is shown in the figure below:

1. Apply for the permission to access the BOS.

   To access the BOS resources, the App client needs to apply for access permission from AppServer. The AppServer that has enabled the BOS service can authorize and limit the access resources for different App end users.

2. Apply for a temporary credential.

   AppServer needs to apply for a temporary credential from STS. AppServer applies for the access credential by calling the STS GetSessionToken() interface. Meanwhile, it is required to specify the resource access permission and expiration time. For the calling method of GetSessionToken(), refer to STS Service Interface.

3. Return the STS credential to AppServer.

   After it processes the application, STS returns a temporary credential to AppServer, including temporary access key AK/SK, SessionToken, expiration date, and AppServer user ID. AppServercan cache the STS credential. When multiple App clients require the same permission, you can directly issue the cached credential to the clients.

4. Return the STS credential to the App clients.

   AppServer sends the received STS credential to the App clients, and the App clients can cache the STS credential. When the credential becomes invalid, the App clients need to re-apply for a valid credential from AppServer.

5. The App clients use the STS credential to access the BOS resources.

   The App client device can construct the API request using the returned STS credential to access the BOS resources directly. BOS perceives the STS credential, and relies on STS to verify the credential and respond to the user request correctly.

Advantages of STS:

• You do not need to disclose your management account or AK/SK information to any third-party user but only need to apply for a temporary credential from STS and issue it to the third-party user. Also, you can customize the permission and expiration date of the credential.
• You do not need to pay attention to the cancellation of the permission. The temporary credential is automatically invalid after expiration.

STS API

Interface description

The GetSessionToken API is used to make a request to return a temporary credential during the temporary access authorization.

Permission description

The request initiator cannot initiate the request unless the initiator has valid AccessKeyID and SecretAccessKey.

Request

• Request syntax

  POST /v1/sessionToken?durationSeconds=DurationSeconds HTTP/1.1
  Host: sts.bj.baidubce.com
  Date: <Date>
  Authorization: <AuthorizationString> 
  
  {
   "id":"userid",
   "accessControlList": [
    {   
     "eid":<eid>,
     "service":"bce:bos",
     "region":"bj",
     "effect": "Allow",
     "resource": ["Bucketname/*"],
     "permission": ["READ"]
     }
    ]
   } 

• Request AbortMultipartUploadarameters

  Name	Parameter Position	Description	Default Value	Required?
  durationSeconds	Query parameters	Effective duration of the temporary credential (second). Data type: int. You can specify a maximum value of 129,600 seconds (36 hours).	43200 (12 hours)	No

• Request header field

  Name	Data Type	Description	Default Value	Required?
  Authorization	string	Authentication string. For the calculation method, refer to Generate Authentication String.	-	No

• Request element

  The request element of this interface is the main part of the access control. The request element consists of one or more ACL configuration items that are independent of each other.

  Name	Data Type	Description	Default Value	Required?	Parent Node
  accessControlList	array	It identifies the beginning of the ACL body and consists of one or more ACL configuration items.	-	Yes	-
  effect	string	It allows you to specify whether to execute the request matching this ACL configuration item. The value is Allow or Deny. Allow indicates that the request is executeable. Deny indicates the denial to execute the request.	-	Yes	accessControlList
  eid	string	ACL configuration item ID	-	No	accessControlList
  id	string	ACL identifier	-	No	-
  permission	array	The permission influenced by the ACL configuration item, whose optional values include READ, WRITE, LIST and GetObject.	-	Yes	accessControlList
  region	string	The region affected by the ACL configuration item. "*" indicates all regions.	-	Yes	accessControlList
  resource	array	Resources affected by the ACL configuration item, which supports the wildcard. E.g., <BucketName>/<ObjectKey> or <BucketName>/xxx*	-	Yes	accessControlList
  service	string	Service component affected by the ACL configuration item. "*" indicates all services.	-	Yes	accessControlList

Descriptions:

• Because the response result of GetSessionToken contains the STS credential, it is strongly recommended that you call it through the HTTPS protocol.
• service: Taking the BOS service as an example, the value is "service":"bce:bos".

• resource: When the value is "service":"bce:bos", the resource can be bucket or object.

  • When the resource is bucket, its value is . E.g., "resource": sts-bucket-1"];
  • When the resource is Object, its value is <BucketName/ObjectName>, e.g., "resource": sts-bucket-1/ object1"];
  • In addition, the resource also supports wildcard *, indicating all objects in the bucket. For example："resource": ["sts-bucket-1/*"]。

• permission: The BOS service supports the READ/WRITE/LIST/GetObject permissions. Each permission corresponds to a group of API requests as follows:

  • The operations corresponding to the READ permission include:

    • GetBucketLocation
    • HeadBucket
    • GetObject
    • GetObjectMeta
    • ListParts

  • The operations corresponding to the WRITE permission include:

    • PutObject

    • PostObjcet

      • InitiateMultipartUpload
      • UploadPart
      • CompleteMultipartUpload
      • AppendObject
      • AbortMultipartUpload
      • DeleteObject
      • DeleteMultipleObjects
    • FetchObject

  • The operations corresponding to the LIST permission include:

    • ListObjects
    • ListMultipartUploads

  • The operations corresponding to the GetObject permission include:

    • GetObject
    • GetObjectMeta

Note: If no ACL is specified in the request element, the temporary credential returned is the same as your current READ/WRITE permission by default. After it is authorized to a third-party user, it may impose a certain risk to your account resource. It is recommended that you explicitly specify ACL during the temporary authorization to avoid the risk. If the request body is empty, the STS credential returned is the same as your current permission by default.

Response

• Response header field

This interface only uses the common response header.

• Response element

Example

• Request example

  POST /v1/sessionToken?durationSeconds=DurationSeconds HTTP/1.1
  Host: sts.bj.baidubce.com
  Date: Wed, 06 Apr 2016 06:34:40 GMT
  Authorization: AuthorizationString
  Content-type:application/json
  Content-Length:178
  
   {
    "id":"10eb6f5ff6ff4605bf044313e8f3ffa5",
    "accessControlList": [
     {   
      "eid":<eid>,
      "service":"bce:bos",
      "region":"bj",
      "effect": "Allow",
      "resource": ["sts-bucket-1-140683201300192-1447847972462384520478/*"],
      "permission": ["READ"]
      }
     ]
    }

• Response example

  HTTP/1.1 200 OK
  Server: Apache-Coyote/1.1
  Content-Type: application/json;charset=UTF-8
  Date: Wed, 06 Apr 2016 06:34:40 GMT
  
  {
    "accessKeyId": "3bdecf4afebd41849628389a20629ecc", 
    "secretAccessKey": "3f901ef12d454b9c92ba2dde7c029140", 
    "sessionToken": "ZGZiM2M3MmU4Mjk4NGQ2MGEzYTNhYTAyMDE3NTZmZmV8AAAAAC8CAABf0XcbS9E/leusHxRyZ4DYNb+SH374S+mmkxaOpcwdLPC7JL/aTF5F7x83dQn354VKiTyNGuvQIsv7MidIPN7+0oOehdFlHua4RkwqIi8wOslX0qNitZa56WpxowLprrMksOHiQiEqYEzAyaVF3Oy3hBbMiX/RprtcnxERAi1/skNR1VzTZyYfS5D4p8Ul62X9Whwmj5Lkxy6yuZ1og94wytwTc8aWPFPGFIpQyCpCaxYvl/QkA1M0rxQ6SMaHbxTyEYuG2Eg8EOP0EKn2O2DMjGuLURRKuxHRCrFidRxDqOX9kM/L7gQXuaZl9DdB1DwZPrSo8xiPDRrfkpIqvkJEeB0blb8dXtMm0V0lmTznUrnPuoD4nfVyEPKCET+0JhQooxNLWDE6x4alnR8QtJkJ2yjrYaoMZdeuqKRcpgehVOIgI8ZDIumN1rdObs7a4Hw4Gmx7f0gQgLWdIF4ZOKsSpWP8aos+vzdOA+NNSHsTVg==", 
    "createTime": "2015-11-18T11:48:17Z", 
    "expiration": "2015-11-18T23:48:17Z", 
    "userId": "2d6f4473c99e4ca7be1ca19ec18beacf"
  }

STS Authentication Process

When the third-party users use the returned temporary AK/SK and SessionToken to initiate a request to the server of Baidu AI Cloud, how does the server complete the temporary authentication?

1. First, the server verifies the validity of the request.

   The server finds the corresponding Secret Access Key through the Access Key ID in the request and extracts the signature string and signature in the request. If the signature calculated by the server is the same as that provided in the request, the request is considered valid. Otherwise, the request is considered invalid, and this processing request is denied.

2. Then, the server verifies whether the requester has the permission to operate the resource.

   The server compares this request with the ACL contained in GetSessionToken during the application for temporary token one by one. After the comparison, the processing logic is shown in the figure below:

   

For example:

Assume that the ACL during the application for the temporary token is as follows:

[{
    "effect": "Allow",
    "resource": ["sts-bucket-1"],
    "region": "bj",
    "service": "bce:bos",
    "permission": ["READ"]
}],

The authorized third party wants to perform the GetObject operation for img.jpg in sts-bucket-1. Because GetOject corresponds to the READ permission, this request can be written as follows:

[{
    "resource": ["sts-bucket-1/img.jpg"],
    "region": "bj",
    "service": "bce:bos",
    "permission": ["READ"]
}],

Matching the above ACL fails because the resource does not match. If the resource is written as sts-bucket-1/img.jpg or sts-bucket-1/* during the application for a temporary token, it can be matched successfully.

Access BOS Service Through STS Credential

After the App clients get the STS temporary credential, they construct the signature through Session Token and the temporary access key (AK/SK). The signature method is the same as the Signature Authentication and Access. The attention should be paid to the following key points: the signature key used by the user is the temporary access key (AK/SK) provided by STS.

Compared with the ordinary APIs, you only need to add x-bce-security-token: <session-token> to the request when you use the STS credential to call the API. The following takes PutObject as an example:

PUT /object HTTP/1.1
Host: <BucketName>.bos.bj.baidubce.com 
Date: Wed, 06 Apr 2016 06:34:40 GMT 
Authorization: <AuthorizationString> 
x-bce-security-token: <SessionToken>
Content-Type: text/plain 
Content-Length: 11434 

Description: At present, STS only supports the API request corresponding to READ, WRITE, and LIST.

Bucket Access Control

Overview of Access Control

BOS supports the management of the bucket access control using ACL. Bucket ACL is the permission attached to a resource, i.e., a bucket. In essence, it is required to authorize who (grantee) to perform which operations (permission). To facilitate users to more precisely control the resources in the bucket, Bucket ACL has Resource and notResource fields. The Resource field is used to implement the access control of the prefix and object granularity within the specified range. The notResource field is used to implement the access control of the prefix and object granularity outside the specified range. Furthermore, Bucket ACL also supports the condition field, which can be used to set the visitor IP and Referer.

To ensure the high security of your data stored in BOS, we provide you with many multi-level access control capabilities. The access control system of BOS is divided into the following three levels:

Bucket standard permissions (CannedACL) Coarse-grained custom permissions
Fine-grained custom permissions

At present, BOS can set ACL by uploading ACL files or by using CannedAcl. Both methods can be implemented through the PutBucketAcl API. Uploading an ACL file is to describe who (grantee) can perform which operations (permission) for what resources (resource or notResource) under what conditions through a JSON file. It is a high threshold to edit the ACL file directly, so BOS also supports the CannedAcl mode. In essence, CannedAcl encapsulates several common access control scenarios and sets the resources in the “x-bce-acl” field in the header field of PutBucketAcl directly.

Access Control through CannedAcl Mode

CannedAcl is a user-friendly way to encapsulate several common access control scenarios. It sets this resource through the “x-bce-acl” field in the header field of PutBucketAcl. Example: x-bce-acl:public-read. The field is case-sensitive.

The currently supported CannedAcl includes:

Description: The permission of the bucket created through PutBucket is private by default.

Access Control Through Uploading ACL File

ACL file format

PutBucketAcl can set the access control by uploading an ACL file. BOS ACL uses the policy description language in the JSON format. The naming method is lower camel case. The field is case sensitive.

Field overview:

Description:

• The ACL format used is described above. When you upload the ACL file, the owner attribute is not required. The JSON field identifies the bucket owner. If it carries the owner attribute, its ID value must be the bucket owner ID.
• The uploaded ACL file is not greater than 20 KB.
• If the user sets the ACL in the Header (Canned ACL) and Body of the HTTP message when it uses PutBucketAcl API, it returns “Error 400: Incorrect Parameters".
• When the currentTime subfield is set, it sets the GMT time. Pay attention to the difference from the local time.
• Only one resource or notResource can be set in an ACL rule at the same time.

Bucket ACL Supporting Coarse-grained Custom Permission

In essence, the permission corresponds to a set of BOS API operations. The BOS API includes bucket-level and object-level APIs. For example, ListObjects is used to view the list of all objects in a bucket, so it is a bucket-level API. PutObject is used to upload a file, so it is an object-level API. Therefore, after you set the permission, you need to set the corresponding resource or notResource in the ACL file. By default, all bucket-level and object-level operations can match with each other when the resource field is not entered, or the bucket name is entered.

The Bucket ACL supports the following coarse-grained custom permissions:

Bucket ACL Supporting Fine-grained Custom Permission

To ensure the high security of your data stored in BOS and meet your more fine-grained permission access control of the BOS resources, BOS expansively supports various fine-grained permissions based on the coarse-grained and fine-grained permissions of READ, LIST, WRITE, MODIFY, and FULL_CONTROL.

The bucket related permissions are described as follows:

The object related permissions are described as follows:

Descriptions:

• The new coarse-grained and fine-grained permissions and the previous ones of READ, LIST, WRITE, FULL_CONTROL, MODIFY and GetObject and RestoreObject do not affect each other. Among them, READ, WRITE, LIST, FULL_CONTROL and MODIFY are coarse-grained permission.
• The coarse-grained permissions are superior to the fine-grained permissions. If both coarse-grained and fine-grained permissions are configured, the coarse-grained permissions overwrite the fine-grained permissions, and the coarse-grained permissions should prevail.
• The bucket-level fine granularity refers to related operations for buckets.
• The object-level fine granularity refers to related operations for objects.

Bucket ACL Supports Deny and Data Tamper-proof Features

Bucket ACL also supports the effect field, which is used to set the effect of this permission. Effect can be configured as Allow or Deny.

Descriptions:

• When the effect is not configured, it is implicitly set to “Allow” by default. When the effect is configured as “Allow”, it is explicitly set to “Allow”. The case that the effect is not configured is equivalent to the case that the effect is configured as “Allow”.
• The semantics of Deny is superior to Allow. When the user configures both Allow and Deny, the Deny should prevail. When the coarse-grained permissions are configured as “Deny”, they are not allowed regardless of whether the fine-grained permissions are configured as “Allow”.
• When the coarse-grained permissions are configured as “Allow”, but the fine-grained permissions are configured as “Deny”, the difference set of the coarse-grained permissions and fine-grained permissions are taken. The operation of the difference set is allowed.
• At present, the READ, LIST, WRITE, FULL_CONTROL, and MODIFY permissions are coarse-grained permissions, and the other permissions are fine-grained permissions.

To avoid the risk of data deletion and tampering due to key leakage, less strict permission control, and operation error, BOS introduces the bucket data tamper-proof feature. It can achieve the bucket data tamper-proof effect by setting the combination of MODIFY, coarse-grained permission, and Deny keyword in the bucket ACL.

At present, the coarse-grained permissions related to the write operation include WRITE, FULL_CONTROL, and MODIFY, and the fine-grained permissions include PutObject, RenameObject, and DeleteObject.

There are two main ways to use Modify, i.e., Allow and Deny.

Descriptions:

• The write operation includes Add, Overwrite and Delete operations. The Add operation refers to uploading an object that did not exist previously. The Overwrite operation refers to uploading an object that existed previously.
• The coarse-grained write permission MODIFY includes the partial operation of fine-grained write permissions RenameObject and PutObject, such as PutObject, PostObject, AppendObject, CopyObject, FetchObject, and MultiUploadInitObject.
• If any one of write granularities PutObject, RenameObject, DeleteObject, WRITE, and FULL_CONTROL is configured as “Allow” and MODIFY is not configured as “Deny”, users are allowed to perform the normal write operation.

The example of Allow is shown in the table below:

The example of Deny is shown in the table below:

Request Authorization Process

When you use ACL for the access control management of the bucket, each bucket has one ACL file only, but one or more groups of ACL configuration items in each ACL can be used to define different operation permissions of different resources for different users. The accessControlList field is used to identify the beginning of the ACL body. Each group of ACL configuration items in the ACL file consists of grantee+permission+resource (or notResource)+condition. If you can authorize a request successfully, it is required to match all conditions in a group of ACL configuration items. When a request is initiated, it matches the configuration items in the ACL one by one. No authorization is made as long as one condition in a group of ACL configuration items does not match?. The ACL authorization process is shown in the figure below:

Assume that the grantee defined in the ACL file is *, i.e., all users, the permission is READ, and the resource is bucket1.

• If the request is PutObject, that is, upload the file cat.jpg to bucket1, the request is denied because PutObject does not belong to the API contained in the READ permission?.
• If the request is GetObject, that is, download the file cat.jpg from bucket1, the request can be authorized because the permission corresponding to GetObject is READ, which can match all conditions in the ACL.

**Description:** For CopyObject, the READ, GetObject, or FULL_CONTROL permission is required for the source object, and the WRITE or FULL_CONTROL permission is required for the target object.

Example

• This example mainly explains the basic usage of the grantee and permission.

  Assume that the bucket1 owner wants another Baidu AI Cloud user (userId=16147f559dd14bb294175a8bab74ff1f) to help him manage bucket1, that is, this user has the FULL_CONTROL permission for bucket1. The corresponding ACL file format is shown as follows:

  {
      "accessControlList": [
          {
              "grantee": [
                  {
                      "id": "16147f559dd14bb294175a8bab74ff1f"
                  }
              ],
              "permission": [
                  "FULL_CONTROL"
              ]
          }
      ]
  }

• This example mainly explains the usage of multiple ACL configuration items.

  If the bucket1 owner hopes that everyone can read the contents of the bucket, but only one Baidu AI Cloud user (userid=b124deeaf6f641c9ac27700b41a350a8) can manage the bucket, all users have the READ permission, while the user (userid=b124deeaf6f641c9ac27700b41a350a) has the FULL_CONTROL permission. The corresponding ACL file format is shown as follows:

        {
            "accessControlList": [
                {
                    "grantee": [
                        {
                            "id": "b124deeaf6f641c9ac27700b41a350a8"
                        }
                    ],
                    "permission": [
                        "FULL_CONTROL"
                    ]
                },
                {
                    "grantee": [
                        {
                            "id": "*"
                        }
                    ],
                    "permission": [
                        "READ"
                    ]
                }
            ]
        }

• This example mainly explains the usage of the condition field.

  If the bucket1 owner allows users (userid=10eb6f5ff6ff4605bf044313e8f3ffa5) of a specific IP address range to manage the bucket, the IP address range is defined through the condition, and these users have the FULL_CONTROL permission. The corresponding ACL file format is shown as follows:

        {
          "accessControlList": [
              {
                  "grantee": [
                      {
                          "id":"10eb6f5ff6ff4605bf044313e8f3ffa5"
                      }
                  ],
                  "permission": [
                      "FULL_CONTROL"
                  ],
                  "condition" : {
                    "ipAddress": [
                          "192.168.0.0/16",
                          "192.169.0.*",
                          "192.170.0.5"
                      ]
                  }
              }
          ]
        }

• This example mainly explains the usage of secureTransport and currentTime fields of the condition.

  If the bucket1 owner only allows users (userid=10eb6f5ff6ff4605bf044313e8f3ffa5) accessed at the specified time through HTTPS to manage the bucket, the secureTransport and currentTime address ranges are defined through the condition, and these users have the FULL_CONTROL permission. The corresponding ACL file format is shown as follows:

    {
       "accessControlList": [
            {
                "grantee": [
                    {
                        "id": "10eb6f5ff6ff4605bf044313e8f3ffa5"
                    }
                ],
                "permission": [
                    "FULL_CONTROL"
                ],
                "resource": [
                    "bucket1/*"
                ]，
                "condition": {
                    "currentTime": {
                        "dateLessThan": "2020-07-01T12:00:00Z" ,
                        "dateGreaterThan": "2018-03-01T15:00:00Z"
                    },
                    "secureTransport": true
                }
            }
        ]
    }

• This example mainly explains the usage of the referer field.

  The bucket1 owner allows users (userid=c558855ea8514c299508699b115473ef) whose referer matches the configured whitelist through the specific IP to view the bucket and object information. The referer field is used to define the whitelist to which access is allowed, stringEquals is used for exact matching, and stringLike is used for fuzzy matching. * in the stringLike represents zero to any number of characters. There can be one * at most, * can be put anywhere in the string. The corresponding ACL file format is shown as follows:

        {
           "accessControlList": [
                {
                    "condition": {
                        "referer": {
                            "stringLike": [
                                "http://www.abc.com/*"
                            ],
                            "stringEquals": [
                                "http://www.abc.com"
                            ]
                        },
                        "ipAddress": [
                            "192.168.1.1"
                        ]
                    },
                    "grantee": [
                        {
                            "id": "c558855ea8514c299508699b115473ef"
                        }
                    ],
                    "permission": [
                        "LIST"
                    ],
                    "resource": [
                        "bucket1",
                        "bucket1/*"
                    ]
                }
            ]
        }

• This example mainly explains the usage of the resource field.

  The resource field can be used to set the access permission for files and directories (prefix) in the bucket. The bucket1 owner only allows another Baidu AI Cloud user (userid=10eb6f5ff6ff4605bf044313e8f3ffa5) to have the FULL_CONTROL permission for the object with the prefix “cook”, the object with the prefix “edu/” and the object with “Travel/China National Geographic”. There is one and only one * at the end of resource field. Because the resource specified in the resource field is the object, only the object-level API operations (such as PutObject, GetObject, and DeleteObject) contained in the FULL_CONTROL permission are executed. The corresponding ACL file format is shown as follows:

        {
          "accessControlList": [
              {
                  "grantee": [
                      {
                          "id":"10eb6f5ff6ff4605bf044313e8f3ffa5"
                      }
                  ],
                  "permission": [
                      "FULL_CONTROL"
                  ],
                  "resource": [
                      "bucket1/cook*",
                      "bucket1/edu/*",
                      "bucket1/travel/China National Geographic Magazine"
                  ]
              }
           ]
        }

• This example mainly explains the usage of notResource field.

  The resource field can be used to set the access permission for the objects other than some specified files and directories (prefix) in the bucket. The bucket1 owner only allows another Baidu AI Cloud user (userid=10eb6f5ff6ff4605bf044313e8f3ffa5) to have the FULL_CONTROL permission for the objects other than those with the prefix “cook”, those with the prefix “edu/” and that with “Travel/China National Geographic”. There is one and only one * at the end of notResource field. Because the resource specified in the notResource field is the object, only the object-level API operations (such as PutObject, GetObject, and DeleteObject) contained in the FULL_CONTROL permission are executed. The corresponding ACL file format is shown as follows:

         {
           "accessControlList": [
               {
                   "grantee": [
                       {
                           "id":"10eb6f5ff6ff4605bf044313e8f3ffa5"
                       }
                   ],
                   "permission": [
                       "FULL_CONTROL"
                   ],
                   "notResource": [
                       "bucket1/cook*",
                       "bucket1/edu/*",
                       "bucket1/travel/China National Geographic Magazine"
                   ]
               }
            ]
         }

• This example mainly explains the basic usage of bucket level permission. If the bucket1 owner hopes that only one Baidu AI Cloud user (userid=b124deeaf6f641c9ac27700b41a350a8) can view the bucket information or list the object in the bucket, the user has the GetBucket permission. The corresponding ACL file format is shown as follows:

{
    "accessControlList": [
        {
            "grantee": [
                {
                    "id": "b124deeaf6f641c9ac27700b41a350a8"
                }
            ],
            "permission": [
                "GetBucket"
            ]
        }
    ]
}

• This example mainly explains the basic usage of the object-level permission.

  If the bucket1 owner hopes that everyone can read and write the object in a bucket, but only one Baidu AI Cloud user (userid=b124deeaf6f641c9ac27700b41a350a8) can manage the bucket, all users have the GetObject and PutObject permissions, while the user (userid=b124deeaf6f641c9ac27700b41a350a) has the FULL_CONTROL permission. The corresponding ACL file format is shown as follows:

    {
        "accessControlList": [
            {
                "grantee": [
                    {
                        "id": "b124deeaf6f641c9ac27700b41a350a8"
                    }
                ],
                "permission": [
                    "FULL_CONTROL"
                ]
            },
            {
                "grantee": [
                    {
                        "id": "*"
                    }
                ],
                "permission": [
                    "GetObject"，"PutObject"
                ]
            }
        ]
    } 

• This example mainly explains the basic usage of the bucket data tamper-proof.

  If the bucket1 owner does not hope one Baidu AI Cloud user (userid=b124deeaf6f641c9ac27700b41a350a88) to tamper with the data in the bucket, but allows the user to add and read the data, this user (userid=b124deeaf6f641c9ac27700b41a350a8) has the Deny MODIFY, Allow PutObject and Allow READ permissions, and the corresponding ACL file format is shown as follows:

    {
    	"accessControlList": [
    		{	
    			"effect" : "Deny",
    			"grantee": [
    				{
                        "id": "b124deeaf6f641c9ac27700b41a350a8"
                    }
                ],
                "permission": [
                    "MODIFY"
                ]
            },{	
    			"effect" : "Allow",
    			"grantee": [
    				{
                        "id": "b124deeaf6f641c9ac27700b41a350a8"
                    }
                ],
                "permission": [
                    "PutObject","READ"
                ]
            }
        ]
    }

View Access Permission

• View the access permission of a bucket. For more information, see GetBucketAcl API.
• The returned ACL is automatically added with the owner attribute.

Object Access Control

BOS supports the management of the Objectaccess control using ACL. Object ACL is permission attached to a resource, i.e., an object. In essence, it authorizes who (grantee) can perform which operations (permission).

At present, BOS can set ACL by uploading ACL files or by using CannedAcl. Both methods can be implemented through the PutObjectAcl API.

• Uploading an ACL file is to describe the Object ACL information through a JSON file. It is a high threshold to edit the ACL file directly, so BOS also supports the CannedAcl mode.
• In essence, CannedAcl encapsulates several common access control scenarios and sets the resources in the “x-bce-acl” or “x-bce-grant-read/x-bce-grant-full-control” field in the header field of PutObjectAcl directly.

Permission Supported by Object ACL

CannedACLSupported Types

Three Types of Headers Supported by CannedACL

To facilitate the permission setting, you can add CannedACL during the creation and copy of object and setting of the object ACL, and set the object access control through "x-bce-acl" or "x-bce-grant-permission" in the header field. At present, setting CannedACL and uploading ACL files in the same request are not supported. There are mainly the following header settings. Two types of headers cannot appear in one request at the same time.

Descriptions:

• If the object is an archive file, you cannot set and delete the object ACL configuration for this file before the archive file is just uploaded and restored.

The Canned ACL API can be modified through the header

• PutObject interface
• PostObject interface
• AppendObject interface
• CopyObject interface
• InitMultiUpload interface
• PutObjectAcl interface