跳至主要內容

CGI 鉴权控制

王金城大约 3 分钟

CGI 全称为公共网关接口（Common Gateway Interface），主要用于开放给第三方的接口。这一类接口我们会进行独立的权限控制，主要通过 access_token 来控制。

接口开发规范

重要

  1. 接口可以分布在不同模块，但是必须统一在 cgi_bin 目录下，如： basic-paper-mtk/cgi_bin/user/info
  2. 推荐使用 RESTful 风格，url 多个单词可以使用 - 或 _ 分割，参数使用驼峰命名法。
  3. 接口返回统一使用 ResultVO<?> 类型，不要忽略泛型的使用。

接口鉴权

  1. token 解析会在 gateway 中进行，业务接口无需再次解析。
  2. gateway 解析成功后会将请求代理到业务模块，并在 header 中加入 CGI-App-Key，可以使用这个值来进行更加详细的权限控制。

获取 Access token

access_token 是接口的全局唯一接口调用凭据，接口调用各接口时都需使用 access_token。开发者需要进行妥善保存。

access_token 的存储至少要保留512个字符空间。access_token 的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的 access_token 失效。

使用及生成方式

  1. 建议开发者使用中控服务器统一获取和刷新 access_token，其他业务逻辑服务器所使用的 access_token 均来自于该中控服务器，不应该各自去刷新，否则容易造成冲突，导致 access_token 覆盖而影响业务；
  2. access_token 的有效期通过返回的 expires_in 来传达，目前是 7200 秒之内的值。中控服务器需要根据这个有效时间提前去刷新新 access_token。在刷新过程中，中控服务器可对外继续输出的老 access_token，此时平台后台会保证在 5 分钟内，新老 access_token 都可用，这保证了第三方业务的平滑过渡；
  3. 获取 access_token 时需要使用 RSA 公钥加密。公钥随时都可能修改，所以，开发者要在每次获取 access_token 前获取最新的 RSA 公钥。

接口调用请求说明

请求方式：GET https://host/basic-paper-cloud/api/basic-paper-sso/cgi_auth/token?ticket=ticket

获取加密公钥

请求方式：GET https://host/basic-paper-cloud/api/basic-paper-sso/cgi_auth/public_key

请求参数

参数名是否必须类型描述
ticket是String通过 RSA 加密后的票据，原始数据为 JSONObject 结构，参数值记得使用 URL 编码再传输

参数加密说明

  1. 使用 RSA 加密，加密数据包中需要包含 appKey、appSecret、timestamp，其中 appKey、appSecret 是在平台后台配置的，timestamp 是当前时间戳。
  2. RSA 加密的 keySize 为 2048。
  3. 加密后的结果中会存在一些字符，所以要进行 URL 编码后再拼接。

加密前数据结构

参数名是否必须类型描述
appKey是String第三方用户唯一凭证
appSecret是String第三方用户唯一凭证密钥
timestamp是Long当前时间戳

Header 说明

参数名是否必须类型描述
Tenant-Sn否String租户编码，云平台必填

接口调用返回说明

正常情况下，会返回下述 JSON 数据包：

{
  "status": 10000,
  "msg": null,
  "data": {
    "accessToken": "accessToken",
    "expiresIn": 7200
  }
}

返回参数说明

参数名类型描述
statusnumber状态码
msgstring消息
data.accessTokenstring获取到的凭证
data.expiresInnumber有效时间

状态码说明

状态码描述
10000成功
20001授权权限不足
40000非法参数：缺少必选参数或必填为 null
40003非法参数：加密参数无效，需要加密参数的参数，无法进行解密
40006操作失败，通用的失败操作
40011操作失败，JSON 解析失败
40100未经授权的，需要身份认证
50000系统异常

使用 Access token

在访问数据接口时需要在请求头中添加 Authorization 字段，值为 Bearer accessToken。