jsonwebtoken

在 docs.rs 上的 API 文档

安装

将以下内容添加到 Cargo.toml

jsonwebtoken = "4"
serde_derive = "1"
serde = "1"

使用方法

完整示例可在 examples 目录中找到：一个是基本示例，另一个是带有自定义头部的示例。

关于导入和结构体

extern crate jsonwebtoken as jwt;
#[macro_use]
extern crate serde_derive;

use jwt::{encode, decode, Header, Algorithm, Validation};

/// Our claims struct, it needs to derive `Serialize` and/or `Deserialize`
#[derive(Debug, Serialize, Deserialize)]
struct Claims {
    sub: String,
    company: String
}

编码

默认算法为 HS256。

let token = encode(&Header::default(), &my_claims, "secret".as_ref())?;

自定义头部和更改算法

支持所有 RFC 参数，但默认头部仅设置了 typ 和 alg。如果您想设置 kid 参数或更改算法，例如

let mut header = Header::default();
header.kid = Some("blabla".to_owned());
header.alg = Algorithm::HS512;
let token = encode(&header, &my_claims, "secret".as_ref())?;

请查看 examples/custom_header.rs 以获取完整的示例。

解码

let token = decode::<Claims>(&token, "secret".as_ref(), &Validation::default())?;
// token is a struct with 2 params: header and claims

decode 可能由于各种原因出错

• 令牌或其签名无效
• 解码 base64 时出错，或解码 base64 的结果不是有效的 UTF-8
• 至少有一个保留声明验证失败

在某些情况下，例如如果您不知道使用的算法，您可能只想解码头部

let header = decode_header(&token)?;

这不会对令牌进行任何验证。

验证

如果存在，此库会自动验证 iat、exp 和 nbf 声明。您还可以验证 sub、iss 和 aud，但那些需要在 Validation 结构体中设置预期值。

由于验证时间字段始终有些棘手，因为存在时钟偏差，您可以通过设置 leeway 参数来为 iat、exp 和 nbf 验证添加一些容错。

最后但同样重要的是，如果您不使用 HS256，则需要设置允许此令牌的算法。

use jsonwebtoken::{Validation, Algorithm};

// Default validation: the only algo allowed is HS256
let validation = Validation::default();
// Quick way to setup a validation where only the algorithm changes
let validation = Validation::new(Algorithm::HS512);
// Adding some leeway (in seconds) for iat, exp and nbf checks
let mut validation = Validation {leeway: 60, ..Default::default()};
// Checking issuer
let mut validation = Validation {iss: Some("issuer".to_string()), ..Default::default()};
// Setting audience
let mut validation = Validation::default();
validation.set_audience(&"Me"); // string
validation.set_audience(&["Me", "You"]); // array of strings

算法

此库目前支持以下算法

• HS256
• HS384
• HS512
• RS256
• RS384
• RS512

RSA

jsonwebtoken 目前只能读取 DER 编码的密钥。如果您已安装 openssl，可以使用以下命令从 .pem 文件中获取 DER 密钥：

// private key
$ openssl rsa -in private_rsa_key.pem -outform DER -out private_rsa_key.der
// public key
$ openssl rsa -in private_rsa_key.der -inform DER -RSAPublicKey_out -outform DER -out public_key.der

如果您的公钥出现错误，请确保您使用上述命令获取，以确保其格式正确。