jsonwebtoken
See JSON Web Tokens for more information on what JSON Web Tokens are.
Installation
Add the following to Cargo.toml:
= "9"
# If you do not need pem decoding, you can disable the default feature `use_pem` that way:
# jsonwebtoken = {version = "9", default-features = false }
= { = "1.0", = ["derive"] }
The minimum required Rust version (MSRV) is 1.67.
Algorithms
This library currently supports the following:
- HS256
- HS384
- HS512
- RS256
- RS384
- RS512
- PS256
- PS384
- PS512
- ES256
- ES384
- EdDSA
How to use
Complete examples are available in the examples directory: a basic one and one with a custom header.
In terms of imports and structs:
use ;
use ;
/// Our claims struct, it needs to derive `Serialize` and/or `Deserialize`
Claims
The claims fields which can be validated. (see validation)
Header
The default algorithm is HS256, which uses a shared secret.
let token = encode?;
Custom headers & changing algorithm
All the parameters from the RFC are supported but the default header only has typ
and alg
set.
If you want to set the kid
parameter or change the algorithm for example:
let mut header = new;
header.kid = Some;
let token = encode?;
Look at examples/custom_header.rs
for a full working example.
Encoding
// HS256
let token = encode?;
// RSA
let token = encode?;
Encoding a JWT takes 3 parameters:
- a header: the
Header
struct - some claims: your own struct
- a key/secret
When using HS256, HS384, or HS512, the key is always a shared secret like in the example above. When using RSA/EC, the key should always be the content of the private key in PEM or DER format.
If your key is in PEM format, it is better performance wise to generate the EncodingKey
once in a lazy_static
or
something similar and reuse it.
Decoding
// `token` is a struct with 2 fields: `header` and `claims` where `claims` is your own struct.
let token = ?;
decode
can result in errors for a variety of reasons:
- the token or its signature is invalid
- the token had invalid base64
- validation of at least one reserved claim failed
As with encoding, when using HS256, HS384, or HS512, the key is always a shared secret like in the example above. When using RSA/EC, the key should always be the content of the public key in PEM (or certificate in this case) or DER format.
In some cases, for example if you don't know the algorithm used or need to grab the kid
, you can choose to decode only the header:
let header = decode_header?;
This does not perform any signature verification or validate the token claims.
You can also decode a token using the public key components of a RSA key in base64 format. The main use-case is for JWK where your public key is in a JSON format like so:
// `token` is a struct with 2 fields: `header` and `claims` where `claims` is your own struct.
let token = ?;
If your key is in PEM format, it is better performance wise to generate the DecodingKey
once in a lazy_static
or
something similar and reuse it.
Convert SEC1 private key to PKCS8
jsonwebtoken
currently only supports PKCS8 format for private EC keys. If your key has BEGIN EC PRIVATE KEY
at the top,
this is a SEC1 type and can be converted to PKCS8 like so:
Validation
This library automatically validates the exp
claim, and nbf
is validated if present. You can also validate the sub
, iss
, and aud
but
those require setting the expected values in the Validation
struct. In the case of aud
, if there is a value set in the token but
not in the Validation
, the token will be rejected.
Since validating time fields is always a bit tricky due to clock skew,
you can add some leeway to the iat
, exp
, and nbf
validation by setting the leeway
field.
Last but not least, you will need to set the algorithm(s) allowed for this token if you are not using HS256
.
Look at examples/validation.rs
for a full working example.