CWIKIUS 文档和手册

有关本文档的快速链接，请参考页面提示: | 链接名称 | URL | 内容说明 | |----------------|-------------------------------------------------------------------------|------------------------------------| | GitHub MD 源代文件 | https://github.com/cwiki-us-docs/cwikius-docs/blob/master/jwt/README.md | 将本页面中的内容转换为 MD 文件的手册，并存于 Github 上面 | | Docsify 转换后的手册 | https://cwiki-us-docs.github.io/cwikius-docs/#/jwt/README | 将 MD 文件使用 Docsify 转换后的手册链接地址 | | 问题讨论和社区 | https://www.ossez.com/tag/jwt | 请访问使用 JWT 标签 | | CWIKI.US 页面链接 | https://www.cwiki.us/display/CWIKIUSDOCS/JWT+-+JSON+Web+Token | Confluence 平台的原始翻译文件更新地址 | **NEW:** 获得 [免费的 JWT 手册（JWT Handbook）](https://auth0.com/resources/ebooks/jwt-handbook) 同时学习更多有关 JWT 的内容！ ## 什么是 JSON Web Token（JWT） JSON Web Token (JWT) 作为一个开放的标准 ([RFC 7519](https://tools.ietf.org/html/rfc7519)) 定义了一种简洁自包含的方法用于通信双方之间以 JSON 对象的形式安全的传递信息。因为有数字签名，所以这些通信的信息能够被校验和信任。 JWT 可以使用秘钥（secret）进行签名 (使用 **HMAC** 算法) 或使用 **RSA** 或 **ECDSA** 算法的公钥/私钥对（public/private key）。 尽管 JWT 可以在通讯的双方之间通过提供秘钥（secret）来进行签名，我们将会更多关注 **已签名（signed）**的 token。 通过签名的令牌可以验证其中数据的 *完整性（integrity）* ，而加密的令牌可以针对其他方 *隐藏（hide）* 申明。 当令牌（token）使用 公钥/私钥对（public/private key）进行签名的时候，只有持有私钥进行签名的一方是进行签名的。 ### 关键术语的中英文对照 * token - 令牌 * secret - 秘钥 * signature - 签名 * claims - 要求或者数据 ## 什么时候应该使用 JSON Web Tokens 在下面的一些场景中 JSON Web Tokens 可比较有用： * **认证鉴权（Authentication）**： 这是 JWT 最常见的应用场景。一旦用户成功登入，在随后的每次请求中都将会包含JWT信息。 通过JWT的验证机制后，将允许该用户访问路由（routes）、服务（services）以及该Token所允许的资源。因为 JWT 的开销非常小，使其非常容易在跨域环境下使用，现如今 JWT 被广泛应用到单点登录（Single Sign On）中。 * **信息交换（Information Exchange）**： 因为 JSON Web Tokens 是可以进行签名的，因此 JWT 能够在不同系统之间安全的传递信息。 例如基于使用公钥/私钥对（public/private key pairs），你可以确保请求的发送者是可信的。 同时，因为头部（header）和负载（payload）的信息和内容都参与了计算，所以你可以验证内容是否被篡改过。 ## JSON Web Token 的结构是什么？ JSON Web Tokens 由使用 (`.`) 分开的 3 个部分组成的，这 3 个部分分别是： - 头部（Header） - 负载（Payload） - 签名（Signature） 正是因为上面的组织形式，因此一个 JWT 通常看起如下面的表现形式。 `xxxxx.yyyyy.zzzzz` 让我们针对上面的形式来具体的分析下。 ### 头部（Header） 在头部的数据中 *通常* 包含有 2 部分的内容：token 的类型，这里使用的是字符 JWT，和使用的的签名加密算法，例如 SHA256 或者 RSA。 例如下面的格式： ``` { "alg": "HS256", "typ": "JWT" } ``` 然后，将上面的 JSON 数据格式使用 **Base64Url** 算法进行哈希，这样你就得到了 JWT 的第一部分。 ### 负载（Payload） JWT 的第二部分为负载，在负载中是由一些 claims 组成的。 Claims 是一些实体（通常指用户）和其他的一一些信息。 有下面 3 种类型的 claims *registered*， *public* 和 *private* 。 **[Registered claims](https://tools.ietf.org/html/rfc7519#section-4.1)**：这些 claims 是预先定义的，这些配置的内容不是必须的但是是推荐使用的，因此提供了一系列约定俗成使用的。比如：iss（issuer）， exp（expiration time）, sub（subject），aud（audience）和其他的一些更多的配置。 请注意，这些约定俗称的配置只有 3 个字符，以便于压缩数据量。 **[Public claims](https://tools.ietf.org/html/rfc7519#section-4.2)**：这些数据可以由使用 JWT 的用户自由去定义，但是为了避免冲突，你需要参考在 IANA JSON Web Token Registry 中对它们进行定义，或者将这些内容定义为 URI，并且需要避免可能出现的冲突。 **[Private claims](https://tools.ietf.org/html/rfc7519#section-4.3)**：这些内容是自定义的内容，这部分的内容被用于在数据传输短间进行转换的数据。这些数据是没有在 registered 和 public 中间没有定义的内容。 一个示例的负载： ```` { "sub": "1234567890", "name": "John Doe", "admin": true } ```` ### 负载（payload） 中的数据也是经过 Base64Url 进行加密的，这部分加密的内容组成了 JWT 的第二部分。 请注意：针对令牌这部分的签名已经被防范篡改。但是这部分还是可以被解密的，因此请不要将任何密钥放到这部分的数据中，除非你的密钥是已经加密过的密钥。 ### 签名（Signature） 为了创建一个加密部分，你需要有已经编码过的头部和负载，然后你还需要一个密钥（secret）和一个已经在头部中指定的加密算法来进行签名。 例如，如果你希望使用 HMAC SHA256 算法来进行签名，那么这个算法中使用的数据为： ```` HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), secret) ```` 签名的作用主要用于校验传输的令牌（Token）数据没有在过程中被篡改。 如果你的令牌是通过私有密钥进行签名的，那么也可以对 JWT 进行校验，以确定 JWT 的发送方使用是合法的签名。 ## 将所有内容整合在一起 将这个 3 部分的内容使用 Base64-URL 编码后整合到一起，将每部分的数据直接使用 点号（.） 进行分隔，以确保令牌数据能够比较容易的在网络 HTTP 和 HTML 环境中进行传输。 针对使用 XML 的令牌，例如 SAML 来说，JWT 显得更加简洁和高效。 下面是使用了头部信息，负载信息和数字签名然后组合到一起的一个 JWT 令牌示例：  如果你想使用 JWT，并且对一个已有的 JWT 令牌进行解密的话，你可以使用 https://jwt.io/#debugger-io 网站上提供的工具来对 JWT 字符串进行解密，校验和生产一个 JWT 令牌。  ## JSON Web Tokens 是如何工作的 在用户权限校验的过程中，一个用户如果使用授权信息成功登录后，一个 JSON Web Token 将会返回给用户端。 因为返回的令牌包含有授权信息，应用程序应小心保存这些授权信息，以避免不必要的安全问题。你的应用程序在不需要授权信息的时候，应用程序不应该保留授权成功后返回的令牌。 应用程序也不应该将这些敏感信息保存在浏览器中，因为这样会更加容易导致信息泄漏，请参考链接：https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html#local-storage 中的内容。 在任何时候，如果用户希望访问一个受