跳到主要内容
2023-12-13 02:52 更新版本:latest

签名方式

使用 App ID 和 App Secret 签名,用于石墨服务器(私有部署则为接入方提供的部署服务器)验证接入方的请求合法性。

签名后的结果(即 signature 的值)为 JSON Web Token(简称为 JWT)格式字符串,其结构包括 Header、Payload、Signature 三个部分。

JWT 通常形式为 xxxxx.yyyyy.zzzzz

  • Header 部分

    • 默认包含的字段:alg 、typ

      • alg 表示签名算法,通常默认为 HS256
      • typ 标识 Token 类型,JSON Web Token 的类型默认为 JWT
    • 添加 kid 字段,值为 App ID

  • Payload 部分

    • 仅添加 exp 字段即可,值为 JWT 的过期时间的秒数 ,例如 1612411882 (如当前时间的秒数值比 exp 字段的值要小,说明还没有到达过期时间,此签名不会被判断为失效)

    • 当请求 /admin 相关 API 时,会额外增加 fileId 信息

签名前的数据结构:

Header

{
"alg": "HS256", // 默认字段
"typ": "JWT", // 默认字段
"kid": "your AppId"
}

Payload

{
"exp": 1612411882
}

Payload 参数

字段名字段名值示例必选说明
expnumber1612411882签名的过期时间称
scopestringlicense用于访问某些限定 scope 的 API,详细信息请参考对应的 API 说明

Java 示例:

https://github.com/auth0/java-jwt 为例

<dependency>
<groupId>com.auth0</groupId>
<artifactId>java-jwt</artifactId>
<version>4.4.0</version>
</dependency>
// JDK8或以上
// “获取App详情”和“更新App回调地址”接口需要带上 scope: license
String signature = JWT.create()
// .withClaim("scope", "license") // 如果调用需要scope参数的接口,需要添加此行,且将过期时间改为4分钟
.withKeyId("your shimo sdk AppId")
.withExpiresAt(new Date().toInstant().plus(7, ChronoUnit.DAYS))
.sign(Algorithm.HMAC256("your shimo sdk AppSecret"));