RFC 7519 - JSON Web Token（JWT）中文版

水平有限，发现问题请指正。

1. 介绍

JSON Web令牌（JWT）是一种紧凑的声明表示格式，适用于空间受限的环境，如HTTP授权头和URI查询参数。JWT用于传输声明，作为JSON[RFC7159]对象的载荷，用于JSON Web签名（JWS）[JWS]结构或JSON Web加密（JWE）结构中的明文，使声明能够使用消息认证码（MAC）和/或加密进行数字签名或完整性保护。JWT始终使用JWS紧凑序列化或JWE紧凑序列化表示。建议的JWT发音与英语单词“jot”相同。

1.1. 记号约定

本文档中的关键字“必须”、“不得”、“要求”、“将会”、“不会”、“应该”、“不应该”、“建议”、“不建议”、“可以”和“可选”应按照[RFC2119]中规定的“用于RFC中表示要求级别的关键字”进行解释。只有在这些术语以加粗出现时才应用该解释。

2. 术语

“JSON Web签名（JWS）”，“Base64URL编码”，“Header参数”，“JOSE头部”，“JWS紧凑序列化”，“JWS负载”，“JWS签名”和“不安全的JWS”是由JWS规范（JWS）定义的术语。

“JSON Web加密（JWE）”，“内容加密密钥（CEK）”，“JWE紧凑序列化”，“JWE加密密钥”和“JWE初始化向量”是由JWE规范定义的术语。

术语“密文”、“数字签名”、“消息认证码（MAC）”和“明文”由“互联网安全词汇表，版本2”定义[RFC4949]。

这些术语由本规范定义：

JSON Web Token (JWT)

表示一组声明的字符串，作为在JWS或JWE中编码的JSON对象，该声明可被数字签名或MAC化和/或加密。

JWT Claims Set （JWT声明集）

包含JWT所传达的声明的JSON对象。

Claim （声明）

关于主题的一条信息。声明表示为名称/值对，由声明名称和声明值组成。

Claim Name（声明名称）

声明表示的名称部分。一个声明名称总是字符串。

Claim Value（声明值）

声明表示的值部分。一个声明值可以是任何JSON值。

Nested JWT（嵌套的JWT）

嵌套的JWT使用了嵌套的签名和/或加密。在嵌套的JWT中，JWT被用作包含的JWS或JWE结构的负载或明文值。

Unsecured JWT（不安全的JWT）

一个其声明未被完整性保护或加密的JWT。

Collision-Resistant Name（无冲突名称）

一个命名空间中的名称，该名称以一种极不可能与其他名称发生冲突的方式分配名称。抗冲突命名空间的示例包括：域名、ITU-T X.660和X.670建议系列中定义的唯一对象标识符（OIDs）、通用唯一标识符（UUID） [RFC4122]。当使用经行政委派给命名空间的名称定义时，名称定义者需要采取合理的预防措施，以确保他们能够控制他们用于定义名称的部分命名空间。

StringOrURI

一个JSON字符串值，附加要求是，虽然可以使用任意字符串值，但包含冒号字符的值必须是URI（RFC3986）。StringOrURI值将作为大小写敏感的字符串进行比较，不进行任何转换或规范化。

NumericDate（数字日期）

一个JSON数值，表示从1970年1月1日（UTC时间）起算，到指定UTC日期/时间的秒数，不包括闰秒。这与IEEE Std 1003.1-2013版（POSIX.1）中的定义“自Epoch以来的秒数”等同，其中每天精确算作86400秒，除了可以表示非整数值。具体日期/时间的细节和UTC时间可以参考RFC 3339（RFC3339）。

3. JSON Web Token (JWT) 概述

JWTs是以JSON对象的形式表示一组声明的，该JSON对象被编码在JWS和/或JWE结构中，该JSON对象就是JWT声明集。根据RFC 7159的第4节[RFC7159]中指出，JSON对象由零个或多个键值对（或成员）组成，其中键是字符串，值是任意的JSON值。这些成员就是由JWT所表示的声明。这个JSON对象可以在JSON值或结构字符前后包含空白和/或换行符，这符合RFC 7159的第2节[RFC7159]的规定。

JWT声明集中的成员名称被称为“声明名称”，对应的值被称为“声明值”。

JOSE标头的内容描述了应用于JWT声明集的加密操作。如果JOSE标头用于JWS，则JWT表示为JWS，声明经过数字签名或MAC化，JWT声明集为JWS有效负载。如果JOSE标头用于JWE，则JWT表示为JWE，声明被加密，JWT声明集是由JWE加密的明文。JWT可以包含在另一个JWE或JWS结构中以创建嵌套JWT，从而能够执行嵌套签名和加密。

JWT表示为URL安全的部分序列，由句点 (’.’) 字符分隔。每个部分都包含一个Base64URL编码的值。JWT中的部分数量取决于使用JWS Compact Serialize生成的JWS或使用JWE Compact Serialize生成的JWE的表示。

3.1. JWT示例

以下示例JOSE Header声明编码对象是JWT，JWT是使用HMAC SHA-256算法进行MAC化的JWS：

{"typ":"JWT",
 "alg":"HS256"}

为了消除上述JSON对象表示中的潜在歧义，下面还包括本示例中用于上述JOSE Header的实际UTF-8表示的八位字节序列。（请注意，由于换行符的不同平台表示（CRLF与LF）、行的开头和结尾的不同行间距、最后一行是否有终止换行符以及其他原因，可能会出现歧义。在本示例中使用的表示中，第一行没有前导或尾随空格，第一行和第二行之间出现CRLF换行符（13、10），第二行有一个前导空格（32），没有尾随空格，最后一行没有终止换行符。）在本示例中表示JOSE Header的UTF-8表示的八位字节（使用JSON数组表示法）是：

