签名认证访问

百度智能云采用统一的API鉴权认证机制，详情请见 鉴权认证机制。

原始AK/SK鉴权

• 原始AK/SK是指您在注册BOS时，系统自动分配给您的 AK（Access Key ID）/SK（Secret Access Key），主要用于对用户的调用行为进行鉴权和认证，相当于百度智能云API专用的用户名及密码。您向BOS发送的每个请求，都需要通过鉴权认证通过后，BOS才会处理您的请求。
• 移动端场景使用原始AK/SK鉴权的交互过程如下图所示：

• 将您的原始AK/SK下发到移动端势必会存在一定的安全风险，因此，原始AK/SK鉴权方式只推荐您在测试过程中使用，正式提供服务时推荐您使用STS方式鉴权。

注意： 当您在授权的时候，建议严格遵循最小权限原则，限定用户执行受限的操作（如仅授权读操作）并设置访问指定前缀的资源，避免授予过大的权限，导致预期外的越权操作，造成数据安全风险。

临时授权访问

STS简介

BOS可以通过STS机制实现第三方的临时授权访问。STS（Security Token Service）是百度智能云提供的临时授权服务。通过STS，您可以为第三方用户颁发一个自定义时效和权限的访问凭证。第三方用户可以使用该访问凭证直接调用百度智能云的API访问百度智能云资源。

说明： 这里的第三方用户主要是指您所开发的应用程序的终端用户，例如，若您是移动App开发者，您的App终端用户我们称为第三方用户。

以移动客户端访问BOS服务为例：

如您是移动App开发者，您已开通BOS服务，并且需要为您的App客户端提供访问BOS服务的权限，那么您有如下两种方式为移动客户端实现鉴权：

STS鉴权

为了让移动终端能够便捷、安全地享受到BOS服务，百度智能云研发了STS服务，来对移动场景下的安全需求进行支持。您无需开放自己的AK/SK，仅通过STS即可实现临时授权。

使用STS为APP客户端临时授权的流程如下图所示：

1. 申请访问BOS权限。

   App客户端访问BOS资源，需向AppServer申请访问权限。已经开通BOS服务的AppServer可以针对不同的App终端用户进行授权及访问资源限制。

2. 申请临时访问凭证。

   AppServer需要向STS服务申请一个临时访问凭证。AppServer通过调用STS的GetSessionToken()接口进行申请，同时需要指定资源访问权限和过期时间。GetSessionToken()的调用方法请参考GetSessionToken接口，STS服务详情请参考STS相关接口文档。

3. 返回STS凭证给AppServer。

   STS处理申请后，返回给AppServer一份临时的身份凭证（Credential），包括临时访问密钥AK/SK， SessionToken、失效时间和AppServer的用户ID等信息。AppServer可以缓存STS凭证，当多个App客户端需要的权限相同时，可以直接把缓存的凭证颁发给客户端。

4. 返回STS凭证给App客户端。

   AppServer将收到的STS凭证下发给App客户端，App客户端可以缓存STS凭证。当凭证失效时，App客户端需要向AppServer重新申请有效访问凭证。

5. App客户端使用STS凭证访问BOS资源。

   App客户端设备可以直接使用返回的STS凭证构造API请求直接访问BOS资源，BOS会感知STS访问凭证，并会依赖STS服务来验证访问凭证，正确响应用户请求。

使用STS的优点：

• 您不需要向第三方用户透露您的管理账号或AK/SK信息，您只需要向STS申请一个临时访问凭证并颁发给第三方用户即可，且这个访问凭证拥有的权限和有效期均可由您自己去定义。
• 您不需要关注该权限的撤销问题，临时访问凭证在过期后会自动失效。

GetSessionToken接口

接口描述

GetSessionToken接口用于临时授权访问时，请求返回一份临时的访问凭证（Credential）。

权限说明

请求发起人需要具有合法的AccessKeyID和SecretAccessKey才能发起请求。

请求

• 请求语法

  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"]
     }
    ]
   } 

• 请求参数

  名称	参数位置	描述	默认值	是否必选
  durationSeconds	Query参数	临时访问凭证的有效时长，即一次请求STS后，在有效时长内可使用此临时访问凭证多次访问BOS资源，不需要重复请求STS。数据类型：int。单位为秒，最长可指定为129600秒（36小时）。	43200（12小时）	否

• 请求头域

  名称	数据类型	描述	默认值	是否必选
  Authorization	string	认证字符串，计算方法请参考生成认证字符串。	-	是

