金山文档开放平台

主题

回到顶部
本页内容

免登流程

如果您的插件后台需要调用开放平台Open API来实现一些后台任务和文档操作，请务必先接入免登流程。

注意

如果仅仅是需要获取到当前文档已登录用户的信息，或者是辨认用户身份（获取用户唯一标识符），那么直接通过插件 SDK 获取用户OpenId和UnionId即可。但如果您的实际业务中需要调用到开放平台的Open API，那么您必须先进行免登流程，通过授权码获取到令牌。

插件实现免登流程需要后端配合，建议您合理安排前后端开发人员的协作开发。

时序图

流程的起点为用户在金山文档 WebOffice 文档内点击目标插件，系统自动弹出授权窗，点击确认授权进入插件后，依次经过插件方前端、插件方后台和开放平台，最终完成免登。

时序图中的每个关键节点在下文中均有详细描述，请跟随我们的引导一步一步的深入。

时序图

准备工作

注意

请确保您已经在开发者后台创建了插件，且能够在页面内正常查询到插件的app_id和app_key。

提示

在用户第一次进入插件时，插件平台会自动打开授权页弹窗，弹窗内会详细展示您插件的相关信息以及需要用到的权限，当用户点击确定授权时，会自动打开您的插件，并将授权关键信息内置到插件框架内。如果用户放弃授权则会该终止流程。

在用户进行授权后，会在插件启动时将授权信息内置到插件框架，我们可以通过插件 SDK 提供的接口获取该信息。所以您需要先在您的插件项目中集成插件 SDK。

获取授权码

在插件内集成好插件 SDK 后，我们就可以调用 SDK 提供的接口去获取授权码了。示例如下：

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>插件SDK</title>
    <script src="./scripts/addon-SDK-0.1.4.umd.js"></script>
  </head>
  <body>
    <div id="plugin-app"></div>
    <script>
      // 获取授权码
      const code = jssdk.sys.app.getAppAuthCode()
    </script>
  </body>
</html>

在您成功获取授权码后，便可以通过您插件后台的接口将授权码传递至插件后台以进行后续的流程。

注意

授权码是临时的（5 分钟），请在用户完成对插件的授权后的五分钟内进行授权码的传递。

获取令牌

插件方后端除了需要插件方前端传递来的授权码，还需要拿到开发者后台的插件详情页内APPID、APPKEY。有了这三个必要参数之后，您就可以向开放平台的认证中心发起 HTTP 请求，获取本插件的访问令牌和刷新令牌。

注意

由于插件的APPID、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、app_id和app_key获取到的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"
}

后续缓存方案建议

通过上述步骤获取令牌后，可以使用服务端 session 进行缓存，这样既避免了反复向认证中心发出请求，造成不必要的网页延迟，又能有效降低服务端API的调用频率，防止因突破单日最大限制而失败。

关键字段说明

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