[123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125]

Base64URL编码JOSE Header的UTF-8表示的八位字节会产生这个编码的JOSE Header值：

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9

以下是JWT声明集的示例：

{"iss":"joe",
 "exp":1300819380,
 " http://example.com/is_root":true}

以下八位字节序列是JWS Payload，它是本例中用于上述JWT Claims Set的UTF-8表示：

[123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 111, 116, 34, 58, 116, 114, 117, 101, 125]

Base64URL对JWS Payload进行编码会产生此编码的JWS Payload（仅出于显示目的使用换行符）：

eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly
9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ

使用HMAC SHA-256算法计算编码JOSE Header和编码JWS Payload的消息认证码，并以[JWS]中指定的方式对HMAC值进行Base64URL编码，生成此编码JWS签名：

dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

将这些编码部分按此顺序与部分之间的句点 (’.’) 字符连接起来，会产生这个完整的JWT（仅出于显示目的使用换行符）：

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly
9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

[JWS]的附录A.1更详细地说明了这种计算。有关加密JWT的示例，请参阅附录A.1

4. JWT声明

JWT声明集表示一个JSON对象，其成员是JWT传递的声明。JWT声明集中的声明名称必须是唯一的；JWT解析器必须拒绝具有重复声明名称的JWT，或者使用仅返回词法上最后一个重复成员名称的JSON解析器，如ECMAScript 5.1[ECMAScript]第15.12节（“JSON对象”）中所述。

JWT必须包含的以被视为有效的声明集是上下文相关的，并且不在本规范的范围内。JWT的具体应用将需要实现以特定方式理解和处理某些声明。然而，如果没有这样的要求，所有不被实现所理解的声明都必须被忽略。

JWT声明名称有三类：注册声明名称、公共声明名称和私有声明名称。

4.1. 注册声明名称

以下Claim Name已在IANA“JSON Web Token Claim”注册表中注册，由第10.1节建立。下面定义的这些声明名称并不打算在所有情况下强制使用或实现，而是为一套有用的、可互操作的声明提供了一个起点。使用JWT的应用程序应该定义他们使用哪些特定的声明，以及何时使用它们是必需的或可选的。所有名称都很简短，因为JWT的一个核心目标是使表示紧凑。

4.1.1. "iss" (发行者) 声明

“iss”（发行者）声明标识了发行JWT的主要机构。该声明的处理通常与特定的应用有关。“iss”值是一个区分大小写的字符串，包含一个StringOrURI值。使用此声明是可选的。

4.1.2. "sub" (主题) 声明

“主题”（sub）声明标识了JWT的主题主语。该声明通常是对主题的陈述。主题值要么在发行者上下文中具有局部唯一性，要么具有全局唯一性。此请求的处理通常与特定的应用有关。“sub”值是一个区分大小写的字符串，包含一个StringOrURI值。使用此请求是可选的。

4.1.3. "aud" (受众) 声明

“aud”（受众）声明标识了JWT预期的接收方。每个预期处理JWT的主机必须使用“受众”声明中的值标识自己。如果处理该声明的主体在存在的情况下没有使用“aud”声明中的值标识自己，那么JWT必须被拒绝。在一般情况下，“aud”值是一个大小写敏感的字符串数组，每个字符串包含一个StringOrURI值。在特殊情况下，当JWT只有一个受众时，“aud”值可以是单个大小写敏感的字符串，包含一个StringOrURI值。“aud”值的解释通常取决于应用程序的具体情况。使用此声明的行为是可选的。

4.1.4. "exp" (过期时间)声明

“exp”（过期时间）声明标识了JWT在过期时间或之后不得被接受处理。处理“exp”声明要求当前日期/时间必须在“exp”声明中列出的过期日期/时间之前。实施者可以给时钟偏差留出一些小的余地，通常不超过几分钟。其值必须是一个包含数值日期的数值。使用此声明的选项是可选的。

4.1.5. "nbf" (不到) 声明

“nbf”（不到）声明标识了在它之前的某个时间点上，JWT必须被拒绝处理。处理“nbf”声明要求当前日期/时间必须在“nbf”声明中列出的不到日期/时间之后。实施者可以给时钟偏差留出一些小的余地，通常不超过几分钟。其值必须是一个包含数值日期的数值。使用此声明的选项是可选的。

4.1.6. "iat" (发行时间) 声明

“iat”（发行时间）声明标识了JWT的发行时间。该声明可用于确定JWT的年龄。其值必须是一个包含数值日期值的数值。使用该声明的选项是可选的。

4.1.7. "jti" (JWT ID) 声明

“jti”（JWT ID）声称为JWT提供了唯一标识符。在分配标识符值时，必须保证不同数据对象获得相同值的概率极低，可忽略不计。如果应用程序使用多个发行者，则必须防止不同发行者产生的值之间的冲突。使用“jti”声明可以防止JWT被重放。jti值是区分大小写的字符串。使用此声明是可选的。

4.2. 公共声明名称

使用JWT的用户可以随意定义声明名称。然而，为了防止冲突，任何新的声明名称都应该在由第10.1节建立的IANA“JSON Web Token Claim”注册表中注册，或者是一个公共名称：包含一个无冲突名称的值。在每个情况下，名称或值的定义者需要采取合理的预防措施，以确保他们对命名空间用于定义“声明名称”的部分保持控制。

