Analytics API Token 是凭证,不是标识符
API token 能访问数据,应当作为有生命周期的秘密来管理:只显示一次、存储验证值、限制权限,并支持常规撤销。
API token 不是用户或站点的标签,而是一种凭证:任何获得有效 token 的人都可能以其持有者的身份执行操作。把它当作标识符,会让它出现在日志、URL、支持工单截图和无人敢撤销的长期配置中。
IETF 于 2025 年 1 月发布的 OAuth 2.0 安全最佳实践更新了 OAuth 部署的威胁模型和安全建议。个人 API token 未必是 OAuth access token,但同一工程原则仍适用:基于持有关系生效的凭证必须在传输中受到保护,只能用于预期服务,并且权限应限制在调用方所需范围内。
秘密只显示一次
使用密码学安全的随机源生成 token,并确保熵足够高,以避免实际可行的猜测。完整 token 只在创建时返回;之后存储一个非秘密前缀用于识别,以及一个单向验证值用于后续查找。如果数据库被复制,验证值比可重复使用的明文凭证安全。不要把通用哈希当作密码哈希:API token 应有高随机性,而人工密码需要刻意设计为较慢的密码哈希函数。
在产品界面和 API 响应中明确说明 token 只显示一次。用户离开创建页面后,应提供撤销并重新签发的方式,而不是找回原始秘密。绝不要把 token 放进查询参数、页面 URL、Analytics 事件、错误报告或截图。与授权头相比,URL 更容易进入浏览器历史、Referer、代理日志和支持工单。
通过正确的渠道传递凭证
对于 HTTP API,应通过 TLS 在 Authorization 请求头中接收 token。RFC 6750 将 bearer token 描述为任何持有者都可使用的凭证,并警告其在存储或传输中泄露会导致滥用。它还不建议将 bearer 凭证放在 URI 查询参数中,因为 URL 通常会被记录。除非协议明确要求其他传输方式且已有文档化的威胁模型,否则应拒绝查询字符串和请求体中的 token。
服务器应在处理请求操作前验证 token。从可信存储中解析所有者和权限;不要把请求中传来的用户或站点所有者视为授权依据。不要将秘密写入应用日志、追踪数据或异常消息。需要在运维中关联请求时,记录 token 的非秘密 ID 或前缀,绝不记录凭证本身。
限制权限、设置有效期并支持撤销
Token 应只授予完成任务所需的最小权限。产品支持时,应允许用户将 token 限定到特定站点、只读权限或特定操作。仅需获取一份报告的自动化脚本,不应默认获得整个账户的写权限。OAuth 安全最佳实践讨论了限制 token 权限和受众;即使 API 使用自己的不透明格式,这仍是有用的设计参考。
将过期和撤销作为一等控制。较短有效期能缩短泄露凭证仍可使用的时间;撤销则适用于安全事件、人员变更或集成调整。如果轮换需要一段重叠期,应明确期限并显示当前有效的 token。撤销必须在 API 边界生效,而不是只在仪表板中隐藏 token。
在 Monoid 的程序化 API 中,用户创建的 mnd_live_… token 是不透明字符串,只在创建时返回一次明文,并以 SHA-256 哈希存储,支持可选过期时间和软撤销。这种设计可以避免从数据库读取时获得原始值,但无法让泄露的有效 token 失效。不要将它放入版本控制、CI 输出、浏览器 bundle 或共享终端历史;怀疑泄露时,应签发替代 token 并撤销旧 token。
让整个生命周期可测试
测试完整流程:创建;按预期权限使用;拒绝无效或过期 token;撤销;再确认同一 token 已失效。验证 token 不能跨账户或站点访问,并确认每个 endpoint 都执行相同的认证和授权规则。加入运维检查,确保日志会脱敏凭证,API 响应不会返回已存储的 token 内容。
秘密管理生命周期包括创建、访问控制、轮换、审计和撤销,而不只是安全存储。只有系统能够识别 token 的所有者、限制其操作、在不记录秘密的情况下发现泄露,并及时关闭 token,它才真正受到保护。
Comments
Loading comments…