JWT 构造与安全审查

目标与适用范围

生成受控 JWT 测试样本或检查已获授权的样本，审查 Claim、算法、过期状态、敏感字段和签名证据，并明确解码不等于验签。
本指南将当前任务范围转化为可复核的交付结果。请保留源文件、中间产物和关键判断，让后续协作者能够理解检查了什么以及为什么这样处理。

准备证据并作出选择

• 只使用为本次审查生成的合成令牌，或使用样本所有者明确授权的令牌；不要使用仍可访问系统的生产 access token。

• 提前记录预期的 issuer、audience、允许算法、有效期政策，以及是否有权提供 HS256 密钥或 RS256 公钥。

• 准备在工单、截图和日志中遮盖令牌值及敏感 Claim 内容。

• 决策点: 需要构造可控样本，还是检查已有样本？. 需要固定 Claim、时间和算法来复现测试时使用 jwt-generator；需要调查真实授权样本的现象时使用 jwt-decoder，避免重新生成令牌掩盖问题。

• 决策点: 当前问题是结构问题，还是密码学问题？. jwt-decoder 只能展示 Header、Payload 和可选签名文本，不会验证签名。需要安全发现时使用 jwt-decoder-security-auditor；只有在获授权的 HS256 密钥或 RS256 公钥可用时才做实际签名核验。

• 决策点: 哪些 Claim 可以进入审查证据？. 可以保留问题类型和 Claim 名称，但应遮盖用户、租户、会话、邮箱或凭据值。解码后的 Payload 是可读的 base64url 数据，不是加密内容。

按步骤完成工作流

1. 生成边界清晰的测试样本

用明确的 issuer、audience、subject、过期时间和可选自定义 Claim 生成非生产 JWT。只使用测试密钥，并在继续前记下目标算法。 使用 jwt-generator.

2. 检查编码结构

解码已授权样本或刚生成的测试样本，分别查看 Header 与 Payload，确认有哪些时间 Claim；同时记录这一步不能证明签名有效。 使用 jwt-decoder.

3. 执行 JWT 安全审计

把同一个受控样本交给审计器，检查算法风险、签名状态、已过期或尚未生效的时间、缺少 issuer 或 audience 的提示，以及可能暴露的敏感 Claim。只有获授权时才提供验签密钥。 使用 jwt-decoder-security-auditor.

4. 按服务政策复核结论

只处理属于本次测试目标的发现，使用脱敏后的测试样本重新运行审计器，并记录哪些问题接受、哪些需要调整令牌政策、哪些因没有密钥仍未验证。 使用 jwt-decoder-security-auditor.

交付前验收结果

• 测试样本已记录用途、负责人和脱敏状态，审查记录中没有生产令牌或生产密钥。
• Header 与 Payload 已分别解码，报告明确把解码标为结构检查，而不是签名验证。
• 报告记录了实际算法、签名状态、exp 与 nbf 行为、issuer 或 audience 缺失，以及发现的敏感 Claim 名称。
• 审查者已将发现与服务政策对照，并给出接受、修改或阻断结论；没有提供密钥时必须标记为未验证，而不是有效。

常见问题

• jwt-decoder 会验证 JWT 签名吗？ 不会。它解析令牌的三个片段，并展示 Header、Payload 以及可选的签名文本。解码不能证明签名真实，也不能证明应用应接受这个令牌。
• 审计器什么时候可以报告签名有效？ 只有在令牌走支持的 HS256 或 RS256 路径，并提供对应的、获授权的 HMAC 密钥或 RSA 公钥时才可以。没有这些材料时，应把签名记为存在但未验证。
• 为什么普通 Claim 也可能被标记为敏感？ JWT Payload 是 base64url 编码而不是加密内容，因此 email、phone、token 或账户标识等字段可能被读取。应遮盖值，并让 Claim 保持最小化。
• 为了快速排查，可以粘贴生产 access token 吗？ 不可以。请使用合成测试样本，或使用明确获授权且已脱敏的样本。不要把有效令牌、签名密钥、私钥或未脱敏 Payload 放进工具、截图、工单或日志。