4.3. 私有声明名称

JWT的生产者和消费者可以同意使用私有声明名称（非注册声明名称（第4.1节）或公共声明名称（第4.2节））。与公共声明名称不同，私有声明名称可能会发生冲突，因此应谨慎使用。

5. JOSE Header

对于一个JWT对象，由JOSE头部表示的JSON对象中的成员描述了对JWT应用的各种加密操作，并且可选地描述了JWT的其他属性。具体取决于JWT是JWS还是JWE，相应的JOSE头部值规则将适用。

本规范进一步规定了当JWT是JWS时以及当它是一个JWE时，对以下标头参数的使用。

5.1. "typ" (类型) 头参数

JWS和JWE定义的“typ”（类型）头部参数被JWT应用程序用于声明整个JWT的媒体类型（IANA.MediaTypes）。当在可以包含JWT对象的程序数据结构中也可能存在非JWT值时，该参数可用于应用程序以消除不同种类对象之间的歧义。当对象已知为JWT时，应用程序通常不会使用它。此参数被JWT实现忽略；任何对此参数的处理都由JWT应用程序执行。如果存在，建议其值为“JWT”以指示该对象为JWT。虽然媒体类型名称不区分大小写，但建议始终使用大写字母拼写“JWT”以与遗留实现兼容。使用此头部参数是可选的。

5.2. "cty" (内容类型) 头参数

由[JWS]和[JWE]定义的“cty”（内容类型）头参数用于本规范传达JWT的结构信息。在不使用嵌套签名或加密操作的正常情况下，不建议使用此头参数。如果使用了嵌套签名或加密操作，此头参数必须存在；在这种情况下，值必须为“JWT”，以指示嵌套的JWT在此JWT中携带。虽然媒体类型名称不区分大小写，但建议始终使用大写字母拼写“JWT”，以与遗留实现兼容。请参阅附录A.2以获取嵌套JWT的示例。

5.3. 将声明作为头部参数进行复制

在某些使用加密JWT的应用程序中，需要某种未加密的声明表示形式是有用的。这可以用于应用程序处理规则，以确定在解密JWT之前是否以及如何处理该JWT。

此规范允许在JWT（JSON Web Token）中根据应用程序的需求复制JWT声明集中的声明，并将其作为JWE的头部参数。如果存在这样的复制声明，接收它们的应用程序应该验证其值是否相同，除非应用程序为这些声明定义了其他特定的处理规则。应用程序有责任确保只有那些可以安全地以非加密方式传输的声明才会作为JWT的头部参数值进行复制。

本规范第10.4.1节为需要这些声明加密JWT的非加密副本的应用程序注册了“iss”（发行者）、“sub”（主题）和“aud”（受众）的头部参数名称。其他规范可能需要类似地注册其他作为头部参数名称注册的声明名称。

6. 不安全的JWTs

为了支持在使用JWT内容时，使用其他方式来保护JWT内容，而不仅仅是JWT中包含的签名和/或加密（例如包含JWT的数据结构上的签名），也可以创建没有签名或加密的JWT。无签名的JWT是使用“alg”头参数值为“none”的JWS，其JWS签名值为空字符串，如JWA规范[JWA]中定义的那样；它是一种无签名的JWS，其JWT声明集作为其JWS载荷。

6.1. 不安全的JWT示例

以下JOSE头部示例声明编码对象是一个未加密的JWT：

{"alg":"none"}

对JOSE头部字段的UTF-8表示的字节进行Base64URL编码，得到这个编码的JOSE头部字段值：

eyJhbGciOiJub25lIn0

以下是一个JWT声明集的示例：

{"iss":"joe",
 "exp":1300819380,
 " http://example.com/is_root":true}

对JWT声明的UTF-8表示的字节进行Base64URL编码，产生这个编码的JWS负载（为显示目的而添加了换行符）：

eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ

编码的JWS签名是空字符串。

将这些编码的部分按照这个顺序连接起来，并在部分之间使用点号字符(’.’)来连接，就可以得到完整的JWT（为了显示目的，这里添加了换行符）：

eyJhbGciOiJub25lIn0
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.

7. 创建和验证JWT（JSON Web Tokens）

7.1. 创建 JWT（JSON Web Token）

创建JWT需要执行以下步骤。在步骤之间没有依赖关系的情况下，这些步骤的顺序并不重要。

1. 创建一个包含所需声明的JWT声明集。请注意，表示中明确允许空格，编码前无需进行规范化。
2. 将JWT声明集转换为UTF-8表示的八位数组。
3. 创建一个包含所需的一组头部参数的JOSE头部。JWT必须符合[JWS]或[JWE]规范。请注意，在表示中明确允许空格，在编码之前不需要进行规范。
4. 根据JWT是JWS还是JWE，有两种情况：
   • 如果JWT是一个JWS，则使用消息作为JWS的有效载荷来创建一个JWS；必须遵循[JWS]中指定的创建JWS的所有步骤。
   • 否则，如果JWT是JWE，则使用消息作为JWE的明文来创建JWE；必须遵循[JWE]中指定的所有步骤来创建JWE。
5. 如果需要进行嵌套签名或加密操作，则将消息作为JWS或JWE，并返回到步骤3，在步骤中创建的新JOSE头部中使用“cty”（内容类型）值为“JWT”。
6. 否则，让生成的结果JWT成为JWS或JWE。

