跳至主要內容

CGI 鉴权控制

王金城大约 4 分钟

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 中加入 AppKey，可以使用 UserHeaderConsts.CGI_APP_KEY 在 request 中获取它，并进行更加详细的权限控制。

获取 Access token

  1. access_token 是接口的全局唯一接口调用凭据，接口调用各接口时都需使用 access_token。开发者需要进行妥善保存。
  2. 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 公钥。
  4. 如果时多租户云平台，那么必须在 header 中添加 Tenant-Sn 租户编码。获取 token 和获取 RSA 公钥都需要添加。

接口调用请求说明

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

重要

此接口为获取 AccessToken 的接口，并且 ticket 值必须使用 RSA 加密。

请求参数

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

获取加密公钥

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

重要

此接口不是获取 AccessToken 的接口，而是加密 ticket 的 RSA 公钥获取接口。

参数加密说明

  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
40002存在无效参数
40003非法参数：加密参数无效，需要加密参数的参数，无法进行解密。
  1. 检查 publicKey 是否正确
  2. 检查 ticket 是否进行 URL 编码后再传输
  3. 确认 RSA 加密的 keySize 是否为 2048
40006操作失败，通用的失败操作
40011操作失败，JSON 解析失败。
  1. 检查 ticket 加密前是否为标准 JSON 结构
40100未经授权的，需要身份认证
50000系统异常

使用 Access token

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