• 请求元素

  本接口的请求元素是权限控制的主要部分。请求元素由一条或多条acl配置项组成，每条acl配置项间相互独立。

  名称	数据类型	描述	默认值	是否必选	父节点
  accessControlList	array	标识acl主体的开始，由一或多组acl配置项组成。	-	是	-
  effect	string	指定与该条acl配置项匹配的Request能否执行，取值为Allow或Deny。Allow表示可以执行；Deny表示拒绝执行。	-	是	accessControlList
  eid	string	标识acl配置项的id 。	-	否	accessControlList
  id	string	acl的标识符。	-	否	-
  permission	array	acl配置项所影响的权限,可选值为READ、WRITE、LIST、MODIFY、FULL_CONTROL和GetObject等细粒度权限。	-	是	accessControlList
  region	string	acl配置项影响的区域，"*"表示所有区域。	-	是	accessControlList
  resource	array	acl配置项所影响的资源，支持通配符。如：<BucketName>/<ObjectKey>或<BucketName>/xxx*	-	是	accessControlList
  service	string	acl配置项影响的服务组件，"*"表示所有服务。	-	是	accessControlList

说明：

• 由于GetSessionToken的响应结果会包含STS凭证，强烈建议通过HTTPS协议调用。
• service：以BOS服务为例，取值为"service":"bce:bos"。

• resource：当"service":"bce:bos"时，resource支持Bucket和Object。

  • 当resource为Bucket时，其取值为<BucketName>。例如，"resource"：["sts-bucket-1"]；
  • 当resource为Object时，其取值为<BucketName/ObjectName>。例如，"resource"： ["sts-bucket-1/object1"]；
  • 此外，resource还支持通配符 *，表示Bucket下所有Object。例如："resource"： ["sts-bucket-1/*"]。

• permission： BOS服务支持READ/WRITE/LIST/MODIFY/GetObject权限。每个权限对应一组API请求如下：

  • READ权限对应的操作有：

    • GetBucketLocation
    • HeadBucket
    • GetObject
    • GetObjectMeta
    • ListParts

  • WRITE权限对应的操作有：

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

  • LIST权限对应的操作有：

    • ListObjects
    • ListMultipartUploads

  • MODIFY权限对应的操作有：

    • PutObject
    • PostObjcet
    • AppendObject
    • RenameObject
    • CopyObject
    • FetchObject
    • PutSymlink

  • GetObject权限对应的操作有：

    • GetObject
    • GetObjectMeta

注意：

• 如在请求元素中不指定acl，则默认返回的临时权限Credential与您当前拥有的READ/WRITE权限相同，授权给第三方用户后，可能会给您的账户资源带来风险，建议您在临时授权时明确指定acl，规避风险。如果请求Body为空，则默认返回的STS凭证与您当前拥有的权限相同。
• 在您指定acl时，建议严格遵循 最小权限原则，限定用户执行受限的操作（permission字段）并设置访问指定前缀的资源（resource字段），避免造成数据安全风险。

响应

• 响应头域

  本接口只用到了公共响应头。

• 响应元素

示例

• 请求示例

  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"]
      }
     ]
    }

• 响应示例

  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配置modify权限使用示例（MODIFY权限定义见下方bucket权限控制）

  • Deny MODIFY + Allow WRITE : 这种配置下允许新增、删除操作，禁止覆盖操作

       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": ["WRITE"]
          },
          {   
          "eid":<eid>,
          "service":"bce:bos",
          "region":"bj",
          "effect": "Deny",
          "resource": ["sts-bucket-1-140683201300192-1447847972462384520478/*"],
          "permission": ["MODIFY"]
          }
         ]
        }

  • Allow MODIFY : 这种配置下只允许覆盖，不允许新增或删除

       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": ["MODIFY"]
          }
         ]
        }

STS鉴权过程

当第三方用户使用返回的临时AK/SK以及SessionToken向百度智能云的服务端发起请求时，服务端是如何完成临时鉴权验证的呢？

• 首先，服务端会验证请求的合法性。

服务器端会通过请求中的 Access Key ID 找到对应的 Secret Access Key，并提取请求中的签名字符串和signature。如果服务器端计算出来的 signature 和请求中提供的 signature 一样，即认为该请求是合法的；否则认为该请求是非法的，将拒绝处理这次请求。

