一个网站要辨识/验证(authentication)访客主要会使用 session、cookie-based session 或 token 这三种方式,JWT (JSON Web Token)顾名思义就是属于 token 的验证方式。使用 JWT 来验证访者,服务器可以不用去记忆访客的状态,因为 JWT 本身就可以保存少量的额外数据,这点和 cookie-based session 相像,但 JWT 不仅仅能放在 Cookie 中发送,也还可以置于 HTTP 标头中或是包含在 URL 内。那么在 Rocket 框架中,要如何使用 JWT 来验证访客呢?

在开始进入 Rocket 框架之前,再来多介绍一下 JWT 吧!先从 JWS (JSON Web Signature)开始讲起。

JWS (JSON Web Signature)

JWS (JSON Web Signature)是一种基于 base64url 和 JSON 格式来发送消息的数据格式,它将消息分为三个部份,分别是标头(JOSE Header)、主体/负载(JWS Payload)和签名(JWS Signature)。其中标头的部份包含 JWS Protected Header 和 JWS Unprotected Header 两种,这边讲的「Protected」有点模糊,笔者认为应该只是在产生签名的时候要不要被纳入计算中。一般来说我们都会使用 JWS Protected Header,因为它会被纳入签名的计算,可避免标头被窜改。

至于负载具体是什么东东,JWS 并未规范,它可以是任意的数据格式。

再来是签名。JWS 的签名可以根据 JWS Protected Header 和负载产生出 MAC (Message Authentication Code)。用来将签名具体产生出来的算法,其名称必须被纳入标头中,因为验证时可能需要被用到。如下:

{
    "alg": "<the algorithm used for generating the signature>"
}

另外 JWS 还有规定一些选填的标头字段,但是使用非嵌套的 JWT + JWS 时用不太到。

JWS 还订定了两种串行化的方式,分别是 JWS Compact Serialization 和 JWS JSON Serialization。由于 JWT 只使用 JWS Compact Serialization,故在此就不介绍 JWS JSON Serialization 了。

JWS Compact Serialization 的作法很简单,就是将 JWS 的 JWS Protected Header、负载和签名这三个部份分别作 base64url 编码,再用半角英文句点 . 串接在一起。如下:

base64url(JWS Protected Header).base64url(JWS Payload).base64url(JWS Signature)

JWT (JSON Web Token)

JWT 是针对当 JWS 的负载或是当 JWE 的明码是 JSON 对象时所做的规范,不过由于 JWE 并不太适合用在访客验证上,这边就不多作介绍了。上面在介绍 JWS 时,提到了一些未具体规范的项目,在 JWT 这边便开宗明义地规定了 JWT 的负载要是一个 JSON 对象,并且限定串行化的方式只能够使用 JWS Compact Serialization。

在 JWT 规范下,负载的部份称为 JWT Claims,一个「claim」就是一组 key-value 数据。以下是有被明确规范用途的字段,都是选填的:

{
    "iss": "<the issuer of this JWT>",
    "sub": "<the subject of this JWT>",
    "aud": ["<the recipients of this JWT>"],
    "exp": <the unix timestamp of expiration date/time in seconds>,
    "nbf": <the unix timestamp in seconds on which the JWT will start to be accepted for processing>,
    "iat": <the unix timestamp in seconds at which the JWT was issued>,
    "jti": <the unique id of this JWT>,
}

以上字段中,最常使用的字段应该是 exp,它规定了这个 JWT 消息的有效截止时间,拿来用作用户登录验证的话,就是登录失效的时间。

同样地,用作用户登录验证的 JWT + JWS,由于不需要让客户端自行校验数据的完整性,因此可以直接使用 HMAC + SHA256/384/512 对称密钥算法来产生签名。一般在使用哈希函数的时候会将要哈希的数据进行加盐(salt)的动作,避免被进行彩虹表攻击(Rainbow Table Attack),然而加盐可以有诸多种方式,安全性和性能容易有争议。HMAC (Keyed-hash Message Authentication Code)是一种加盐哈希的标准函数,它将盐作为密钥(key),会先经过填充和哈希处理后再与我们要哈希的数据做串接,最后再进行一次哈希。而利用 JWT + JWS + HMAC + SHA256/384/512 来进行用户登录验证时,通常不需要针对不同用户设置不同的盐,因为这里并不存在用户密码会遭反解外流的可能,HMAC 在这里的用途纯粹只是要利用只有服务器知道的盐来产生签名而已。

