阿里云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目前可以通过上传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格式的策略描述语言，命名方法为首字母小写的驼峰命名格式，字段区分大小写。

字段总览：

字段数据类型说明是否必须父节点accessControlListlist标识acl主体的开始，由一或多组acl配置项组成，其中acl配置项由grantee+permission+resource+condition组合而成。是无+granteelist标识被授权人。是accessControlList++idstring标识被授权人的Account ID，用户的Account ID可以登录控制台点击账户名下的“用户信息->基本信息”查看。是grantee+permissionlistACL配置项所影响的权限，可选值为READ、LIST、WRITE、和GetObject。权限详细解释请参见"Bucket ACL支持的permission权限"。是accessControlList+resourcelistACL配置项所影响的资源，表示对resource指定范围的资源设置访问权限，支持通配符。如：<BucketName>/<ObjectKey>或<BucketName>/xxx*。 resource不填或填Bucket名称，等同于resource字段设为[<bucketName>, <bucketName>/*]，即对Bucket和所有Object设置访问权限。否accessControlList+notResourcelistACL配置项所影响的资源，表示对notResource指定范围以外的资源设置访问权限，支持通配符。如：<BucketName>/<ObjectKey>或<BucketName>/xxx*，表示对BucketName中ObjectKey之外的Object或者以XXX为前缀的Object之外的其他Object设置访问权限。如果notResource字段不填则等同于没有配置notResource，即采用默认配置，对Bucket及所有Object设置访问权限。否accessControlList+conditionlistACL配置项所包含的限制条件，支持配置IP地址和Referer名单否accessControlList++ipAddresslist标识授予访问权限的ip否condition++refererstring标识授予访问权限的referer否condition+++stringLikestring标识referer白名单中模糊匹配的地址否referer+++stringEqualsstring标识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/中国国家地理杂志"          ]      }   ]}