7.2. 验证JWT（JSON Web Token）

在验证JWT时，会执行以下步骤。如果各步骤之间的输入和输出之间没有依赖关系，则各步骤的顺序并不重要。如果列出的任何步骤失败，则必须拒绝JWT-即，应用程序将其视为无效输入。

1. 请验证JWT中至少包含一个句点（'.'）字符。
2. 令编码的JOSE头部为JWT中在第一个点（’.’）字符之前的部分。
3. 按照没有使用行终止符、空格或其他额外字符的限制，对经过编码的JOSE头部进行Base64URL解码。
4. 验证所得到的八位字节序列是符合RFC 7159[RFC7159]的完全有效的JSON对象的UTF-8编码表示形式；让JOSE头部就是这个JSON对象。
5. 验证所得到的JOSE头部只包含其语法和语义都被理解并支持的参数和值，或者当不被理解时被明确指定为被忽略的参数和值。
6. 使用在[JWE]的第九部分中描述的任何一种方法来确定JWT是否为JWS或JWE。
7. 根据JWT是JWS还是JWE，有两种情况：
   • 如果JWT是一个JWS，请按照[JWS]中指定的步骤验证JWS。将消息作为JWS负载进行Base64URL解码的结果。
   • 否则，如果JWT是JWE，则按照[JWE]中为验证JWE而指定的步骤进行操作，并让明文为验证后的明文消息。
8. 如果JOSE头部包含一个“cty”（内容类型）值为“JWT”，则该消息是一个作为嵌套签名或加密操作主题的JWT。在这种情况下，返回到步骤1，使用该消息作为JWT。
9. 否则，对以下遵循无行数限制、无空格或其他额外字符的使用限制的消息进行Base64URL解码。
10. 验证所得到的八位字节序列是符合RFC 7159[RFC7159]的完全有效的JSON对象的UTF-8编码表示，将JWT的“Claims Set”设定为此JSON对象。

最后，需要注意的是，在特定上下文中使用哪种算法是应用程序的决定。即使JWT可以被成功验证，除非应用程序接受JWT中使用的算法，否则它应该拒绝JWT。

7.3. 字符串比较规则

处理JWT不可避免地需要将已知的字符串与JSON对象的成员和值进行比较。例如，在检查算法是什么时，将Unicode字符串编码“alg”与JOSE头部的成员名称进行比较，以查看是否有匹配的头部参数名称。

JSON中成员名称比较的规则在RFC 7159[RFC7159]的第8.3节中有描述。由于只执行相等和不等的字符串比较操作，因此可以使用相同的规则来比较成员名称和成员值与已知字符串。

这些比较规则必须用于所有JSON字符串的比较，除非成员的定义明确指出应使用针对该成员值的另一种比较规则。在本规范中，“typ”和“cty”成员值不使用这些比较规则。

某些应用可能会在区分大小写的值中包含不区分大小写的信息，例如将DNS名称作为“iss”（发行者）声明值的一部分。在这些情况下，应用可能需要定义一个规范，用于表示不区分大小写部分时的规范大小写，例如，如果不止一个方可能需要生成相同的值以便进行比较，则需要将其转换为小写字母。（然而，如果所有其他方都直接消费生产方一字不差地发出的任何值，而没有试图将其与独立生成的值进行比较，则生产方使用的大小写将无关紧要。）

8. 实施要求

本节定义了哪些算法和本规范的特性是实现时必须遵循的。使用本规范的应用程序可以对实现提出附加要求，它们可以使用。例如，一个应用程序可能要求支持加密的JWT和嵌套的JWT，而另一个应用程序可能要求使用P-256曲线和SHA-256哈希算法使用椭圆曲线数字签名算法（ECDSA）对JWT进行签名（“ES256”）。

在JSON Web算法[JWA]中指定的签名和MAC算法中，仅HMAC SHA-256（“HS256”）和“无”必须由符合JWT实现的实现提供。建议实现还支持使用SHA-256哈希算法的RSASSA-PKCS1-v1_5算法（“RS256”）和采用P-256曲线和SHA-256哈希算法的ECDSA（“ES256”）。支持其他算法和密钥大小的选项是可选的。

对加密的JWT的支持是可选的。如果一个实现提供加密功能，则应在符合要求的实现中实现[JWA]中规定的加密算法。仅必须实现RSAES-PKCS1-v1_5使用2048位密钥（“RSA1_5”）、AES密钥包装使用128位和256位密钥（“A128KW”和“A256KW”）、以及使用AES-CBC和HMAC SHA-2的复合身份验证加密算法（“A128CBC-HS256”和“A256CBC-HS512”）。建议实现也支持使用椭圆曲线Diffie-Hellman临时静态（ECDH-ES）以商定用于包装内容加密密钥的密钥（“ECDH-ES+A128KW”和“ECDH-ES+A256KW”），以及使用AES在Galois/Counter模式下（GCM）使用128位和256位密钥（“A128GCM”和“A256GCM”）。对其他算法和密钥长度的支持是可选的。

对嵌套的JWT的支持是可选的。

9. 声明内容是JWT的URI

本规范注册了“urn:ietf:params:oauth:token-type:jwt”统一资源标识符（URI），供使用URI声明内容类型（而不是媒体类型）的应用程序使用，以表明所引用的内容是JWT。

10. IANA考虑因素

10.1. JSON Web令牌声明注册中心

