跳到主要内容

4. JWT 声明 (JWT Claims)

JWT 声明集 (JWT Claims Set) 表示一个 JSON 对象, 其成员是 JWT 所传达的声明. JWT 声明集中的声明名称必须唯一 (MUST); JWT 解析器必须拒绝包含重复声明名称的 JWT, 或使用只返回词法顺序上最后一个重复成员名称的 JSON 解析器, 如 ECMAScript 5.1 [ECMAScript] 第 15.12 节 ("The JSON Object") 所规定.

一个 JWT 必须包含哪些声明才被视为有效取决于上下文, 不属于本规范范围. JWT 的具体应用会要求实现以特定方式理解和处理某些声明. 然而, 在没有这些要求的情况下, 实现无法理解的所有声明都必须被忽略 (MUST).

JWT 声明名称分为三类: 注册声明名称 (Registered Claim Names), 公共声明名称 (Public Claim Names), 私有声明名称 (Private Claim Names).

4.1. 注册声明名称 (Registered Claim Names)​

以下声明名称注册在第 10.1 节建立的 IANA "JSON Web Token Claims" 注册表中. 下列声明均不意图在所有情况下强制使用或实现, 而是为一组有用且可互操作的声明提供起点. 使用 JWT 的应用应当说明它们使用哪些具体声明, 以及这些声明何时为必需或可选 (SHOULD). 所有名称都很短, 因为 JWT 的核心目标之一是使表示保持紧凑.

4.1.1. "iss" (Issuer) 声明​

"iss" (issuer) 声明标识签发该 JWT 的主体. 对该声明的处理通常是应用特定的. "iss" 值是一个区分大小写的字符串, 包含 StringOrURI 值. 使用此声明是可选的 (OPTIONAL).

4.1.2. "sub" (Subject) 声明​

"sub" (subject) 声明标识 JWT 的主体. JWT 中的声明通常是关于该主体的陈述. 主体值必须在签发者上下文中局部唯一, 或者全局唯一 (MUST). 对该声明的处理通常是应用特定的. "sub" 值是一个区分大小写的字符串, 包含 StringOrURI 值. 使用此声明是可选的 (OPTIONAL).

4.1.3. "aud" (Audience) 声明​

"aud" (audience) 声明标识 JWT 预期面向的接收者. 每个预期处理该 JWT 的主体都必须用 audience 声明中的某个值标识自己 (MUST). 当该声明存在时, 如果处理声明的主体无法在 "aud" 声明中用某个值标识自己, 则必须拒绝该 JWT (MUST). 在一般情况下, "aud" 值是一个由区分大小写字符串组成的数组, 每个字符串都包含 StringOrURI 值. 在 JWT 只有一个 audience 的特殊情况下, "aud" 值可以是一个包含 StringOrURI 值的区分大小写字符串 (MAY). audience 值的解释通常是应用特定的. 使用此声明是可选的 (OPTIONAL).

4.1.4. "exp" (Expiration Time) 声明​

"exp" (expiration time) 声明标识过期时间, 在该时间或之后, JWT 必须不再被接受处理 (MUST NOT). 处理 "exp" 声明要求当前日期/时间必须早于 "exp" 声明中列出的过期日期/时间 (MUST). 实现者可以提供少量宽限, 通常不超过几分钟, 以考虑时钟偏差 (MAY). 其值必须是包含 NumericDate 值的数字 (MUST). 使用此声明是可选的 (OPTIONAL).

4.1.5. "nbf" (Not Before) 声明​

"nbf" (not before) 声明标识在此之前 JWT 必须不被接受处理的时间 (MUST NOT). 处理 "nbf" 声明要求当前日期/时间必须晚于或等于 "nbf" 声明中列出的 not-before 日期/时间 (MUST). 实现者可以提供少量宽限, 通常不超过几分钟, 以考虑时钟偏差 (MAY). 其值必须是包含 NumericDate 值的数字 (MUST). 使用此声明是可选的 (OPTIONAL).

4.1.6. "iat" (Issued At) 声明​

"iat" (issued at) 声明标识 JWT 的签发时间. 该声明可用于确定 JWT 的年龄. 其值必须是包含 NumericDate 值的数字 (MUST). 使用此声明是可选的 (OPTIONAL).

4.1.7. "jti" (JWT ID) 声明​

"jti" (JWT ID) 声明为 JWT 提供唯一标识符. 标识符值必须以确保同一值被意外分配给不同数据对象的概率可忽略不计的方式分配 (MUST); 如果应用使用多个签发者, 还必须防止不同签发者产生的值之间发生冲突 (MUST). "jti" 声明可用于防止 JWT 被重放. "jti" 值是区分大小写的字符串. 使用此声明是可选的 (OPTIONAL).

4.2. 公共声明名称 (Public Claim Names)​

使用 JWT 的各方可以自由定义声明名称. 然而, 为防止冲突, 任何新的声明名称都应当注册到第 10.1 节建立的 IANA "JSON Web Token Claims" 注册表中, 或者是公共名称 (Public Name): 包含抗冲突名称 (Collision-Resistant Name) 的值 (SHOULD). 在任何情况下, 名称或值的定义者都需要采取合理预防措施, 确保其控制了用于定义声明名称的命名空间部分.

4.3. 私有声明名称 (Private Claim Names)​

JWT 的生产者和消费者可以约定使用属于私有名称 (Private Names) 的声明名称 (MAY): 即既不是注册声明名称 (第 4.1 节), 也不是公共声明名称 (第 4.2 节) 的名称. 与公共声明名称不同, 私有声明名称可能发生冲突, 应谨慎使用.