授权认证

鉴权方式

知晓云开放 API 授权通过 Access Token 作为接口调用的凭证，在对开放 API 发起请求时，均需要在 HTTP Header 加入以下授权参数：

  1.   Authorization: Bearer <Access Token>

若开发者需要在发起 API 请求时进行测试环境的指定，则需要在 HTTP Header 中加入以下环境参数：

  1.   X-Hydrogen-Env-ID: <Env ID>

在不指定环境参数的情况下，默认调用生产环境的 API。

授权流程

  2.   +--------+      ID/Secrct      +--------+
  3.   |        | +-----------------> |        |
  4.   |        |                     |        |
  5.   |        |         Code        |        |
  6.   |        | <-----------------+ |        |
  7.   | Client |                     | 知晓云  |
  8.   |        |         Code        |        |
  9.   |        | +-----------------> |        |
  10.   |        |                     |        |
  11.   |        |    Access Token     |        |
  12.   |        | <-----------------+ |        |
  13.   +--------+                     +--------+

info ID/Secert 为知晓云应用的 ClientID、ClientSecret，可通过知晓云管理后台进行获取。

获取 Access Token

获取 Access Token 需要经过以下两个步骤

获取 code

接口

POST https://cloud.minapp.com/api/oauth2/hydrogen/openapi/authorize/

参数说明

Content-Type: application/json

参数 类型 必填 说明
client_id String Y 知晓云应用的 ClientID
client_secret String Y 知晓云应用的 ClientSecret

返回参数

参数 类型 说明
code String 授权码
expires_in Number code 的过期时间，单位是秒

info 获取 Code 会经过两次的 HTTP 302 Found 跳转，开发者在实现时需要允许客户端跟随跳转。

不跟随跳转示例：

  1. $ curl ifanr.com
  2. <html>
  3. <head><title>302 Found</title></head>
  4. <body bgcolor="white">
  5.   <center><h1>302 Found</h1></center>
  6.   <hr><center>nginx/1.11.5</center>
  7. </body>
  8. </html>

跟随跳转示例：

  1. $ curl -L ifanr.com
  2. <!DOCTYPE html>
  3. <html lang="zh-CN">
  4. <head>
  5.   <meta charset="UTF-8">
  6.   <meta property="og:site_name" content="爱范儿" />
  7.   <meta property="og:type" content="article" />
  8.   <meta property="og:url" content="http://www.ifanr.com" />
  9.   <meta name="MSSmartTagsPreventParsing" content="true"/>
  10.   <meta http-equiv="imagetoolbar" content="no"/>
  11.   <meta name="robots" content="all"/>
  12.   <title>  爱范儿 · 报道未来，服务新生活引领者</title>
  13.   ....

使用 code 获取 Access Token

接口地址

POST https://cloud.minapp.com/api/oauth2/access_token/

参数说明

Content-Type: application/json

参数 类型 必填 说明
client_id String Y 知晓云应用的 ClientID
client_secret String Y 知晓云应用的 ClientSecret
code String Y 授权码，通过上一步获取到的
grant_type String Y 授权类型，这里需指定为 “authorization_code”

返回参数

参数 类型 说明
access_token String 用户授权的唯一票据
token_type String token 类型
expires_in Number access_token 过期时间，单位是秒
refresh_token String 用于刷新授权有效期
scope String 权限范围

代码示例

{% tabs first=”Node”,second=”PHP” %}

{% content “first” %}

  1.   var request = require('request');
  3.   // 获取 code
  4.   var opt = {
  5.     uri: 'https://cloud.minapp.com/api/oauth2/hydrogen/openapi/authorize/',
  6.     method: 'POST',
  7.     json: {
  8.       client_id: '[[client_id]]',
  9.       client_secret: '{{client_secret}}'
  10.     },
  11.     jar: true,                // 允许记住 cookie 
  12.     followAllRedirects: true,     // 允许重定向
  13.   }
  15.   request(opt, function(err, res, body) {
  16.       getToken(body.code)  // 回调调用 getToken 函数
  17.   })
  19.   // 获取 token
  20.   function getToken(code) {
  21.     var opt = {
  22.       uri: 'https://cloud.minapp.com/api/oauth2/access_token/',
  23.       method: 'POST',
  24.       json: {
  25.         client_id: '[[client_id]]',
  26.         client_secret: '{{client_secret}}',
  27.         grant_type: 'authorization_code',
  28.         code,
  29.       }
  30.     }
  32.     request(opt, function(err, res, body) {
  33.       let token = JSON.parse(body).access_token
  34.     })
  35.   }

