整体概述

石墨文档中台和你的应用是双向调用关系：你的应用会调用石墨的接口，石墨也会回调你的应用。两个方向需要不同的凭证，Signature (X-WebOffice-Signature) 和 Token (X-WebOffice-Token) 分别承担其中一边的鉴权。

这两种凭证经常被混淆，是接入过程里最容易踩坑的环节之一。

一、为什么需要两种凭证？

石墨与你的应用的调用是双向的：

你的应用 → 石墨：石墨需要确认请求来自"合法接入方"，也就是说石墨文档中台对这些外部请求的鉴权基于 Signature。Signature 由 appId 和 secret 并结合特定的算法生成，只有合法的接入方才能签出有效的 Signature。

石墨 → 你的应用：你的应用需要确认回调来自"合法石墨服务"，也就是说你的应用对外部请求的鉴权主要基于 Token。Token 由你的应用提前签发并由石墨透传回来，里面还可以嵌入用户 id 这类业务信息。

石墨主动通知场景：石墨内部产生的周期性任务、系统事件，这类请求不是由用户主动触发、没有用户上下文的信息，因此石墨拿不到 Token，这种场景下你的应用也需要支持使用 Signature 的方式来完成对来自石墨文档请求的鉴权。

二、两种签名凭证详细说明

签名凭证分为 X-WebOffice-Signature（以下简称 Signature）和 X-WebOffice-Token（以下简称 Token）两种类型：

凭证类型	Header 名	主要作用	其他作用
Signature	`X-WebOffice-Signature`	石墨文档中台用来校验外部请求是否合法	某些场景下石墨无法提供 `Token`，因此你的应用回调接口也需支持通过 `X-WebOffice-Signature` 校验请求来自石墨
Token	`X-WebOffice-Token`	你的应用校验来自石墨文档中台的请求是否合法	携带接入方需要透传的信息，例如用户 id 等

具体接口是否携带 Signature 或 Token，以及携带哪种 / 几种，请查阅对应接口文档。下文给出的是最典型的两种场景。

两者的关键差异：

维度	Signature	Token
签发者	你的应用（基于 `appId`、`secret` 生成）	你的应用（用自定义业务规则）
校验者	石墨文档中台后端；你的应用后端（仅主动通知场景）	你的应用后端
是否携带业务信息	否	是（可携带用户 id、租户 id 等信息）
生命周期	短（一般几分钟到几十分钟，有参数里的 ts 决定）	你的应用自行决定，建议短期
主要风险	时钟漂移、secret 泄露	重放攻击、Token 泄露

三、签名凭证传递流程

3.1 典型场景：用户操作触发

绝大多数业务动作都由用户在浏览器端发起。此时你的应用前端先向后端要 Signature + Token，再交给石墨 JS SDK；JS SDK 用它们去调石墨，石墨回调你的应用时把 Token 原样带回来。

要点：

Signature 由你的应用后端签发，前端不持有 secret，避免泄露。

Token 由石墨透传回来，你的应用回调接口直接验自己签的内容即可。

签名要短期化：每次会话取一次新的 signature + token，过期了重新换。

3.2 石墨文档中台主动通知场景：石墨主动触发

在某些场景下，石墨会主动发起回调到你的应用，这些场景不是由用户操作触发，所以石墨无法提供 Token 信息：

周期性任务：石墨内部的定时统计 / 清理任务产生的通知。

系统事件：与具体用户无关的全局事件，例如文档协同会话异常关闭、批处理结果回传等。

延迟事件：用户早已离开页面，但石墨这边某个状态变更才落地，需要异步通知。

这些请求只能携带 Signature，由你的应用后端用同一对 appId + secret 来校验请求是否合法。

要点：

这条链路里没有用户、没有前端、没有 JS SDK——你的应用回调接口必须能独立用 Signature 完成鉴权，不能假设一定能拿到 Token。

同一个回调接口要支持"Signature + Token 双凭证（典型场景）"和"仅 Signature（主动通知）"两种入站方式，按 Header / Credential-Type 自动分支。

校验失败必须返回 4xx，不要返回 200——否则石墨会认为接收成功、不再重试，事件就丢了。

四、回调接口的鉴权实现

你的应用回调接口实现的请求鉴权业务流程大概如下所示：

实现要点：

统一入口、分支鉴权。所有石墨回调走同一个 endpoint，按 X-WebOffice-Credential-Type 与 Token 是否存在做分支，不为每种事件单独配 URL。

Signature 校验要带 ts。用 appId + secret + ts + nonce 这类参数生成签名，校验时比对计算结果，同时拒绝 ts 偏离当前时间过大（建议 ±5 分钟）的请求。

Token 自己签自己验。Token 是你的应用签发的（JWT / HMAC / 自定义都行），校验只跟你的应用密钥相关。Token 里塞业务上下文（如 userId / tenantId）时记得只放 id 不放敏感数据。

时钟同步。所有服务节点跑 NTP，避免因时钟漂移把合法请求误判为重放。

校验失败明确返回 4xx。建议 401（鉴权信息缺失或无效）/ 403（鉴权通过但业务上拒绝）；不要返回 5xx，会让石墨当成自己出问题而无意义重试。

五、构造方式

具体的签名算法、参数顺序、编码格式按对应文档：

签名凭证 - Signature（参考：co18-03-02-Signature-签名.md）

签名凭证 - Token（参考：co18-03-03-Token-与回调鉴权.md）

涉及到把 appId + secret 写进配置时，按 co18-03-05-安全上线清单.md 的要求保护好密钥。

六、常见误区

误区	实际影响	正确做法
在前端持有 `secret` 直接签 `Signature`	`secret` 泄露后整个接入身份被人冒用	`Signature` 一律由你的应用后端签发，前端只拿结果
假设石墨回调一定带 `Token`	主动通知场景没有 `Token`，被回调接口直接拒绝，事件丢失	同一入口支持"`Signature + Token`"和"仅 `Signature`"两条分支
校验失败返回 200	石墨判定送达成功，不再重试，事件永久丢失	鉴权失败必须返回 4xx（`401` / `403`）
校验失败返回 5xx	石墨触发无意义重试，把日志和服务都打爆	鉴权失败返回 4xx；只有自身业务异常才返回 5xx
不校验时间戳 / 不拒绝过期 `ts`	攻击者可拿历史请求重放	拒绝偏离当前时间 > 5 分钟的请求，并维护短期 nonce 防重放
`Token` 里塞用户邮箱 / 手机号等敏感数据	一旦 `Token` 泄露，PII 跟着泄露	`Token` 只放 id 类轻量字段，敏感信息你的应用自己根据 id 查
`Signature` 拿来当业务幂等键	`Signature` 每次都不一样，不可比对	业务幂等键自己维护（事件 id / 任务 id / 业务键）
多节点时钟未同步	偶发合法请求被误判为重放	所有节点跑 NTP；`Signature` 校验允许 ±5 分钟容差
把 `secret` 提交到代码仓库	一次泄露永久泄露	用密钥管理（KMS / Vault / 环境变量），CI 里做秘密扫描
同一份 `Signature` 在前端被复用打多次接口	一旦窗口过期后续请求全部失败	每次会话取一次新的 `signature + token`，按需刷新

一、为什么需要两种凭证？#

二、两种签名凭证详细说明#

三、签名凭证传递流程#

3.1 典型场景：用户操作触发#

3.2 石墨文档中台主动通知场景：石墨主动触发#

四、回调接口的鉴权实现#

五、构造方式#

六、常见误区#