访问控制

签名认证访问

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

临时授权访问

STS简介

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

说明:

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

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

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

原始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服务,来对移动场景下的安全需求进行支持。您无需开放自己的AK/SK,仅通过STS即可实现临时授权。

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

image.png

  1. 申请访问BOS权限。

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

  2. 申请临时访问凭证。

    AppServer需要向STS服务申请一个临时访问凭证。AppServer通过调用STS的GetSessionToken()接口进行申请,同时需要指定资源访问权限和过期时间。GetSessionToken()的调用方法请参考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申请一个临时访问凭证并颁发给第三方用户即可,且这个访问凭证拥有的权限和有效期均可由您自己去定义。
  • 您不需要关注该权限的撤销问题,临时访问凭证在过期后会自动失效。

STS服务接口

接口描述

GetSessionToken接口用于临时授权访问时,请求返回一份临时的访问凭证(Credential)。

权限说明

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

请求

  • 请求语法

    POST /v1/sessionToken HTTP/1.1
    Host: sts.bj.baidubce.com
    Date: <Date>
    Authorization: <Authorization_String>
    
  • 请求参数

    名称 描述 默认值 是否必选
    durationSeconds 临时访问凭证的有效时长。数据类型:int。单位为秒,最长可指定为129600秒(36小时)。 43200(12小时)
  • 请求头域

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

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

    名称 数据类型 描述 默认值 是否必选 父节点
    accessControlList list 标识acl主体的开始,由一或多组acl配置项组成。 - -
    effect string 指定与该条acl配置项匹配的Request能否执行,取值为AllowDenyAllow表示可以执行;Deny表示拒绝执行。 - accessControlList
    eid string 标识acl配置项的id 。 - accessControlList
    id string acl的标识符。 - -
    permission list acl配置项所影响的权限,可选值为READWRITELISTGetObject - accessControlList
    region string acl配置项影响的区域,"*"表示所有区域。 - accessControlList
    resource list 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/GetObject权限。每个权限对应一组API请求如下:

    • READ权限对应的操作有:

      • GetBucketLocation
      • HeadBucket
      • GetObject
      • GetObjectMeta
      • ListParts
    • WRITE权限对应的操作有:

      • PutObject
      • PostObjcet
      • InitiateMultipartUpload
      • UploadPart
      • CompleteMultipartUpload
      • AppendObject
      • AbortMultipartUpload
      • DeleteObject
      • DeleteMultipleObjects
      • FetchObject
    • LIST权限对应的操作有:

      • ListObjects
      • ListMultipartUploads
    • GetObject权限对应的操作有:

      • GetObject
      • GetObjectMeta

注意:如在请求元素中不指定acl,则默认返回的临时权限Credential与您当前拥有的READ/WRITE权限相同,授权给第三方用户后,可能会给您的账户资源带来风险,建议您在临时授权时明确指定acl,规避风险。如果请求Body为空,则默认返回的STS凭证与您当前拥有的权限相同。

响应

  • 响应头域

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

  • 响应元素
名称 数据类型 描述
accessKeyId string 用于STS凭证访问的AK。
expiration date 访问失效时间。
secretAccessKey string 用于STS凭证访问的SK。
sessionToken string SessionToken,使用STS凭证访问时必须携带。
userId string 您的用户ID。

示例

  • 请求示例

    POST /v1/sessionToken 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鉴权过程

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

  1. 首先,服务端会验证请求的合法性。

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

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

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

    STS

举例说明:

假设在申请临时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.jpgsts-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: <Authorization_String> 
x-bce-security-token: <SessionToken>
Content-Type: text/plain 
Content-Length: 11434

说明:目前STS只支持READ、WRITE、LIST所对应的API请求。

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包括:

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配置项所影响的权限,可选值为READLISTWRITE、和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标识授予访问权限的ipcondition
++refererstring标识授予访问权限的referercondition
+++stringLikestring标识referer白名单中模糊匹配的地址referer
+++stringEqualsstring标识referer白名单中精确匹配的地址referer
++secureTransportbool标识是否只允许https方式访问。可选值“true”、"false",不设置时视为“false”。当设置为"true"时,表示只允许https方式访问。condition
++currentTimeobjectcondition配置项所包含的时间限制条件,支持配置"dateLessThan","dateLessThanEquals", "dateGreaterThan"和"dateGreaterThanEquals",四个配置项可以任选若干进行设置,匹配有效的条件是所设置配置项均需匹配。condition
+++dateLessThanstring标识授予访问权限的时间小于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z”currentTime
+++dateLessThanEqualsstring标识授予访问权限的时间小于或者等于指定时间。标识授予访问权限的时间小于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z”currentTime
+++dateGreaterThanstring标识授予访问权限的时间大于指定时间。标识授予访问权限的时间小于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z”currentTime
+++dateGreaterThanEqualsstring标识授予访问权限的时间大于或者等于指定时间。标识授予访问权限的时间小于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z”currentTime

