签名凭证 Token

凭证 Token 是您的应用签发、您的应用校验，石墨原样透传的 Token 到您的回调接口。

石墨文档中台不会解析、也无法校验 Token 是否合法性，这意味着 Token 的格式和密钥完全由您掌握，安全模型也完全由您负责。

一、用途与传递路径

凭证 Token 解决的是“石墨回调过来时，您的应用如何知道这是哪个用户、哪个业务上下文”的问题，整个签发和校验流程大概如下所示：

要点：

签发者 = 校验者。石墨只透传，不解析。这是 Token 与 Signature 最本质的区别——Signature 是石墨当校验者，Token 是您的应用既当签发者也当校验者。

Token 由后端签发。前端不持有任何密钥，每次需要就向后端取一次新的。

回调里的 Token = 您提供的那个 Token。石墨拿到什么就回什么——这同时意味着，一旦签发出去，在它过期前会随每次相关回调反复被使用。

二、Token 应包含的信息

2.1 必须包含：用户身份

Token 必须能让您的应用识别出"这次回调来自哪个业务用户"。一般做法是把用户 id 编码进 Token字段中，（不要直接编码用户名、邮箱、手机号这类敏感字段，需要的话用用户 id 去查）：

{
  "uid": "user_123"
}

如果您的系统是多租户的，再加上租户 id：

{
  "uid": "user_123",
  "tenantId": "tenant_42"
}

2.2 可选：业务透传字段

因为石墨不会改 Token，您可以借这条通道把"调用上下文"原样传到回调侧。最常见的用法是 trace_id（链路追踪 id）——以导入为例：

可以放在 Token 里的典型字段：

字段	用途
`uid` / `userId`	必含。识别业务用户
`tenantId`	多租户场景识别租户
`trace_id`	把"前一跳的调用上下文"传到回调侧
`exp` / `iat`	过期与签发时间（推荐用 JWT 的标准字段）
`scope`	标记本次签发的权限范围（如"仅可读"）

请勿塞进 Token 的信息：明文密码、明文身份证、明文手机号、信用卡号、API 密钥等。Token 在网络中流转，一旦泄露这些信息会跟着泄露。

三、Token 生成方式

石墨对 Token 格式没有要求，下面三种是常见的实现层级，按"安全 vs 复杂度"递增。生产环境推荐方式二（JWT），足够覆盖绝大多数接入需求。

3.1 方案对比

方案	安全级别	实现复杂度	性能	可调试性	推荐场景
JSON 明文	⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	开发联调、内网验证
JWT 签名（推荐）	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	生产环境通用
AES-256-GCM 加密	⭐⭐⭐⭐⭐	⭐	⭐⭐⭐	⭐	合规要求高、载荷需保密

三种方案选型上有两条主线：

要不要防篡改？ 要 → JWT 起步；不要（仅内网联调） → JSON 明文够用。

Token 内容本身是不是敏感？ 是 → AES-256-GCM；否（用 id 而不是 PII） → JWT 已够。

3.2 方案一：JSON 明文（本地调试）

最简单的形式：直接把对象 JSON 化、Base64 编码后作为 Token。

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

适用场景：

联调阶段，希望能直接肉眼读 Token 内容。

完全可信的内网部署，攻击面有限。

注意：不适合在生产环境使用此方案，没有签名意味着任何人拿到 Token 都能伪造、改造一个新的塞进去。

3.3 方式二：JWT 签名（生产环境推荐）

JWT (JSON Web Token) 在 JSON Payload 上加一段 HMAC 签名，校验侧用同样的 secret 重算签名比对，能防篡改但不防偷看。

JWT 的生成与校验细节可以参考签名凭证-Signature 里的算法说明，两者用同一类 HMAC 思路，只是 secret 必须不同。

Token 的 secret 一定要和 Signature 的 secret 分开。Signature 的 secret 是石墨派发给您的应用接入凭证；Token 的 secret 是您的应用内部自留的，石墨从不接触。两者混用一旦其中一个泄露，另一个的安全模型就全部塌掉。

最终 Token 形如：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c2VyXzEyMyIsInRyYWNlSWQiOiJhYWJiY2NkZDEyMzQ1NiIsImV4cCI6MTY0MDk5NTIwMCwiaWF0IjoxNjQwOTkxNjAwLCJpc3MiOiJ5b3VyLWFwcC1uYW1lIn0.signature_hash_here

