签名凭证-Token

用途

Token 通常用于校验与 接入方 相关的请求是否合法，具体场景参考下图：

签名中需要包含的信息

用户身份信息

Token 中一定要包含用户身份信息，即接入方需要通过此信息得知该次回调请求是哪个用户产生的。

其他希望透传的信息

“透传”指的是接入方发起的请求中携带的 Token，经过石墨 SDK 处理后，会原封不动地通过回调接口返回给接入方，石墨不会解析也不会校验 Token 是否合法（无法校验）。
因此接入方可以通过 Token 传递一些自己系统需要的东西，例如 TraceId（链路追踪ID），我们以导入场景举例：

接入方调用石墨 SDK 导入文件接口时，在 Token 中写入一个 "tracd_id": "req_abc_123"的数据。

石墨在处理导入的流程中，会请求获取当前用户信息的回调接口，来获取用户信息以及对文件的权限。

此时接入方接到该回调请求时，通过解析 Token 得知 trace_id 的值为 "req_abc_123"，从而知道该回调请求来自于调用导入文件接口。

Token 生成方式

Token 由接入方生成，最终也由接入方解析，所以石墨并不要求 Token 的格式。
我们提供三种参考方案：

方式一：JSON 明文 Token（基础版）

描述：
最简单的方法，用户信息以纯 JSON 对象形式传递。此方法提供基本的用户标识，不包含任何加密或防篡改保护。

适用场景：

开发和测试环境

可信内部网络系统

概念验证实现

安全要求较低的场景

评分：

维度	评分	说明
安全级别	⭐	无任何保护机制
实现复杂度	⭐⭐⭐⭐⭐	最简单实现
性能表现	⭐⭐⭐⭐⭐	无额外开销
调试便利性	⭐⭐⭐⭐⭐	完全可读

最终 Token 示例：

{
  "uid": "user_123",
  "traceId": "aabbccdd123456",
  "timestamp": 1640995200000
}

方式二：JWT 加密（推荐）

描述：
JSON Web Token (JWT) 提供了一种在各方之间安全传输信息的标准化方式。它经过数字签名，具有防篡改特性，同时保持载荷的可读性以便调试。

适用场景：

生产环境

需要防篡改保护

需要 Token 过期机制的系统

与现有 JWT 基础设施集成

评分：

维度	评分	说明
安全级别	⭐⭐⭐⭐	防篡改，载荷可读
实现复杂度	⭐⭐⭐	需要 JWT 库支持
性能表现	⭐⭐⭐⭐	中等签名开销
调试便利性	⭐⭐⭐	载荷 base64 解码可读

生成方式：
可以参考石墨 Signature 的生成方式：签名凭证-Signature。

注意需要使用和 Signature 不同的签名 secret。

最终 Token 示例：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c2VyXzEyMyIsInRyYWNlSWQiOiJhYWJiY2NkZDEyMzQ1NiIsImV4cCI6MTY0MDk5NTIwMCwiaWF0IjoxNjQwOTkxNjAwLCJpc3MiOiJ5b3VyLWFwcC1uYW1lIn0.signature_hash_here

方式三：高级加密（企业版）

描述：
为了获得最大安全性，此方法使用强加密算法使 Token 完全不透明。载荷经过加密，只有拥有正确密钥的一方才能解密。

通常状况下，方式二已经可以满足签名的安全需求，若接入方的企业有更高的合规性需求，就需要考虑更高级别的加密。若为这种情况，接入方企业通常有内部成熟的加密方案，在此我们以 AES-256-GCM 为示例演示加密方法。

适用场景：

高安全性环境

合规要求

Token 内容必须完全隐藏

具有严格安全策略的企业部署

评分：

维度	评分	说明
安全级别	⭐⭐⭐⭐⭐	完全加密保护
实现复杂度	⭐	需要复杂的加密基础设施
性能表现	⭐⭐⭐	加密解密有开销
调试便利性	⭐	需要解密才能查看

使用 AES-256-GCM 的多语言示例：

Java

Python

用途#

签名中需要包含的信息#

用户身份信息#

其他希望透传的信息#

Token 生成方式#

方式一：JSON 明文 Token（基础版）#

方式二：JWT 加密（推荐）#

方式三：高级加密（企业版）#

用途

签名中需要包含的信息

用户身份信息

其他希望透传的信息

Token 生成方式

方式一：JSON 明文 Token（基础版）

方式二：JWT 加密（推荐）

方式三：高级加密（企业版）