说明:

  • 所使用的ACL格式如上所述;在上传ACL文件时,可不带Owner属性;如果带有Owner属性,则其id值必须正确。
  • 上传的ACL文件不大于20KB。
  • 若用户使用PutBucketAcl接口的时候,在Http报文的Header和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支持如下粗粒度自定义权限:

权限名称 权限支持的操作
READ 允许读取Bucket内的Object及其相关信息,但没有列表权限,具体操作权限包含GetBucketLocationHeadBucketGetObjectGetObjectMetaListParts。READ权限对应的API既有bucket级别的API如GetBucketLocation,也有object级别的API如GetObject和ListParts。
LIST 列表权限,可以查看指定Bucket下的Object列表以及获取所有未执行完的MultipartUpload,具体操作权限包含ListObjects ListMultipartUploads。LIST权限对应的API只有bucket级别的API。
WRITE 允许创建,覆盖和删除Bucket内的Object,具体操作权限包含PutObjectPostObjectInitiateMultipartUploadUploadPartCompleteMultipartUploadAbortMultipartUploadAppendObjectDeleteObjectDeleteMultipleObjectsFetchObject。WRITE权限对应的API只有object级别。
MODIFY 用户仅可做PutObject、AppendObject等相关写入操作,不可做数据删除操作。该权限主要功能是与Deny合用防止Bucket数据被篡改
FULL_CONTROL 包含以上所有权限。FULL_CONTROL除了具有READ、LIST和WRITE的所有操作权限以外,还包括以下操作权限PutBucketAclGetBucketACLPutBucketCorsGetBucketCorsDeleteBucketCors。FULL_CONTROL权限对应的API既有bucket级别的API也有Object级别的API。

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

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

Bucket相关权限说明如下:

Bucket 相关权限 支持的操作
GetBucket 该权限表示允许用户获取Bucket内容及其相关信息,例如,列出Bucket下面的Objects、在三步上传时列出Bucket下面的所有未执行完成的Multipart Upload
GetBucketAcl 该权限表示允许用户获取Bucket Acl的信息
PutBucketAcl 该权限表示允许用户新增Bucket Acl
GetBucketCors 该权限表示允许用户获取Bucket上的跨域资源共享(CORS)的规则
PutBucketCors 该权限表示允许用户在指定的Bucket上设定或者删除一个跨域资源共享(CORS)的规则
GetBucketStyle 该权限表示允许用户获取或者列出Bucket Style的规则
PutBucketStyle 该权限表示允许用户新增或者删除Bucket Style的规则
GetBucketMirroring 该权限表示允许用户获取Bucket镜像回源的相关信息
PutBucketMirroring 该权限表示允许用户新增或者删除Bucket镜像回源的相关信息
GetCopyRightProtection 该权限表示允许用户获取Bucket的原图保护配置的信息
PutCopyRightProtection 该权限表示允许用户开启或者关闭Bucket的原图保护功能

Object相关权限说明如下:

Object 相关权限 支持的操作
PutObject 该权限表示允许用户进行上传Object的相关操作,例如PutObject、PostObject、AppendObject、FetchObject、CopyObject、三步上传、三步Copy
GetObject 仅支持GetObjectGetObjectMeta操作。GetObject权限对应的API只有object级别。
DeleteObject 该权限表示允许用户进行删除单个Object或者批量删除Object的相关操作
RenameObject 该权限表示允许用户对Object进行重命名(Rename)
ListParts 该权限表示允许用户列出三步上传过程中指定的UploadId所有已经上传成功的Part,用户可以查看三步上传的当前进度
GetObjectAcl 该权限表示允许用户获取Object Acl
PutObjectAcl 该权限表示允许用户新增Object Acl和删除Object Acl

说明:

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

Bucket ACL支持Deny和数据防篡改

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

说明:

  • 在不配置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数据防篡改的效果。

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

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