用户透过服务器的登录 API,提供登录所需的验证数据(例如帐号、密码)后,如果数据正确无误,服务器便可以利用 JWT 来保存该用户的 ID 和额外需要记录的状态,再将 JWT 串行化之后传给用户保存。之后用户向服务器发送请求时,便可以顺便发送这个经过串行化之后的 JWT,来让服务器去重新使用相同的 HMAC + SHA256/384/512 去计算 JWT 的标头和负载的签名,看结果是否会与用户传来的 JWT 自带的签名一致,如果一致表示用户传来的 JWT 是没有被窜改过的,就可以放心地拿来利用啦!

jwt-authorization Request Guard for Rocket Framework

「jwt-authorization Request Guard for Rocket Framework」是笔者开发的套件,可以利用进程式宏来产生指定好密钥以及签名算法的结构体,作为 Rocket 框架的请求守卫。

Crates.io

Cargo.toml

rocket-jwt-authorization = "*"

使用方法

由于「jwt-authorization Request Guard for Rocket Framework」是一个进程式宏的函数库,所以除了引用 rocket_jwt_authorization 至目前的 Cargo 项目外,还需要引用 jwt、hmac 和 sha2、serde、serde_derive 这 5 个 crate。

jwt = "*"
hmac = "*"
sha2 = "*"
serde = "*"
serde_derive = "*"

rocket_jwt_authorization = "*"

以下是产生 JWT 请求守卫的程序:

#[macro_use]
extern crate rocket_jwt_authorization;

#[macro_use]
extern crate serde_derive;

#[derive(Debug, Serialize, Deserialize, JWT)]
#[jwt("secret_key", sha2::Sha256, Cookie = "access_token")]
pub struct UserAuth {
    #[serde(flatten)]
    registered: jwt::RegisteredClaims,
    id: i32,
}

以上的 UserAuth 结构体是一个 JWT 请求守卫,其使用的密钥为 secret_key,产生签名的算法为 HS256 (HMAC + SHA256),且会去读取 Cookie 中的 access_token 字段来反串行化 JWT。

UserAuth 结构体中的使用字段可以是任意的。jwt::RegisteredClaims 结构体提供了 JWT 有明确定义的字段(如 iss),可以搭配 #[serde(flatten)] 属性将它们引用进我们自己的结构体当中。不过 jwt::RegisteredClaims 结构体中的字段是没有实质功能的,例如我们若设置了 exp 字段,就必须要自行在路由处理程序中写程序检查这个 JWT 是否逾时。

如果想从 Cookie 之外来读取请求中已串行化的 JWT,例如要从标头的 Authorization 字段或是从网址的 Query 中读取已串行化的 JWT 也是可行的,而且我们还可以自订顺序呢!如下:

#[derive(Debug, Serialize, Deserialize, JWT)]
#[jwt("secret_key", sha2::Sha256, Cookie = "access_token", Header, Query = "access_token")]
pub struct UserAuth {
    id: i32,
}

以上的 UserAuth 结构体作为 JWT 请求守卫使用时,会先去读取请求 Cookie 中的 access_token 字段。如果没有发现 JWT 的存在,就会去读取请求标头的 Authorization 字段,看有没有以 Bearer 为开头的已串行化的 JWT。如果还是没有发现 JWT 的存在,就会去读取 Query 中的 access_token 字段。

如果不是当作请求守卫来使用,可以自行调用 UserAuth 结构体提供的 verify_jwt_token 关联函数,并传入已串行化的 JWT 来进行验证和反串行化的动作。

UserAuth 结构实体提供的 get_jwt_token 方法则可以将该实体进行串行化。

另外,对于会去读取 Cookie 的 JWT 请求守卫,结构实体还提供了 set_cookie、set_cookie_insecure 和 remove_cookie 方法,可以快速地对 Cookie 的指定字段(在属性中填入的 Cookie 字段)进行操作。