{% content “second” %}

  1. <?php
  2. $param = array(
  3.   'client_id' => "{$client_id}",
  4.   'client_secret' => "{$client_secret}"
  5. );
  7. // 获取 code
  8. $code_url = 'https://cloud.minapp.com/api/oauth2/hydrogen/openapi/authorize/';
  9. $code_data = postData($code_url, json_encode($param));
  11. $code_data = json_decode($code_data, true);// 使用 code 获取 Access Token
  12. $param['code'] = $code_data['code'];
  13. $param['grant_type'] = 'authorization_code';
  15. $access_token_url = 'https://cloud.minapp.com/api/oauth2/access_token/';
  16. $access_token = postData($access_token_url, $param, 'application/json'); // 获取到的 Access Token
  18. // 封装请求函数
  19. function postData($url, $param, $content_type = 'application/json') {
  20.   $ch = curl_init();
  22.   curl_setopt($ch, CURLOPT_TIMEOUT, 30);
  23.   curl_setopt($ch, CURLOPT_URL, $url);
  24.   curl_setopt($ch, CURLOPT_POST, true);
  25.   curl_setopt($ch, CURLOPT_POSTFIELDS, $param);
  26.   curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);  // 设置允许重定向
  27.   curl_setopt($ch, CURLOPT_AUTOREFERER, 1);
  28.   curl_setopt($ch, CURLOPT_COOKIEFILE, '');
  29.   curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  30.   curl_setopt($ch, CURLOPT_COOKIESESSION, true);
  31.   curl_setopt($ch, CURLINFO_CONTENT_TYPE,  $content_type);  // 设置 Content-Type，默认 application/json
  32.   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
  34.   $response = curl_exec($ch);
  35.   curl_close($ch);
  36.   return $response;
  37. }

{% endtabs %}

使用 Refresh Token 刷新 Access Token

danger 调用此接口会将之前申请的 Access Token（包括 Refresh Token）强制失效，请开发者谨慎操作。

接口地址

POST https://cloud.minapp.com/api/oauth2/access_token/

参数说明

Content-Type: application/json

参数 类型 必填 说明
client_id String Y 知晓云应用的 ClientID
client_secret String Y 知晓云应用的 ClientSecret
refresh_token String Y 刷新凭证，从申请 Access Token 接口获得
grant_type String Y 授权类型，这里需指定为 “refresh_token”

返回参数

参数 类型 说明
access_token String 用户授权的唯一票据
token_type String token 类型
expires_in Number access_token 过期时间
refresh_token String 用于刷新授权有效期
scope String 权限范围

代码示例

{% tabs refreshTokenFirst=”Node”,refreshTokenSecond=”PHP” %}

{% content “refreshTokenFirst” %}

  1.   var request = require('request');
  3.   // 刷新 Access Token
  4.   function refreshAccessToken(refreshToken) {
  5.     var opt = {
  6.       uri: 'https://cloud.minapp.com/api/oauth2/access_token/',
  7.       method: 'POST',
  8.       json: {
  9.         client_id: '[[client_id]]',
  10.         client_secret: '{{client_secret}}',
  11.         grant_type: 'refresh_token',
  12.         refresh_token: refreshToken,
  13.       }
  14.     }
  15.     request(opt, function(err, res, body) {
  16.       let token = JSON.parse(body).access_token
  17.     })
  18.   }

{% content “refreshTokenSecond” %}

  1. <?php
  2. $param = array(
  3.   'client_id' => "{$client_id}",
  4.   'client_secret' => "{$client_secret}",
  5.   'grant_type' => "refresh_token",
  6.   'refresh_token' => "{$refresh_token}"
  7. );
  9. $access_token_url = 'https://cloud.minapp.com/api/oauth2/access_token/';
  10. $access_token = postData($access_token_url, $param, 'application/json'); // 获取到的 Access Token
  12. // 封装请求函数
  13. function postData($url, $param, $content_type = 'application/json') {
  14.   $ch = curl_init();
  16.   curl_setopt($ch, CURLOPT_TIMEOUT, 30);
  17.   curl_setopt($ch, CURLOPT_URL, $url);
  18.   curl_setopt($ch, CURLOPT_POST, true);
  19.   curl_setopt($ch, CURLOPT_POSTFIELDS, $param);
  20.   curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);  // 设置允许重定向
  21.   curl_setopt($ch, CURLOPT_AUTOREFERER, 1);
  22.   curl_setopt($ch, CURLOPT_COOKIEFILE, '');
  23.   curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  24.   curl_setopt($ch, CURLOPT_COOKIESESSION, true);
  25.   curl_setopt($ch, CURLINFO_CONTENT_TYPE,  $content_type);  // 设置 Content-Type
  26.   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
  28.   $response = curl_exec($ch);
  29.   curl_close($ch);
  30.   return $response;
  31. }

{% endtabs %}

danger 开发者需要保证 Access Token 的安全性