• 然后，服务端会验证请求者是否对于资源有操作的权限。

  服务器端会将该次请求与申请临时Token时GetSessionToken携带的acl列表逐条对比，对比后的处理逻辑如下图：

  

• 举例说明：

假设在申请临时token时的acl如下：

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

被授权的第三方想要对sts-bucket-1下的img.jpg进行GetObject操作。 由于GetOject对应READ权限，所以这次请求可以写成：

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

和上面的acl进行匹配时会失败，因为resource并不匹配。如果当时申请临时token时resource写成sts-bucket-1/img.jpg或sts-bucket-1/*则可以成功匹配。

使用STS凭证访问BOS服务

App客户端拿到STS临时凭证后，通过其中Session Token以及临时访问密钥（AK/SK）构建签名。签名方式同 签名认证访问。需要注意如下关键点：用户使用的签名密钥为STS提供的临时访问密钥（AK/SK）。

与普通的API接口相比，使用STS凭证调用API时，只需要在请求中增加x-bce-security-token: <session-token>即可，以PutObject为例：

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 

说明：

• 目前STS已支持READ、WRITE、LIST、MODIFY、FULL_CONTROL和GetObject等细粒度的API请求。
• STS具有缓存机制，在有效时间内可使用同一访问凭证多次访问BOS资源，不需要重复发送STS请求。通过修改请求中的durationSeconds参数可调整临时访问凭证的有效时间。

Bucket权限控制

权限控制概述

BOS支持使用ACL对Bucket权限进行管理。Bucket ACL是附属于资源即某个Bucket的权限，其本质上是授权谁（grantee）可以执行哪些操作（permission）。为了方便用户更精细地控制Bucket里的资源，Bucket ACL支持resource和notResource字段。Resource字段用于实现对指定范围的prefix和object粒度的权限控制，notResource字段用户实现对指定范围外的prefix和object粒度的权限控制。 此外，Bucket ACL还支持condition字段，Condition字段可以用来设置访问者的IP、Referer等信息。

为了保障您存储在BOS中数据的高安全性，我们为您提供了丰富的多级权限管理能力。 BOS的权限体系分为如下三级：

• Bucket标准权限（即CannedACL）
• 粗粒度自定义权限
• 细粒度自定义权限

BOS 目前可以通过 上传ACL文件 和 使用CannedAcl 两种方式来设置 ACL，两种方式都通过 PutBucketAcl接口 实现。上传ACL文件是通过一个JSON文件来描述谁（grantee）在什么条件下（condition）可以对什么资源（resource 或 notResource）执行哪些操作（permission）。直接编辑ACL文件门槛较高，因此 BOS 还支持 CannedAcl 方式。CannedAcl 本质上就是对几种常见的权限控制场景进行了封装，直接在 PutBucketAcl 的头域中的 x-bce-acl 字段对资源进行设置。

使用CannedAcl方式的权限控制

CannedAcl是一种方便用户使用的方式，对常见的几种权限情况进行了封装。通过在PutBucketAcl的头域中的 x-bce-acl 字段对该资源进行设置的。例：x-bce-acl:public-read。字段区分大小写。

当前支持的CannedAcl包括：

说明：通过PutBucket创建的新Bucket权限默认是private。

上传ACL文件方式的权限控制

ACL文件格式

PutBucketAcl 可以通过上传一个ACL文件的方式对访问权限进行设置。BOS ACL 使用Json格式的策略描述语言，命名方法为首字母小写的驼峰命名格式，字段区分大小写。

BOS ACL内容可以使用 BOS ACL编辑工具 获取权限配置模板及自定义配置。

• 字段总览：

说明：

• 所使用的ACL格式如上所述；在上传ACL文件时，可不带Owner属性(json字段标识Bucket的Owner)；如果带有Owner属性，则其id值必须为Bucket的Owner id
• 上传的ACL文件不大于20KB。
• 若用户使用PutBucketAcl接口的时候，在Http报文的Header(Canned ACL)和Body中同时设置了ACL，则返回错误码400，错误说明为“参数不正确”。
• 设置currentTime子字段值时，设置的是GMT时间，注意与本地时间的差别。
• 在一条ACL规则中，同时只能存在一个resource或一个notResource的设置。

Bucket ACL支持粗粒度自定义权限

permission本质上对应一组BOS API操作。BOS API分为bucket级别API和object级别的API，如ListObjects用来查看一个bucket中的所有Object列表，是一个bucket级别API，PutObject用来上传一个文件，是一个object级别API。 所以在ACL文件里，当设置好permission后，需要设定相应的resource或notResource。缺省情况下resource字段不填或填bucket名称，就可以同时匹配bucket级别和object级别的所有操作。

• Bucket ACL支持如下粗粒度自定义权限：

Bucket ACL支持细粒度自定义权限

为了保障您存储在BOS中数据的高安全性和满足您对BOS资源更加细粒度的进行权限访问控制，BOS在支持READ、LIST、WRITE、MODIFY、FULL_CONTROL这几种粗细粒度的基础上，现在扩展支持了各类细粒度权限。

• Bucket相关权限说明如下：

• Object相关权限说明如下：

说明：

• 新增的粗细粒度和以前的READ、LIST、WRITE、FULL_CONTROL、MODIFY、GetObject、RestoreObject这几种粗细粒度互不影响，其中READ，WRITE，LIST，FULL_CONTROL， MODIFY属于粗粒度权限。
• 粗粒度权限高于细粒度权限，如果既配了粗粒度权限又配了细粒度权限，粗粒度权限会覆盖细粒度权限，以粗粒度为主。
• Bucket级别的细粒度是指对Bucket进行的相关操作。
• Object级别的细粒度是指对Object进行的相关操作。

Bucket ACL支持Deny和数据防篡改

Bucket Acl同时支持effect字段，用于设置该条权限的效果，effect支持Allow和Deny这两种配置方式。

说明：

• 在不配置effect的情况下，默认情况下是隐式Allow。在配置effect的情况下，当值为Allow时是显式Allow；在不配置effect和配置effect并且其值为Allow的况下，这两种情况是等价的。
• Deny的语义高于Allow，当用户既配了Allow也配了Deny的情况下，以Deny为准，拒绝通过；Deny了粗粒度权限，不管细粒度权限是否允许，都不允许通过。
• Allow了粗粒度权限，但是Deny了细粒度权限，那么就取粗粒度与细粒度的差集，差集部分的操作是允许通过的。
• 目前READ、LIST、WRITE、FULL_CONTROL、MODIFY权限为粗粒度权限，其余的权限可以归结为细粒度权限。

为了解决由于密钥泄露、权限控制不严格、操作失误等带来的数据删除、篡改风险，BOS推出Bucket数据防篡改的功能，通过在Bucket Acl设置 MODIFY 粗粒度权限和 Deny 关键字组合就可以起到Bucket数据防篡改的效果。例如：如果想要设置禁止覆盖与删除Object，可通过同时设置Deny MODIFY + Deny DeleteObject 达到效果。

目前涉及到写的粗粒度有 WRITE、FULL_CONTROL、MODIFY，细粒度有 PutObject、RenameObject、DeleteObject。

MODIFY的使用方式主要有两大类，Allow 和 Deny 这两种。

说明：

• 写操作，包括新增操作、覆盖操作和删除操作，新增操作是指：新上传一个Object，这个Object以前是不存在的，覆盖操作是指：上传一个Object，这个Object以前是存在的。
• MODIFY粗粒度写权限包含RenameObject细粒度写权限和PutObject细粒度写权限下面的部分操作，如PutObject、PostObject、AppendObject、CopyObject、FetchObject、MultiUploadInitObject等。
• 如果配置允许了PutObject、RenameObject、DeleteObject、WRITE、FULL_CONTROL几种写粒度之中的任意一种，并且没有配置Deny MODIFY，那么允许用户进行正常的写操作。

Allow示例

Deny示例

数据安全提示：

在您为用户授权时，建议严格遵循最小权限原则，限定用户执行受限的操作并设置访问指定前缀的资源，避免授予过大的权限，导致预期外的越权操作，造成数据安全风险。包括但不限于以下典型场景：

• 粗粒度自定义权限LIST、WRITE操作的安全风险较高，不建议向所有用户授权该操作，可通过配置grantee字段标识被授权人。
• 授权WRITE操作时，建议避免授权Bucket级别的写权限，建议配置resource字段值精确到BucketName/ObjectName/*。
• 自定义粗粒度权限中，READ权限允许读取Bucket内的Object及其相关信息，但没有列表权限，LIST权限为列表权限，可以查看指定Bucket下的Object列表以及获取所有未执行完的MultipartUpload。建议区分READ权限和LIST权限支持的操作范围，在最小范围内为用户分配权限。
• 多用户共同使用同一个Bucket时，建议通过划分Bucket区域的方式明确用户可访问的资源，授权时精确到BucketName/Userid/*。
• 当时用户同时设置了sts的MODIFY权限和bucket的MODIFY权限时：优先遵循最小权限原则，当两个维度权限无交集时，会直接禁止访问。

请求授权过程

使用ACL对Bucket进行权限管理时，每个Bucket只能有一个ACL文件，但每个ACL里可以有一组或多组ACL配置项用来定义不同用户对不同资源拥有不同操作权限，accessControlList字段用来标识acl主体的开始。ACL文件中的每组ACL配置项由grantee+permission+resource（或notResource）+condition组合而成，如果某个请求能成功授权则需要匹配一组ACL配置项中的所有条件。当一条请求过来时会逐个匹配ACL中的配置项，只要某组ACL配置项中有一个条件没有匹配上则不能通过授权，除非一组ACL配置项中的所有条件匹配上才能完成授权。ACL授权过程如下图：

假定此时ACL文件定义的grantee是*即所有用户，permission是READ，resource是bucket1。

• 如果请求为PutObject即上传文件cat.jpg到bucket1中，该请求会被拒绝，因为PutObject不属于READ permission所包含的API，所以请求不能通过。
• 如果请求为GetObject即从bucket1中下载文件cat.jpg，该请求可以通过授权，因为GetObject对应的permission是READ，匹配ACL中的所有条件，所以通过授权。

说明: CopyObject操作，需要对源Object有READ、GetObject或FULL_CONTROL权限，对目标Object有WRITE或FULL_CONTROL权限。

示例

• 该示例主要讲解grantee和permission的基础用法。

  假设bucket1的owner希望让另一个百度智能云用户（userId=16147f559dd14bb294175a8bab74ff1f）帮助自己管理bucket1，即设置该用户对bucket1拥有FULL_CONTROL权限，对应的acl文件格式如下：

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

• 该示例主要讲解多个ACL配置项的使用方法。

  bucket1的owner希望所有人都可以读取bucket的内容，但只有一个百度智能云用户（userid=b124deeaf6f641c9ac27700b41a350a8）能够管理bucket，则设置所有用户为READ权限，而userid=b124deeaf6f641c9ac27700b41a350a8的用户为FULL_CONTROL权限。对应的ACL文件格式如下：

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

• 该示例主要讲解condition字段的使用方法。

  bucket1的owner允许通过特定IP段的userid=10eb6f5ff6ff4605bf044313e8f3ffa5的用户来管理Bucket，则通过condition定义IP地址段，并授权这些用户FULL_CONTROL权限。对应的ACL文件格式如下：

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

bucket1的owner允许通过不在特定IP段的userid=10eb6f5ff6ff4605bf044313e8f3ffa5的用户来管理Bucket，则通过condition定义非IP地址段，并授权这些用户FULL_CONTROL权限。对应的ACL文件格式如下：

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

• 该示例主要讲解condition的secureTransport和currentTime字段的使用方法。

  bucket1的owner只允许通过https方式在指定时间访问的userid=10eb6f5ff6ff4605bf044313e8f3ffa5的用户来管理Bucket，则通过condition定义secureTransport、currentTime地址段，并授权这些用户FULL_CONTROL权限。对应的ACL文件格式如下：

    {
       "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
                }
            }
        ]
    }

• 该示例主要讲解referer字段的使用方法。

  bucket1的owner允许通过特定IP且referer与配置的白名单匹配的userid=c558855ea8514c299508699b115473ef的用户查看Bucket和Object信息。其中referer字段用来定义允许访问的白名单，stringEquals用于精确匹配，stringLike用于模糊匹配。stringLike中*代表0到任意多的字符，最多可以有一个*，*可以在字符串的任意位置。对应的ACL文件格式如下：

        {
           "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/*"
                    ]
                }
            ]
        }

• 该示例主要讲解resource字段的使用方法。

  resource字段可以用来对Bucket内的文件和目录（prefix）设置访问权限。 bucket1的owner只允许另一个百度智能云用户（userid=10eb6f5ff6ff4605bf044313e8f3ffa5）对“cook” 为前缀的Object、“edu/” 为前缀的Object和“travel/中国国家地理杂志”这个Object有FULL_CONTROL权限。resource字段的末尾有且只能有一个*。由于resource字段所指定资源是Object，所以只有FULL_CONTROL permission所包含的Object级别的API操作（如PutObject、GetObject、DeleteObject）会被执行。对应的ACL文件格式如下：

        {
          "accessControlList": [
              {
                  "grantee": [
                      {
                          "id":"10eb6f5ff6ff4605bf044313e8f3ffa5"
                      }
                  ],
                  "permission": [
                      "FULL_CONTROL"
                  ],
                  "resource": [
                      "bucket1/cook*",
                      "bucket1/edu/*",
                      "bucket1/travel/中国国家地理杂志"
                  ]
              }
           ]
        }

• 该示例主要讲解notResource字段的使用方法。

  notResource字段可以用来对Bucket内某些指定文件和目录（prefix）之外的Object设置访问权限。bucket1的owner只允许另一个百度智能云用户（userid=10eb6f5ff6ff4605bf044313e8f3ffa5）对除“cook”为前缀的Object、“edu/”为前缀的Object和“travel/中国国家地理杂志”这个Object之外的其它Object有FULL_CONTROL权限。notResource字段的末尾有且只能有一个*。由于notResource所指定资源是Object，所以只有FULL_CONTROL permission所包含的Object级别的API操作（如PutObject、GetObject、DeleteObject）会被执行。对应的ACL文件格式如下：

         {
           "accessControlList": [
               {
                   "grantee": [
                       {
                           "id":"10eb6f5ff6ff4605bf044313e8f3ffa5"
                       }
                   ],
                   "permission": [
                       "FULL_CONTROL"
                   ],
                   "notResource": [
                       "bucket1/cook*",
                       "bucket1/edu/*",
                       "bucket1/travel/中国国家地理杂志"
                   ]
               }
            ]
         }

• 该示例主要讲解Bucket级别的权限示例的基础用法。 bucket1的owner希望只有一个百度智能云用户（userid=b124deeaf6f641c9ac27700b41a350a8）能够查看bucket的信息或者列出Bucket下面的Object，则设置这个用户为GetBucket权限。对应的ACL文件格式如下：

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

• 该示例主要讲解Object级别的权限示例的基础用法。

  bucket1的owner希望所有人都只可以对Bucket里面的Object进行读和写，但只有一个百度智能云用户（userid=b124deeaf6f641c9ac27700b41a350a8）能够管理bucket，则设置所有用户为GetObject，PutObject权限，而userid=b124deeaf6f641c9ac27700b41a350a8的用户为FULL_CONTROL权限。对应的ACL文件格式如下：

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

• 该示例主要讲解Bucket防数据篡改示例的基础用法。

  bucket1的owner不希望一个百度智能云用户（userid=b124deeaf6f641c9ac27700b41a350a8）篡改Bucket的数据，但是允许其新增数据和读取数据，则设置userid=b124deeaf6f641c9ac27700b41a350a8的用户权限为Deny MODIFY、Allow PutObject、Allow READ，对应的ACL文件格式如下：

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

查看访问权限

• 查看某Bucekt的访问权限，详见GetBucketAcl接口。
• 返回的ACL会自动加上Owner属性。

Object权限控制

BOS支持使用ACL对Object权限进行管理。Object ACL是附属于资源即某个Object的权限，其本质上是授权谁（grantee）可以执行哪些操作（permission）。

BOS目前可以通过上传ACL文件和使用CannedAcl两种方式来设置ACL，两种方式都可以通过PutObjectAcl接口实现。

• 上传ACL文件是通过一个JSON文件来描述Object ACL信息。直接编辑ACL文件门槛较高，因此BOS还支持CannedAcl方式。
• CannedAcl本质上就是对几种常见的权限控制场景进行了封装，直接在PutObjectAcl的头域中的“x-bce-acl”字段或者x-bce-grant-read/x-bce-grant-full-control字段对资源进行设置。

Object ACL支持的permission权限

CannedACL支持类型

CannedACL支持的三种header

为了方便权限设置，在创建Object、复制Object及设置Object ACL时可以添加CannedACL，通过头域的"x-bce-acl"或者"x-bce-grant-permission'来设置Object访问权限，目前不支持在同一请求中同时设置CannedACL和上传ACL文件。主要有以下header设置方式, 两种类型的header不可以同时在一个请求中出现。

说明：

• 如果object是归档类型的文件，那么该文件在归档文件刚上传和取回过程完成前，不能设置和删除object acl配置。

可通过Header修改Canned ACL的接口

• PutObject接口
• PostObject接口
• AppendObject接口
• CopyObject接口
• InitMultiUpload接口
• PutObjectAcl接口