金山文档开放平台

主题

回到顶部
本页内容

小程序授权

小程序登录授权是基于标准的 OAuth 2.0 协议实现的，通过金山文档帐号授权登录第三方小程序的能力。

准备工作

在使用小程序登录授权能力之前，你需要先仔细阅读服务商指南，根据文档中的指示在开发者后台创建一个应用，并获得应用的 app_id 和 app_key。

第一步：获取授权码

跳转金山文档小程序进行用户授权获取，小程序跳转请参考微信小程序官方文档

wx.navigateToMiniProgram({
  appId: 'wx5b97b0686831c076', //金山文档小程序id
  path: 'pages/thirdPartyAuth/thirdPartyAuth?appId=${appId}&scope=access_personal_files,download_personal_files&switchAccount=true',
  success(res) {
    // 打开成功
  }
})

跳转传递参数说明

名称类型是否必传说明
appId
string
是
应用 APPID，查看应用信息
scope
string
是
需申请的权限，用,分割，具体类型请参照 scope 权限说明
switchAccount
boolean
否
是否打开账号切换弹出层，默认为false，不打开
state
string
否
由用户自定义，授权成功后会带回

金山文档小程序回跳

用户确定授权后，金山文档小程序将采用navigateBackMiniProgram，返回原小程序：

wx.navigateBackMiniProgram({
  extraData: {
    code: 'xxxxxx'，
    state:'xxxxx'
  },
})

三方小程序在 app.js 的 onshow 里获取授权码 

onShow(object:any) {
    console.log(object.referrerInfo.extraData) //{code:"xxxxxx", state:'xxxxx'  }
}

第二步：获取令牌

提示

由于应用appkey和获取到的access_token安全级别比较高，后续刷新access_token、通过access_token获取用户信息等步骤，必须从服务器调用接口。

接口信息

请求方法： GET

请求路径： /api/v1/oauth2/access_token

请求主机：developer.kdocs.cn

签名方式： 无

Header 参数

名称是否必填说明
Content-Type
是
固定为:application/json

Query 参数

名称类型是否必填说明
code
string
是
用户授权返回 code
app_id
string
是
应用 APPID
app_key
string
是
应用 APPKEY

请求地址示例 

[GET] https://developer.kdocs.cn/api/v1/oauth2/access_token?code={code}&app_id={APPID}&app_key={APPKEY}

返回参数

名称类型说明
code
int
非 0 表示失败，参考错误码说明
+
data
access_token {}
令牌内容

返回示例 

{
  "code": 0,
  "data": {
    "app_id": "SX20220706XGEQGL",
    "access_token": "XiDvqrCkvBtAAooijpoMyHQiyeXUhPjk",
    "expires_in": 86400,
    "refresh_token": "oWtTFhASVZhwKpwOaxNtoRTourVnPxCC"
  },
  "result": "ok"
}

第三步：刷新过期的令牌

由于access_token的有效期较短，当access_token过期后，可以使用refresh_token进行刷新，refresh_token有效期为 90 天，当refresh_token失效之后，需要用户重新授权。

使用refresh_token刷新access_token时，会返回一个新的access_token，原access_token自动失效。

接口信息

请求方法： POST

请求路径： /api/v1/oauth2/refresh_token

请求主机：developer.kdocs.cn

签名方式： 无

Header 参数

名称是否必填说明
Content-Type
是
固定为:application/json

Query 参数

名称类型是否必填说明
app_id
string
是
应用唯一标识

Body 参数

名称类型是否必填说明
app_key
string
是
应用密钥
refresh_token
string
是
填写通过code获取到的refresh_token参数

请求地址示例 

[POST]  https://developer.kdocs.cn/api/v1/oauth2/refresh_token?app_id={app_id}

{
    "app_key": "{app_key}",
    "refresh_token": "{refresh_token}"
}

返回参数

名称类型说明
code
int
非 0 表示失败，参考错误码说明
+
data
refresh_token {}
新的令牌内容

返回示例 

{
  "code": 0,
  "data": {
    "access_token": "XiDvqrCkvBtAAooijpoMyHQiyeXUhPjk",
    "app_id": "SX20220706XGEQGL",
    "expires_in": 7776000,
    "refresh_token": "oWtTFhASVZhwKpwOaxNtoRTourVnPxCC"
  },
  "result": "ok"
}

关键字段说明

字段说明有效期描述
code
授权码
5 分钟
通过服务商前端发送至服务商后端，被换取令牌接口消费后会失效
access_token
令牌
24 小时
储存在服务商后端，所有与开放平台的通信都在后端完成，有效的避免令牌被泄露
refresh_token
刷新令牌
90 天
用于对令牌进行刷新，防止频繁进行登录授权，提升用户体验