金山文档开放平台

主题

回到顶部
本页内容

Web 授权

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

准备工作

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

注意

在开发者后台申请应用时，请注意回调地址的正确填写，此处的授权流程依赖该地址进行授权码的传递。

第一步：获取授权码

授权页链接 

[GET] https://developer.kdocs.cn/h5/auth?app_id={app_id}&scope={scope}&redirect_uri={redirect_uri}&state={state }

链接参数说明

名称类型是否必填说明
app_id
string
是
应用的 APPID，查看应用信息
scope
string
是
需申请的权限，用,分割，scope 权限说明
redirect_uri
string
是
应用注册的回调地址之一，采用encodeURIComponent() 处理
state
string
否
由用户自定义，授权成功后会通过重定向带回
header
string
否
是否显示页面 header，默认 false 不显示
force_login
boolean
否
是否强制用户登陆，如果为是，会注销掉用户当前的登陆状态，跳转至登陆页面，强制用户登陆一次
logout_after_auth
boolean
否
是否在授权流程结束后，退出当前用户的登陆状态

授权页

请按照上述说明填充链接参数，然后打开链接，进入开放平台授权页面。

用户点击授权后，会携带code 和 state 自动跳转至所传递的 redirect_uri。

授权页

提示

如果回调地址中含?分隔符，code 参数会采用&拼接

location.href = `${redirect_uri}?code=${code}&state=${state}`

注意

code 的有效时间为 5 分钟，过期后返回错误码 20001 表示授权码无效，开发者需要重新发起授权流程。

第二步：获取令牌

提示

由于应用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 天
用于对令牌进行刷新，防止频繁进行登录授权，提升用户体验