本节为JWT声明名称IANA建立了“JSON Web Token声明”注册表。注册表记录了声明名称和对其定义规范的引用。本节注册了第4.1节中定义的声明名称。

在经过三周的审查期（在jwt-reg-review@ietf.org邮件列表上）和一个或多个指定专家的建议后，值将在RFC5226要求的规范基础上进行注册。

然而，为了在公布之前分配价值，指派专家可在确信此类规范将予公布之后批准其登记。

向用于审查的邮件列表发送的注册请求应使用适当的主题（例如，“要求注册要求：示例”）。

在审查期间，指定专家将批准或拒绝注册请求，并将此决定通知审查列表和IANA。拒绝应包括一个解释，如果适用，还应包括如何使请求成功的建议。在超过21天的期间内未决的注册请求可以提请IESG注意（使用iesg@ietf.org邮件列表）以待解决。

指定专家应适用的标准包括确定拟议的登记是否与现有功能重复、是否可能具有普遍适用性或是否仅对单一申请有用、以及登记说明是否清楚等。

IANA只能接受指定专家的注册更新，并应将所有注册请求发送到审查邮件列表。

建议任命多名设计专家，他们能够代表使用该规范的不同申请方的观点，以便能够对登记决定进行有广泛依据的审查。在可能对某一专家造成利益冲突的登记决定的情况下，该专家应尊重其他专家的判断。

10.1.1. 注册模板

Claim Name:

请求的名称（例如，“iss”）。由于本规范的核心理念是使结果表示形式紧凑，因此建议名称应简短——即不超过8个字符，除非有令人信服的理由。名称区分大小写。除非指定专家声明有令人信服的理由允许例外，否则名称不应以不区分大小写的方式匹配其他已注册名称。

Claim Description:

声明的简要描述（例如“发行人”）

Change Controller:

对于标准跟踪RFC，列出“IESG”。对于其他，给出责任方的名称。其他详细信息（例如，邮政地址，电子邮件地址，主页URI）也可能包括在内。

Specification Document(s):

应参考具体指定参数的文件或文件，最好包括可用来检索这些文件副本的URI。还可以包括对相关部分的说明，但并非必需。

10.1.2. 初始注册内容

o Claim Name: "iss"

o Claim Description: Issuer

o Change Controller: IESG

o Specification Document(s): Section 4.1.1 of RFC 7519

o Claim Name: "sub"

o Claim Description: Subject

o Change Controller: IESG

o Specification Document(s): Section 4.1.2 of RFC 7519

o Claim Name: "aud"

o Claim Description: Audience

o Change Controller: IESG

o Specification Document(s): Section 4.1.3 of RFC 7519

o Claim Name: "exp"

o Claim Description: Expiration Time

o Change Controller: IESG

o Specification Document(s): Section 4.1.4 of RFC 7519

o Claim Name: "nbf"

o Claim Description: Not Before

o Change Controller: IESG

o Specification Document(s): Section 4.1.5 of RFC 7519

o Claim Name: "iat"

o Claim Description: Issued At

o Change Controller: IESG

o Specification Document(s): Section 4.1.6 of RFC 7519

o Claim Name: "jti"

o Claim Description: JWT ID

o Change Controller: IESG

o Specification Document(s): Section 4.1.7 of RFC 7519

10.2. 子命名空间注册urn:ietf:params:oauth:token-type:jwt

10.2.1. 注册表内容

该部分在IANA“OAuth URI”注册表中注册了值“token-type:jwt”，该注册表由“用于OAuth的IETF URN子命名空间” [RFC6755]建立，可用于指示内容为JWT。

o URN: urn:ietf:params:oauth:token-type:jwt

o Common Name: JSON Web Token (JWT) Token Type

o Change Controller: IESG

o Specification Document(s): RFC 7519

10.3. 媒体类型注册

10.3.1. 注册表内容

这部分按照RFC 6838 [RFC6838]中描述的方式，将“application/jwt”媒体类型[RFC2046]注册到“媒体类型”注册表[IANA.MediaTypes]中，该媒体类型可用于指示内容为JWT。

o Type name: application

o Subtype name: jwt

o Required parameters: n/a

o Optional parameters: n/a

o Encoding considerations: 8bit; JWT values are encoded as a series

of base64url-encoded values (some of which may be the empty string) separated by period (’.’) characters.

o Security considerations: See the Security Considerations section of RFC 7519

o Interoperability considerations: n/a

o Published specification: RFC 7519

o Applications that use this media type: OpenID Connect, Mozilla

Persona, Salesforce, Google, Android, Windows Azure, Amazon Web

Services, and numerous others

o Fragment identifier considerations: n/a

o Additional information:

Magic number(s): n/a

File extension(s): n/a

Macintosh file type code(s): n/a

o Person & email address to contact for further information:

Michael B. Jones, mbj@microsoft.com

o Intended usage: COMMON

o Restrictions on usage: none

o Author: Michael B. Jones, mbj@microsoft.com

o Change controller: IESG

o Provisional registration? No

10.4. 头部参数名称注册

本部分登记在第4.1节中定义的特定声明名称，这些名称在IANA（互联网工程任务组）的“JSON Web Signature and Encryption Header Parameters”注册表中注册，该注册表由[JWS]为在JWE中的头参数中复制的声明而建立的，符合第5.3节的规定。

10.4.1. 注册表内容

o Header Parameter Name: "iss"

o Header Parameter Description: Issuer

o Header Parameter Usage Location(s): JWE

o Change Controller: IESG

o Specification Document(s): Section 4.1.1 of RFC 7519