Allow的示例如下表所示:

MODIFY配置为Allow的示例 配置示例描述 备注
Allow MODIFY 只配置了Allow MODIFY,没有配置其它写粒度权限 这种场景下,只允许覆盖,不允许新增
Allow MODIFY + Allow 细粒度写权限 配置了Allow MODIFY和细粒度写权限 这种场景下,在配置细粒度写权限下的操作允许新增,并且允许任何覆盖操作
Allow MODIFY + Allow 粗粒度写权限 配置了Allow MODIFY和粗粒度写权限 这种场景下,允许任何写操作
Allow MODIFY + Allow 粗粒度写权限 + Allow 细粒度写权限 配置了Allow MODIFY和粗细粒度写权限 这种场景下,允许任何写操作,粗细粒度同时配置时以粗粒度为准
Allow MODIFY + Deny 细粒度写权限 配置了Allow MODIFY和Deny细粒度写权限 这种场景下,不允许新增,在配置细粒度写权限之外的操作允许覆盖
Allow MODIFY + Deny 粗粒度写权限 配置了Allow MODIFY和Deny粗粒度写权限 这种场景下,不允许新增,不允许覆盖
Allow MODIFY + Deny 细粒度写权限 + Allow 粗粒度写权限 配置了Allow MODIFY、Deny细粒度写权限和Allow粗粒度写权限 这种场景下,在配置细粒度写权限下面对应的操作不可以新增,也不可以覆盖;在配置了细粒度写权限之外的操作允许新增并且允许覆盖

Deny的示例如下表所示

MODIFY配置为Deny的示例 配置示例描述 备注
Deny MODIFY 只配置了Deny MODIFY,没有配置其它写粒度权限 这种场景下,不允许覆盖,不允许新增
Deny MODIFY + Deny 细粒度写权限 配置了Deny MODIFY和细粒度写权限 这种场景下,不允许覆盖,不允许新增
Deny MODIFY + Deny 粗粒度写权限 配置了Deny MODIFY和粗粒度写权限 这种场景下,不允许任何写操作
Deny MODIFY + Deny 粗细粒度写权限 配置了Deny MODIFY和粗细粒度写权限 这种场景下,不允许任何写操作,粗细粒度同时配置时以粗粒度为准
Deny MODIFY + Allow 细粒度写权限 配置了Deny MODIFY和Allow细粒度写权限 这种场景下,在配置了细粒度写权限下面的操作可以新增,不允许覆盖操作
Deny MODIFY + Allow 粗粒度写权限 配置了Deny MODIFY和Allow粗粒度写权限 这种场景下,允许任何新增操作,不允许覆盖操作
Deny MODIFY + Deny 细粒度写权限 + Allow 粗粒度写权限 配置了Deny MODIFY、Deny细粒度写权限和Allow粗粒度写权限 这种场景下,在配置了细粒度写权限下的操作不允许新增,也不允许覆盖;其余的细粒度写权限下面的操作允许新增,但是不允许覆盖

说明:

  • 写操作,包括新增操作和覆盖操作,新增操作是指:新上传一个Object,这个Object以前是不存在的,覆盖操作是指:上传一个Object,这个Object以前是存在的。
  • MODIFY粗粒度写权限包含RenameObject细粒度写权限和PutObject细粒度写权限下面的部分操作,如PutObject、PostObject、AppendObject、CopyObject、FetchObject、MultiUploadInitObject等
  • 如果配置允许了PutObject、RenameObject、DeleteObject、WRITE、FULL_CONTROL几种写粒度之中的任意一种,并且没有配置Deny 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"
                  ]
              }
          }
      ]
    }
    
  • 该示例主要讲解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权限

Object Acl支持的权限值 支持的操作
READ 该属性表示允许用户读取Object内容及其相关信息
FULL_CONTROL 该属性表示用户拥有Object的控制权限,等价于READ和put/get/delete object acl的权限

CannedACL支持类型

Acl 添加的权限
private(私有) Bucket Owner获得FULL_CONTROL,其他人没有任何权限
public-read(公共读) Bucket Owner获得FULL_CONTROL,其他人获得READ权限

CannedACL支持的三种header

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

CannedACL Header 有效值 是否必须
x-bce-acl private/public-read
x-bce-grant-read 支持多个id,以逗号分隔
x-bce-grant-full-control 支持多个id,以逗号分隔

可通过Header修改Canned ACL的接口