2015-11-02 18:27:28 -05:00
|
|
|
# jsonwebtoken
|
2015-10-31 11:37:15 -04:00
|
|
|
|
2015-11-02 16:04:58 -05:00
|
|
|
[![Build Status](https://travis-ci.org/Keats/rust-jwt.svg)](https://travis-ci.org/Keats/rust-jwt)
|
|
|
|
|
2015-11-02 18:27:28 -05:00
|
|
|
## Installation
|
|
|
|
Add the following to Cargo.toml:
|
|
|
|
|
|
|
|
```toml
|
2017-04-12 21:29:30 -04:00
|
|
|
jsonwebtoken = "2"
|
|
|
|
serde_derive = "0.9"
|
2015-11-02 18:27:28 -05:00
|
|
|
```
|
2015-11-02 16:04:58 -05:00
|
|
|
|
|
|
|
## How to use
|
2015-12-22 12:17:53 -05:00
|
|
|
There is a complete example in `examples/claims.rs` but here's a quick one.
|
2015-11-02 16:04:58 -05:00
|
|
|
|
2015-11-02 18:32:32 -05:00
|
|
|
In terms of imports:
|
|
|
|
```rust
|
|
|
|
extern crate jsonwebtoken as jwt;
|
2017-04-12 21:29:30 -04:00
|
|
|
#[macro_use]
|
|
|
|
extern crate serde_derive;
|
2015-11-02 18:32:32 -05:00
|
|
|
|
2017-04-12 21:29:30 -04:00
|
|
|
use jwt::{encode, decode, Header, Algorithm, Validation};
|
2015-11-02 18:32:32 -05:00
|
|
|
```
|
|
|
|
|
2015-12-22 12:17:53 -05:00
|
|
|
Look at the examples directory for 2 examples: a basic one and one with a custom
|
|
|
|
header.
|
|
|
|
|
2015-11-02 16:04:58 -05:00
|
|
|
### Encoding
|
|
|
|
```rust
|
2017-04-10 23:58:50 -04:00
|
|
|
let token = encode(&Header::default(), &my_claims, "secret".as_ref()).unwrap();
|
2015-11-02 16:04:58 -05:00
|
|
|
```
|
2017-04-12 21:29:30 -04:00
|
|
|
In that example, `my_claims` is an instance of a Claims struct that derives `Serialize` and `Deserialize`.
|
2015-12-22 12:17:53 -05:00
|
|
|
The default algorithm is HS256.
|
|
|
|
Look at custom headers section to see how to change that.
|
2015-11-02 16:04:58 -05:00
|
|
|
|
|
|
|
### Decoding
|
|
|
|
```rust
|
2017-04-12 21:29:30 -04:00
|
|
|
let token = decode::<Claims>(&token, "secret", Algorithm::HS256, &Validation::default()).unwrap();
|
2015-12-19 19:58:46 -05:00
|
|
|
// token is a struct with 2 params: header and claims
|
2015-11-02 16:04:58 -05:00
|
|
|
```
|
2017-04-12 21:29:30 -04:00
|
|
|
`decode` can error for a variety of reasons:
|
2015-11-02 16:04:58 -05:00
|
|
|
|
2017-04-12 21:29:30 -04:00
|
|
|
- the token or its signature is invalid
|
|
|
|
- error while decoding base64 or the result of decoding base64 is not valid UTF-8
|
|
|
|
- validation failed
|
2015-11-02 16:04:58 -05:00
|
|
|
|
2015-11-03 13:38:41 -05:00
|
|
|
### Validation
|
2017-04-12 21:29:30 -04:00
|
|
|
This library validates automatically the `iat`, `exp` and `nbf` claims if found. You can also validate the `sub`, `iss` and `aud` but
|
|
|
|
those require setting the expected value.
|
|
|
|
You can add some leeway to the `iat`, `exp` and `nbf` validation by setting the `leeway` parameter as shown in the example below.
|
|
|
|
|
|
|
|
```rust
|
|
|
|
use jsonwebtoken::Validation;
|
|
|
|
|
|
|
|
// Default valuation
|
|
|
|
let validation = Validation::default();
|
|
|
|
// Adding some leeway
|
|
|
|
let mut validation = Validation {leeway: 1000 * 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
|
|
|
|
```
|
|
|
|
|
|
|
|
It's also possible to disable verifying the signature of a token by setting the `validate_signature` to `false`. This should
|
|
|
|
only be done if you know what you are doing.
|
2015-11-03 13:38:41 -05:00
|
|
|
|
2015-12-19 19:58:46 -05:00
|
|
|
### Custom headers
|
|
|
|
All the parameters from the RFC are supported but the default header only has `typ` and `alg` set: all the other fields are optional.
|
|
|
|
If you want to set the `kid` parameter for example:
|
|
|
|
|
|
|
|
```rust
|
|
|
|
let mut header = Header::default();
|
|
|
|
header.kid = Some("blabla".to_owned());
|
2015-12-21 14:23:10 -05:00
|
|
|
header.alg = Algorithm::HS512;
|
2017-04-10 23:58:50 -04:00
|
|
|
let token = encode(&header, &my_claims, "secret".as_ref()).unwrap();
|
2015-12-19 19:58:46 -05:00
|
|
|
```
|
2015-12-22 12:17:53 -05:00
|
|
|
Look at `examples/custom_header.rs` for a full working example.
|
2015-12-19 19:58:46 -05:00
|
|
|
|
2015-11-02 16:04:58 -05:00
|
|
|
## Algorithms
|
2017-04-12 21:29:30 -04:00
|
|
|
This library currently supports the following:
|
|
|
|
|
|
|
|
- HS256
|
|
|
|
- HS384
|
|
|
|
- HS512
|
|
|
|
- RS256
|
|
|
|
- RS384
|
|
|
|
- RS512
|