o Header Parameter Name: "sub"

o Header Parameter Description: Subject

o Header Parameter Usage Location(s): JWE

o Change Controller: IESG

o Specification Document(s): Section 4.1.2 of RFC 7519

o Header Parameter Name: "aud"

o Header Parameter Description: Audience

o Header Parameter Usage Location(s): JWE

o Change Controller: IESG

o Specification Document(s): Section 4.1.3 of RFC 7519

11. 安全考虑因素

与任何加密应用程序相关的所有安全问题都必须由JWT/JWS/JWE/JWK代理来解决。这些问题包括保护用户的非对称私钥和对称密钥，并采取各种攻击的对策。

JWS规范中的所有安全考虑因素也适用于JWT，当使用加密时，JWE的安全考虑因素也是如此。特别是，[JWS]中的第10.12节（“JSON安全考虑因素”）和第10.13节（“Unicode比较安全考虑因素”）以与它们应用于JOSE头部相同的方式适用于JWT声明集。

11.1. 信任决策

在信任决策中不能依靠JWT的内容，除非其内容在加密上得到保护并且与信任决策所需的上下文绑定在一起。特别是，用于签名和/或加密JWT所使用的密钥通常需要可验证地控制在被确认为JWT发行者的方手中。

11.2. 签署和加密订单

虽然嵌套JWT的签名和加密操作在语法上可以以任何顺序进行，但如果需要签名和加密，通常生产者应该先对消息进行签名，然后再对结果进行加密（即加密签名）。这样可以防止攻击者剥离签名只留下加密的消息，同时也可以为签名者提供隐私保护。此外，在许多司法管辖区中，对加密文本的签名不被认为是有效的。

需要注意的是，与签名和加密操作顺序相关的潜在安全问题，已经在基础JWS和JWE规范中得到了解决；特别是，由于JWE只支持使用认证加密算法，许多上下文中可能需要在加密后进行签名的加密问题，对于本规范并不适用。

12. 隐私权考虑因素

JWT可以包含隐私敏感信息。在这种情况下，必须采取措施防止将此信息泄露给非预期方。实现这一点的其中一种方法是使用加密的JWT并对收件人进行身份验证。另一种方法是确保仅使用支持端点身份验证的加密协议（如传输层安全协议（TLS））来传输包含未加密的隐私敏感信息的JWT。从JWT中省略隐私敏感信息是减少隐私问题的最简单方法。

13. 参考文献

13.1. 规范性参考材料

[ECMAScript]

Ecma International, "ECMAScript Language Specification, 5.1 Edition", ECMA Standard 262, June 2011,

<http://www.ecma-international.org/ecma-262/5.1/ECMA-262.pdf>.

[IANA.MediaTypes]

IANA, "Media Types",

<Media Types>.

[JWA]

Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,

DOI 10.17487/RFC7518, May 2015,

<Information on RFC 7518 » RFC Editor>.

[JWE]

Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516,

DOI 10.17487/RFC7516, May 2015,

<Information on RFC 7516 » RFC Editor>.

[JWS]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515,

DOI 10.17487/RFC, May 2015,

<Information on RFC 7515 » RFC Editor>.

[RFC20]

Cerf, V., "ASCII format for Network Interchange", STD 80, RFC 20,

DOI 10.17487/RFC0020, October 1969,

<Information on RFC 20 » RFC Editor>.

[RFC2046]

Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046,

DOI 10.17487/RFC2046, November 1996,

<Information on RFC 2046 » RFC Editor>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119,

DOI 10.17487/RFC2119, March 1997,

<Information on RFC 2119 » RFC Editor>.

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,

DOI 10.17487/RFC3986, January 2005,

<Information on RFC 3986 » RFC Editor>.

[RFC4949]

Shirey, R., "Internet Security Glossary, Version 2", FYI 36, RFC 4949,

DOI 10.17487/RFC4949, August 2007,

<Information on RFC 4949 » RFC Editor>.

[RFC7159]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159,

DOI 10.17487/RFC7159, March 2014,

<http://www.rfc-editor.org/info/rfc7159>.

[UNICODE]

The Unicode Consortium, "The Unicode Standard",

<Unicode 15.1.0>.

13.2. 信息性参考文献

[CanvasApp]

Facebook, "Canvas Applications", 2010,

<http://developers.facebook.com/docs/authentication/canvas>.

[JSS]

Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", September 2010,

<http://jsonenc.info/jss/1.0/>.

[MagicSignatures]

Panzer, J., Ed., Laurie, B., and D. Balfanz, "Magic Signatures", January 2011,

<http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-01.html>.

[OASIS.saml-core-2.0-os]

Cantor, S., Kemp, J., Philpott, R., and E. Maler, "Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", OASIS Standard saml-core-2.0-os, March 2005,

<http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf>.

[POSIX.1]

IEEE, "The Open Group Base Specifications Issue 7", IEEE Std 1003.1, 2013 Edition, 2013,

<General Concepts>.

[RFC3275]

Eastlake 3rd, D., Reagle, J., and D. Solo, "(Extensible Markup Language) XML-Signature Syntax and Processing", RFC 3275, DOI 10.17487/RFC3275, March 2002,

<Information on RFC 3275 » RFC Editor>.

[RFC3339]

Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,

<Information on RFC 3339 » RFC Editor>.

[RFC4122]

Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10.17487/RFC4122, July 2005,

<Information on RFC 4122 » RFC Editor>.

[RFC5226]

Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI 10.17487/RFC5226, May 2008,

