所有文档

          对象存储 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 array 标识acl主体的开始,由一或多组acl配置项组成。 - -
            effect string 指定与该条acl配置项匹配的Request能否执行,取值为AllowDenyAllow表示可以执行;Deny表示拒绝执行。 - accessControlList
            eid string 标识acl配置项的id 。 - accessControlList
            id string acl的标识符。 - -
            permission array acl配置项所影响的权限,可选值为READWRITELISTGetObject - 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/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格式的策略描述语言,命名方法为首字母小写的驼峰命名格式,字段区分大小写。

          字段总览:

          字段数据类型说明是否必须父节点
          accessControlListarray标识acl主体的开始,由一或多组acl配置项组成,其中acl配置项由grantee+permission+resource+condition组合而成。
          +effectstring指定与该条acl配置项匹配的Request能否执行,取值为Allow或Deny。Allow表示可以执行;Deny表示拒绝执行。accessControlList
          +granteearray标识被授权人。accessControlList
          ++idstring标识被授权人的Account ID,用户的Account ID可以登录控制台点击账户名下的“用户信息->基本信息”查看。grantee
          +permissionarrayACL配置项所影响的权限,可选值为READLISTWRITE、和GetObject。权限详细解释请参见"Bucket ACL支持的permission权限"。accessControlList
          +resourcearrayACL配置项所影响的资源,表示对resource指定范围的资源设置访问权限,支持通配符。如:<BucketName>/<ObjectKey>或<BucketName>/xxx*。 resource不填或填Bucket名称,等同于resource字段设为[<bucketName>, <bucketName>/*],即对Bucket和所有Object设置访问权限。accessControlList
          +notResourcearrayACL配置项所影响的资源,表示对notResource指定范围以外的资源设置访问权限,支持通配符。如:<BucketName>/<ObjectKey>或<BucketName>/xxx*,表示对BucketName中ObjectKey之外的Object或者以XXX为前缀的Object之外的其他Object设置访问权限。如果notResource字段不填则等同于没有配置notResource,即采用默认配置,对Bucket及所有Object设置访问权限。accessControlList
          +conditionarrayACL配置项所包含的限制条件,支持配置IP地址和Referer名单accessControlList
          ++ipAddressarray标识授予访问权限的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,具体操作权限包含ListObjectsListMultipartUploads。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的接口

          上一篇
          错误码
          下一篇
          Service相关接口