权限控制概述
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目前可以通过上传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包括：
| ACL | 添加的权限 |
|---|---|
| private（私有） | Bucket Owner获得FULL_CONTROL，其他人没有任何权限 |
| public-read（公共读） | Bucket Owner获得FULL_CONTROL，其他人获得READ权限 |
| public-read-write（公共读写） | Bucket Owner获得FULL_CONTROL，其他人获得READ和WRITE权限 |
说明：通过PutBucket创建的新Bucket权限默认是private。
上传ACL文件方式的权限控制
ACL文件格式
PutBucketAcl可以通过上传一个ACL文件的方式对访问权限进行设置。BOS ACL使用Json格式的策略描述语言，命名方法为首字母小写的驼峰命名格式，字段区分大小写。
字段总览：
| 字段 | 数据类型 | 说明 | 是否必须 | 父节点 |
|---|---|---|---|---|
| accessControlList | list | 标识acl主体的开始，由一或多组acl配置项组成，其中acl配置项由grantee+permission+resource+condition组合而成。 | 是 | 无 |
| +grantee | list | 标识被授权人。 | 是 | accessControlList |
| ++id | string | 标识被授权人的Account ID，用户的Account ID可以登录控制台点击账户名下的“用户信息->基本信息”查看。 | 是 | grantee |
| +permission | list | ACL配置项所影响的权限，可选值为READ、LIST、WRITE、和GetObject。权限详细解释请参见"Bucket ACL支持的permission权限"。 |
是 | accessControlList |
| +resource | list | ACL配置项所影响的资源，表示对resource指定范围的资源设置访问权限，支持通配符。如：<BucketName>/<ObjectKey>或<BucketName>/xxx*。 resource不填或填Bucket名称，等同于resource字段设为[<bucketName>, <bucketName>/*]，即对Bucket和所有Object设置访问权限。 | 否 | accessControlList |
| +notResource | list | ACL配置项所影响的资源，表示对notResource指定范围以外的资源设置访问权限，支持通配符。如：<BucketName>/<ObjectKey>或<BucketName>/xxx*，表示对BucketName中ObjectKey之外的Object或者以XXX为前缀的Object之外的其他Object设置访问权限。如果notResource字段不填则等同于没有配置notResource，即采用默认配置，对Bucket及所有Object设置访问权限。 | 否 | accessControlList |
| +condition | list | ACL配置项所包含的限制条件，支持配置IP地址和Referer名单 | 否 | accessControlList |
| ++ipAddress | list | 标识授予访问权限的ip | 否 | condition |
| ++referer | string | 标识授予访问权限的referer | 否 | condition |
| +++stringLike | string | 标识referer白名单中模糊匹配的地址 | 否 | referer |
| +++stringEquals | string | 标识referer白名单中精确匹配的地址 | 否 | referer |
说明：
- 所使用的ACL格式如上所述；在上传ACL文件时，可不带Owner属性；如果带有Owner属性，则其id值必须正确。
- 上传的ACL文件不大于20KB。
- 若用户使用PutBucketAcl接口的时候，在Http报文的Header和Body中同时设置了ACL，则返回错误码400，错误说明为“参数不正确”。
- 在一条ACL规则中，同时只能存在一个resource或一个notResource的设置。
Bucket ACL支持的permission权限
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支持如下permission权限：
| 权限名称 | 权限支持的操作 |
|---|---|
| READ | 允许读取Bucket内的Object及其相关信息，但没有列表权限，具体操作权限包含GetBucketLocation、 HeadBucket、 GetObject、 GetObjectMeta、 ListParts。READ权限对应的API既有bucket级别的API如GetBucketLocation，也有object级别的API如GetObject和ListParts。 |
| LIST | 列表权限，可以查看指定Bucket下的Object列表以及获取所有未执行完的MultipartUpload，具体操作权限包含ListObjects 和ListMultipartUploads。LIST权限对应的API只有bucket级别的API。 |
| WRITE | 允许创建，覆盖和删除Bucket内的Object，具体操作权限包含PutObject、 PostObject、 InitiateMultipartUpload、 UploadPart、 CompleteMultipartUpload、 AbortMultipartUpload、 AppendObject、 DeleteObject和DeleteMultipleObjects。WRITE权限对应的API只有object级别。 |
| FULL_CONTROL | 包含以上所有权限。FULL_CONTROL除了具有READ、LIST和WRITE的所有操作权限以外，还包括以下操作权限PutBucketAcl、 GetBucketACL、 PutBucketCors、 GetBucketCors和DeleteBucketCors。FULL_CONTROL权限对应的API既有bucket级别的API也有Object级别的API。 |
| GetObject | 仅支持GetObject和GetObjectMeta操作。GetObject权限对应的API只有object级别。 |
请求授权过程
使用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" ] } } ] } -
该示例主要讲解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/中国国家地理杂志" ] } ] }