授权机制

在调用搭搭云平台任何API前，都需要先调用认证接口完成用户身份认证，获得授权后才能继续调用其它API接口。目前搭搭云开放平台用户身份鉴权主要采用的是 OAuth2.0 和 HMAC-SHA1 请求签名机制。开发者可根据需要及应用场景使用其中一种认证即可调用搭搭云OpenAPI。

针对不同场景，建议使用的授权机制是：

  • 网页调用

    oAuth2.0 （必须通过自有web服务端转发，参阅：前端开发指南

  • 小程序/原生移动端APP/PC桌面客户端调用

    oAuth2.0 直接调用平台API

  • 服务端调用

    oAuth2.0 或 HMAC-SHA1签名（HMAC-SHA1更为安全，oAuth2.0更为简便）

OAuth2.0授权机制

OAuth2.0概述

关于OAuth2.0协议的授权流程可以参考下面的流程图，其中Client指第三方应用，Resource Owner指用户，Authorization Server是我们的授权服务器，Resource Server是API服务器。

搭搭云开放接口目前只开放 oAuth2.0 协议的账号密码模式和刷新访问令牌（即token）。

使用步骤

  • 使用账号密码，调用 GetAccessToken 接口获取后续访问的授权令牌 Access Token。此处的账号密码，是指在搭搭云的应用中开通的一个内部员工账号及对应密码。

  • 调用其它API时，在 http header 或 请求参数 中使用 Access Token，以通过接口验证

  • 调用其它API时如果返回错误，提示 Access Token 过期，则调用 RefreshAccessToken 接口刷新 Access Token

接口文档

接口 说明
GetAccessToken 获取授权Access Token
RefreshAccessToken 刷新Access Token

使用Access_Token

在后续调用其它API接口时使用 Access_Token 有两种方式：

  1. 在header里传递，形式为在 http header 里的 Authorization 域中增加 "Bearer空格Access_Token"（建议使用），如下所示：
GET  /v1/date HTTP/1.1
Host: api.dadayun.cn
Date: Tue, 28 Aug 2018 08:09:38 GMT
Authorization: Bearer Access_Token
  1. 直接使用参数，传递参数名为 access_token。（此方式为了适配某些客户端无法设置 http header 而采取的解决方案）
GET  /v1/date?access_token=abcd HTTP/1.1
Host: api.dadayun.cn
Date: Tue, 28 Aug 2018 08:09:38 GMT

HMAC-SHA1请求签名机制

此方式仅适用于服务端调用

HMAC-SHA1请求签名机制概述

在此方式下，从任意一台服务器访问搭搭云的API接口时，必须在每次调用请求的 http header 的 Authorize 域中携带加密签名字符串，该加密签名须由调用方按照搭搭云平台规定的算法生成，请求发出后，平台方按照相同规则进行计算，并与传入的签名进行验证后，结果相同则返回请用结果，否则拒绝服务并返回403错误。

具体请求时在 http header 中传入签名的格式为：


Authorization:DDY AppKey:Signature

其中，Signature 即为计算出的签名字符串。 AppKey 和 AppSecret 由搭搭云官方颁发给访问者，其中 AppKey 用于标识访问者的身份；AppSecret 是用于加密签名字符串和服务器端验证签名字符串的密钥，必须严格保密，只有搭搭云和调用者知道。

可以将 AppKey 和 AppSecret 理解为一对账号和密码，由用户在搭搭云官网控制台中获取。获取方法见：获取AppKey与AppSecret

签名算法

Authorization = base64(hmac-sha1(
              HTTP_METHOD + "\n" 
            + CONTENT-MD5 + "\n" 
            + CONTENT-TYPE + "\n" 
            + DATE + "\n" 
            + CanonicalizedDDYHeaders 
            + CanonicalizedResource))

HTTP_METHOD 表示大写的HTTP Method(如：PUT, GET, POST, DELETE) Content-Md5 表示请求内容数据的MD5值。如果请求的Header中没有传Content-MD5，则此处填入空串 CONTENT-TYPE 表示请求内容的类型 DATE 表示此次操作的时间，不能为空，目前只支持 GMT 格式，如果请求时间和API接口服务器时间相差超过5分钟，平台会判定此请求不合法，返回400错误。格式为：Thu, 07 Mar 2012 18:49:58 GMT。如果用 x-ddy-date 替代 Date，则 DATE 不能填空，需用 x-ddy-date 的值替换。 CanonicalizedDDYHeaders表示 http中的x-ddy-开始的字段组合。（见下文注意事项） CanonicalizedResource表示本次http请求资源的完整URI(统一资源标识符，不含 http:// 或 https://)。（如：/v1/form/templates/$idOrName/instances?start=0&limit=20）

注意： CanonicalizedDDYHeaders（即在 http header 中以 x-ddy-开头的域）在签名验证前需要符合以下规范:

  • head的名字需要变成小写；
  • head自小到大排序；
  • 分割head name和value的冒号前后不能有空格；
  • 每个Head之后都有一个\n，如果没有以x-ddy-开头的head，则在签名时CanonicalizedDDYHeaders就设置为空。

其他：

  1. 用来签名的字符串为UTF-8格式。
  2. 签名的方法用RFC 2104中定义的HMAC-SHA1方法，其中Key为AppSecret。
  3. content-type和content-md5在请求中不是必须的，没有的情况下，请使用空字符串 '' 代替。

调用示例

GET  /v1/date HTTP/1.1
Host: api.dadayun.cn
Date: Tue, 28 Aug 2018 08:09:38 GMT
Authorization: DDY 2552884d8e29444eba950a5c863b6e7f:xQE0diMbLRepdf3YB+FIEXAMPLE=

results matching ""

    No results matching ""