RFC 7519 · JSON Web Signature

JWT 简介

JSON Web Token（JWT）是一项开放标准（RFC 7519），将声明表示为紧凑、URL 安全的字符串。它常与 OAuth 2.0 和 OpenID Connect 一起使用，但格式本身是通用的：任何持有正确验证材料的一方都可以校验签名并理解其中的声明——在密钥与时钟管理的限制之内。

本页说明 JWT 如何构建、如何阅读各部分，以及仅凭令牌本身可以期待哪些保证、哪些不能。

01

紧凑序列化与编码

在常见形式（JSON Web Signature，JWS）中，JWT 由点分隔的三段组成：标头、载荷和签名。前两段是使用 Base64URL（非标准 Base64）编码的 JSON 对象：通常省略填充并使用 URL 安全字符，以便放入标头与查询字符串。

Base64URL 不是加密。任何持有字符串的人都能读取标头与载荷。签名证明前两段由控制签名密钥的一方生成；并不隐藏其内容。

02

JWT 结构

在紧凑 JWS 形式中，各段作用如下：

标头

通常包含 typ（类型，常为 "JWT"）和 alg（签名算法）。也可能包含 kid 以从 JWKS 选择公钥，或堆栈所需的其他元数据。

载荷

包含声明的 JSON 对象：主体、有效期、受众与应用特定字段。若签发者定义，也允许嵌套对象。

签名

对 "header.payload" 字节（两段编码与中间的点）的密码值，使用标头中的算法与共享密钥（HMAC）或非对称私钥（RSA、ECDSA、EdDSA）。

03

声明：载荷中的内容

声明是键值对。其含义取决于上下文，但 RFC 7519 定义了一组注册名称，以便库与 API 一致解释。

注册声明

常见示例包括 iss、sub、aud、exp、nbf、iat、jti。exp 与 nbf 为 Unix 时间戳；正确验证需要验证方有可信时钟。

公共声明

名称可在 IANA「JSON Web Token Claims」注册表登记以获得广泛互操作，但在生产者与消费者就语义达成一致前仍只是约定。

私有声明

签发者与消费者约定的名称（例如内部角色或租户标识）。除非完全控制双方，否则避免与注册名称冲突。

04

算法概览

标头中的 alg 决定签名计算方式。选择错误的模型会影响谁可以验证以及如何共享密钥。

  • HMAC（HS*）：单一共享密钥签名与验证。对单一服务简单，但每个验证方都必须持有密钥。
  • RSA 或 ECDSA/EdDSA：签发者用私钥签名；验证者使用公钥（常通过 JWKS 分发）。适合微服务与不应持有签名密钥的公开客户端。
  • 算法 "none" 绝不应在生产中接受：若配置错误可能允许未签名令牌。应明确拒绝未知或禁用的算法。
05

安全：信任、隐私与验证

有效签名表明令牌由控制签名密钥的一方签发，且标头与载荷未被篡改。它本身并不加密任何内容。

请勿在载荷中存放密码、API 密钥或其他长期机密。若除签名外还需保密，请在传输层使用 TLS，并考虑 JWE——另一种格式与工作流。

服务器应使用预期密钥或 JWKS 验证签名，检查 exp（通常还有 nbf），在架构依赖时强制执行 aud 与 iss，并在适当时使用短寿命与刷新流程。

06

常见用途

JWT 常用于：

  • 表示已认证身份与授权决策（Bearer 访问令牌、OpenID Connect 的 ID 令牌）
  • 在分布式系统中的服务之间传递身份或委托权限
  • 与安全存储和刷新策略结合，在客户端建模会话状态
  • 在 API 网关与资源服务器携带 OAuth 2.0 范围或自定义声明
07

实际限制

使用 JWT 设计时的实用约束：

  • 大小：令牌常置于 HTTP 标头；过大载荷会增加延迟并可能触及代理限制。
  • 撤销：纯无状态 JWT 若无额外基础设施（拒绝列表、自省或极短寿命）无法即时撤销。
  • 时钟偏差：exp 与 nbf 的验证依赖签发者与验证者之间大致同步的时钟。