适用场景：

绝大多数生产环境。防篡改、能带过期时间、各语言生态成熟。

Payload 里只有 id 类轻量字段、不介意被 base64 解码看到结构。

3.4 方式三：AES-256-GCM 加密（生产环境推荐，更复杂安全性更高）

JWT 的载荷虽然防篡改但可读。如果您的应用有合规要求，载荷本身也不能让人看见（例如载荷包含内部权限标签、组织结构 id），就需要再加一层对称加密。

通常 JWT 已能满足安全需求；只有当企业合规需要"载荷完全不可读"时再升级到这一档。下面给出 Java / Go / Python 三种语言的 AES-256-GCM 完整示例，IV 12 字节、AAD 固定串、密文与 IV 各自 base64 后下发。

Java

Python

实现要点：

IV / nonce 必须随机且不重复。同一 secret 下 IV 复用 = AES-GCM 安全性归零。

**AAD（附加验证数据）**生成与校验必须一致。可以塞进版本号、环境标识，对应 Token 在跨环境下不能互认。

secretKey 长度需为 32 字节（AES-256）。示例里用 SHA-256 派生是常见做法。

密文 + IV（+ AuthTag）需要一起下发。任何一段丢失都无法解密。

四、Token 的校验

回调接口拿到 X-Weboffice-Token 之后，至少要经过如下流程校验：

校验各环节关键点：

签名 / AAD 校验。JWT 校验 HMAC 是否一致；AES-256-GCM 解密时如 AAD 不匹配会直接报错——这一步同时完成"防篡改"和"防跨环境串"。

过期时间。Token 内部最好带 exp，校验时拒绝过期。建议生命周期与浏览器会话同量级（如 30 分钟到 2 小时），不要给得太长。

吊销 / 黑名单。用户登出、密码变更、Session 撤销时，要让仍未过期的 Token 立即失效。常见做法：服务端维护一张吊销表，校验时查一次；或者 Token 里塞 sessionId，校验时确认 session 仍活跃。

业务权限二次校验。Token 通过只能证明"来源合法"，不能证明"该用户对当前文件有权限"。文件级权限校验应放在 Token 校验之后，由您的应用业务侧再判一次。

失败统一返回 4xx：鉴权问题用 401，业务拒绝用 403。详细原因见签名凭证：Signature 与 Token。

五、常见误区

误区	实际影响	正确做法
在前端直接用密钥签 `Token`	密钥泄露，任何人都能伪造 `Token`	`Token` 一律由您的应用后端签发，前端只拿结果
`Token` 用明文 JSON 上生产	任何人改造载荷都能冒充用户	至少升级到 JWT 签名（方式二）
`Token` 与 `Signature` 共用同一个 secret	一处泄露=两处全塌	两套 secret 物理分开、分开轮换
`Token` 里直接塞手机号 / 邮箱 / 身份证	一次泄露 PII 跟着泄露	只放 id，敏感信息您的应用按 id 自己查
不带过期时间	一旦泄露永久可用	加 `exp` 字段，建议 ≤ 2 小时；同时维护吊销表
用户登出后 `Token` 仍能调通回调	离职 / 撤权后还能继续操作	维护 `sessionId` + 吊销表，校验时联动
`Token` 校验只判"格式对"	改个 uid 就能冒充别的用户	必须校验签名（HMAC 或 GCM AAD），不只看结构
把 `Token` 当业务幂等键	同一会话内多次回调 `Token` 相同，幂等键失效	幂等键用业务事件 id / `trace_id`，不要用 `Token`
AES-GCM 复用同一 IV	安全性直接归零	每次加密生成 12 字节随机 IV，不复用
同一个 `Token` 被多个用户复用	当前用户回调返回错人	`Token` 与用户一一绑定，会话维度签发

一、用途与传递路径#

二、Token 应包含的信息#

2.1 必须包含：用户身份#

2.2 可选：业务透传字段#

三、Token 生成方式#

3.1 方案对比#

3.2 方案一：JSON 明文（本地调试）#

3.3 方式二：JWT 签名（生产环境推荐）#

3.4 方式三：AES-256-GCM 加密（生产环境推荐，更复杂安全性更高）#

四、Token 的校验#

五、常见误区#