对象存储BOS

    访问控制

    签名认证访问

    百度智能云采用统一的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客户端临时授权的流程如下图所示:

    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?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参数 临时访问凭证的有效时长。数据类型: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?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鉴权过程

    当第三方用户使用返回的临时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: <AuthorizationString> 
    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组合而成。
    +effectstring指定与该条acl配置项匹配的Request能否执行,取值为Allow或Deny。Allow表示可以执行;Deny表示拒绝执行。accessControlList
    +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属性(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支持如下粗粒度自定义权限:

    权限名称 权限支持的操作
    READ 允许读取Bucket内的Object及其相关信息,但没有列表权限,具体操作权限包含GetBucketLocationHeadBucketGetObjectGetObjectMetaListPartsRestoreObject。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级别。
    RestoreObject 该权限表示允许用户取回归档类型文件
    DeleteObject 该权限表示允许用户进行删除单个Object或者批量删除Object的相关操作
    RenameObject 该权限表示允许用户对Object进行重命名(Rename)
    ListParts 该权限表示允许用户列出三步上传过程中指定的UploadId所有已经上传成功的Part,用户可以查看三步上传的当前进度
    GetObjectAcl 该权限表示允许用户获取Object Acl
    PutObjectAcl 该权限表示允许用户新增Object Acl和删除Object Acl

    说明:

    • 新增的粗细粒度和以前的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支持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这两种。

    说明:

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

    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粗粒度写权限 这种场景下,在配置了细粒度写权限下的操作不允许新增、删除,也不允许覆盖;其余的细粒度写权限下面的操作允许新增、删除,但是不允许覆盖

    请求授权过程

    使用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,以逗号分隔

    说明:

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

    可通过Header修改Canned ACL的接口

    一篇
    错误码
    一篇
    Bucket相关接口