<Information on RFC 5226 » RFC Editor>.

[RFC6755]

Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,

<Information on RFC 6755 » RFC Editor>.

[RFC6838]

Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013,

<Information on RFC 6838 » RFC Editor>.

[SWT]

Hardt, D. and Y. Goland, "Simple Web Token (SWT)", Version 0.9.5.1, November 2009,

<http://msdn.microsoft.com/en-us/ library/windowsazure/hh781551.aspx>.

[W3C.CR-xml11-20060816]

Cowan, J., "Extensible Markup Language (XML) 1.1 (Second Edition)", World Wide Web Consortium Recommendation REC-xml11-20060816, August 2006,

<http://www.w3.org/TR/2006/REC-xml11-20060816>.

[W3C.REC-xml-c14n-20010315]

Boyer, J., "Canonical XML Version 1.0", World Wide Web Consortium Recommendation REC-xml-c14n-20010315, March 2001,

<http://www.w3.org/TR/2001/REC-xml-c14n-20010315>.

附录A JWT示例

本节包含JWT的示例。其他示例JWT请参阅本文件第6.1节和[JWS]的附录A.1-A.3。

A.1. 示例加密JWT（JSON Web Token）

这个示例使用RSAES-PKCS1-v1_5和AES_128_CBC_HMAC_SHA_256对第3.1节中使用的相同声明进行加密，并对接收者进行加密。

以下JOSE头部示例声明了：

• 使用RSAES-PKCS1-v1_5算法将内容加密密钥加密到接收者处以产生JWE加密密钥。
• 使用AES_128_CBC_HMAC_SHA_256算法对明文进行认证加密，以产生JWE密文和JWE身份验证标签。

{"alg":"RSA1_5","enc":"A128CBC-HS256"}

除了使用第3.1节中JWT声明集的UTF-8表示的八位组作为明文值之外，此JWT的计算与[JWE]附录A.2中JWE的计算相同，包括使用的密钥。

这个例子的最终结果（为了便于显示，这里添加了换行符）：

eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.
QR1Owv2ug2WyPBnbQrRARTeEk9kDO2w8qDcjiHnSJflSdv1iNqhWXaKH4MqAkQtMoNfABIPJaZm0HaA415sv3aeuBWnD8J-Ui7Ah6cWafs3ZwwFKDFUUsWHSK-IPKxLGTkND09XyjORj_CHAgOPJ-Sd8ONQRnJvWn_hXV1BNMHzUjPyYwEsRhDhzjAD26imasOTsgruobpYGoQcXUwFDn7moXPRfDE8-NoQX7N7ZYMmpUDkR-Cx9obNGwJQ3nM52YCitxoQVPzjbl7WBuB7AohdBoZOdZ24WlN1lVIeh8v1K4krB8xgKvRU8kgFrEn_a1rZgN5TiysnmzTROF869lQ.
AxY8DCtDaGlsbGljb3RoZQ.
MKOle7UQrG6nSxTLX6Mqwt0orbHvAKeWnDYvpIAeZ72deHxz3roJDXQyhxx0wKaMHDjUEOKIwrtkHthpqEanSBNYHZgmNOV7sln1Eu9g3J8.
fiK51VwhsxJ-siBMR-YFiA

A.2. 嵌套JWT示例

这个例子说明了如何使用JWT作为JWE或JWS的负载来创建一个嵌套的JWT。在这种情况下，首先对JWT的声明集进行签名，然后进行加密。

内部签名的JWT与[JWS]附录A.2中的示例相同。因此，这里不再重复其计算过程。接下来，使用RSAES-PKCS1-v15和AES-128 CBC HMAC SHA256将该内部JWT加密给收件人。

以下JOSE头部声明：

使用RSAES-PKCS1-v1_5算法将内容加密密钥加密到接收者，以产生JWE加密密钥。

使用AES_128_CBC_HMAC_SHA_256算法对明文进行认证加密，以生成JWE加密文和JWE身份验证标签。

明文本身就是JWT。

{"alg":"RSA1_5","enc":"A128CBC-HS256","cty":"JWT"}

对JOSE头部字段的UTF-8表示的字节进行Base64URL编码，得到该编码的JOSE头部字段值：

eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5IjoiSldUIn0

该JWT的计算与[JWE]附录A.2中JWE的计算相同，除了使用的不同的JOSE头部、明文、JWE初始化向量和内容加密密钥值之外。(使用的RSA密钥是相同的)。

使用的明文是附录A.2.1中[JWS]结尾的ASCII[RFC20]表示的JWT的八位字节串（去除所有空白字符和换行符），这是一个包含458个八位字节的序列。

使用的JWE初始化向量值（使用JSON数组表示法）为：

[82, 101, 100, 109, 111, 110, 100, 32, 87, 65, 32, 57, 56, 48, 53, 50]

这个例子使用了由下面的Base64URL编码值表示的内容加密密钥：

GawgguFyGrWKav7AX4VKUg

嵌套JWT的最终结果（为便于显示进行了换行）：

eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5IjoiSldUIn0.
g_hEwksO1Ax8Qn7HoN-BVeBoa8FXe0kpyk_XdcSmxvcM5_P296JXXtoHISr_DD_MqewaQSH4dZOQHoUgKLeFly-9RI11TG-_Ge1bZFazBPwKC5lJ6OLANLMd0QSL4fYEb9ERe-epKYE3xb2jfY1AltHqBO-PM6j23Guj2yDKnFv6WO72tteVzm_2n17SBFvhDuR9a2nHTE67pe0XGBUS_TK7ecA-iVq5COeVdJR4U4VZGGlxRGPLRHvolVLEHx6DYyLpw30Ay9R6d68YCLi9FYTq3hIXPK_-dmPlOUlKvPr1GgJzRoeC9G5qCvdcHWsqJGTO_z3Wfo5zsqwkxruxwA.
UmVkbW9uZCBXQSA5ODA1Mg.
VwHERHPvCNcHHpTjkoigx3_ExK0Qc71RMEParpatm0X_qpg-w8kozSjfNIPPXiTBBLXR65CIPkFqz4l1Ae9w_uowKiwyi9acgVztAi-pSL8GQSXnaamh9kX1mdh3M_TT-FZGQFQsFhu0Z72gJKGdfGE-OE7hS1zuBD5oEUfk0Dmb0VzWEzpxxiSSBbBAzP10l56pPfAtrjEYw-7ygeMkwBl6Z_mLS6w6xUgKlvW6ULmkV-uLC4FUiyKECK4e3WZYKw1bpgIqGYsw2v_grHjszJZ-_I5uM-9RA8ycX9KqPRp9gc6pXmoU_-27ATs9XCvrZXUtK2902AUzqpeEUJYjWWxSNsS-r1TJ1I-FMJ4XyAiGrfmo9hQPcNBYxPz3GQb28Y5CLSQfNgKSGt0A4isp1hBUXBHAndgtcslt7ZoQJaKe_nNJgNliWtWpJ_ebuOpEl8jdhehdccnRMIwAmU1n7SPkmhIl1HlSOpvcvDfhUN5wuqU955vOBvfkBOh5A11UzBuo2WlgZ6hYi9-e3w29bR0C2-pp3jbqxEDw3iWaf2dc5b-LnR0FEYXvI_tYk5rd_J9N0mg0tQ6RbpxNEMNoA9QWk5lgdPvbh9BaO195abQ.
AVO9iT5AV4CzvDJCdhSFlQ

附录B. JWTs与SAML断言的关系

安全断言标记语言 (SAML) 2.0

[OASIS.saml-core-2.0-os]提供了比JWTs更强大和更安全的表达能力和更多安全选项的标准，用于创建安全令牌。然而，这种灵活性和表达力的成本是大小和复杂性。SAML使用XML[W3C.CR-xml11-20060816]和XML数字签名(DSIG)[RFC3275]来增加SAML断言的大小，使用XML，特别是XML规范化[W3C.REC-xml-c14n-20010315]来增加其复杂性。

JWT的目的是提供一个简单的安全令牌格式，该格式足够小，可以放入HTTP头部和URI中的查询参数。它通过支持比SAML更简单的令牌模型，并使用JSON[RFC7159]对象编码语法来实现这一点。它还支持使用消息认证码（MAC）和数字签名来保护令牌，数字签名使用比XMLDSIG更小（且不那么灵活）的格式。

因此，虽然JWT可以做SAML断言所做的一些事情，但JWT并不是为了完全取代SAML断言而设计的，而是作为一种令牌格式，在考虑到实施简便或紧凑性时使用。

SAML断言总是实体关于主题的声明。JWT通常以相同的方式使用，实体通过“iss”（发行者）声明来表达声明，主题通过“sub”（主题）声明来表达。然而，由于这些声明是可选的，因此也允许使用JWT格式的其他用途。

附录C. JWTs与简单Web令牌（SWTs）的关系

无论是JWT还是SWT（SWT），其核心都在于能在应用之间传递一组声明。对于SWT来说，声明名称和声明值都是字符串。对于JWT来说，虽然声明名称是字符串，但声明值可以是任何JSON类型。这两种令牌类型都为其内容提供了加密保护：SWT使用HMAC SHA-256，而JWT则可以选择算法，包括签名算法、MAC算法和加密算法。

感谢

作者们承认JWT的设计有意受到了SWT的设计和简单性以及DickHardt在OpenID社区讨论的JSON令牌的想法的影响。

以前探索过签名JSON内容的方案有Magic Signatures[MagicSignatures]，JSON Simple Sign[JSS]，以及Canvas Applications[CanvasApp]，所有这些方案都对本文档产生了影响。

本规范是由OAuth工作组编写的，该工作组包括数十名积极而专注的参与者。

特别是，以下个人提供了影响此规范的想法、反馈和措辞：Dirk Balfanz, Richard Barnes, Brian Campbell, Alissa Cooper, Breno de Medeiros, Stephen Farrell, Yaron Y. Goland, Dick Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Warren Kumari, Ben Laurie, Barry Leiba, Ted Lemon, James Manger, Prateek Mishra, Kathleen Moriarty, Tony Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, David Recordon, Eric Rescorla, Jim Schaad, Paul Tarjan, Hannes Tschofenig, Sean Turner, and Tom Yu.

在制定此规范的过程中，Hannes Tschofenig和Derek Atkins担任了OAuth工作组的主席，而Sean Turner、Stephen Farrell和Kathleen Moriarty则担任了安全区的主管。

作者地址

Michael B. Jones

Microsoft

EMail: mbj@microsoft.com

URI: Mike Jones: self-issued – Musings on Digital Identity

John Bradley Ping Identity

EMail: ve7jtb@ve7jtb.com

URI: Thread Safe

Nat Sakimura

Nomura Research Institute

EMail: n-sakimura@nri.co.jp

URI: .Nat Zone – Digital Identity and Privacy