Update README
This commit is contained in:
parent
35fd9d63cc
commit
3e3c752974
54
README.md
54
README.md
|
@ -6,8 +6,8 @@
|
||||||
Add the following to Cargo.toml:
|
Add the following to Cargo.toml:
|
||||||
|
|
||||||
```toml
|
```toml
|
||||||
jsonwebtoken = "1"
|
jsonwebtoken = "2"
|
||||||
rustc-serialize = "0.3"
|
serde_derive = "0.9"
|
||||||
```
|
```
|
||||||
|
|
||||||
## How to use
|
## How to use
|
||||||
|
@ -16,9 +16,10 @@ There is a complete example in `examples/claims.rs` but here's a quick one.
|
||||||
In terms of imports:
|
In terms of imports:
|
||||||
```rust
|
```rust
|
||||||
extern crate jsonwebtoken as jwt;
|
extern crate jsonwebtoken as jwt;
|
||||||
extern crate rustc_serialize;
|
#[macro_use]
|
||||||
|
extern crate serde_derive;
|
||||||
|
|
||||||
use jwt::{encode, decode, Header, Algorithm};
|
use jwt::{encode, decode, Header, Algorithm, Validation};
|
||||||
```
|
```
|
||||||
|
|
||||||
Look at the examples directory for 2 examples: a basic one and one with a custom
|
Look at the examples directory for 2 examples: a basic one and one with a custom
|
||||||
|
@ -28,24 +29,43 @@ header.
|
||||||
```rust
|
```rust
|
||||||
let token = encode(&Header::default(), &my_claims, "secret".as_ref()).unwrap();
|
let token = encode(&Header::default(), &my_claims, "secret".as_ref()).unwrap();
|
||||||
```
|
```
|
||||||
In that example, `my_claims` is an instance of a Claims struct that derives `RustcEncodable` and `RustcDecodable`.
|
In that example, `my_claims` is an instance of a Claims struct that derives `Serialize` and `Deserialize`.
|
||||||
The default algorithm is HS256.
|
The default algorithm is HS256.
|
||||||
Look at custom headers section to see how to change that.
|
Look at custom headers section to see how to change that.
|
||||||
|
|
||||||
### Decoding
|
### Decoding
|
||||||
```rust
|
```rust
|
||||||
let token = decode::<Claims>(&token, "secret", Algorithm::HS256).unwrap();
|
let token = decode::<Claims>(&token, "secret", Algorithm::HS256, &Validation::default()).unwrap();
|
||||||
// token is a struct with 2 params: header and claims
|
// token is a struct with 2 params: header and claims
|
||||||
```
|
```
|
||||||
In addition to the normal base64/json decoding errors, `decode` can return two custom errors:
|
`decode` can error for a variety of reasons:
|
||||||
|
|
||||||
- **InvalidToken**: if the token is not a valid JWT
|
- the token or its signature is invalid
|
||||||
- **InvalidSignature**: if the signature doesn't match
|
- error while decoding base64 or the result of decoding base64 is not valid UTF-8
|
||||||
- **WrongAlgorithmHeader**: if the alg in the header doesn't match the one given to decode
|
- validation failed
|
||||||
|
|
||||||
### Validation
|
### Validation
|
||||||
The library only validates the algorithm type used but does not verify claims such as expiration.
|
This library validates automatically the `iat`, `exp` and `nbf` claims if found. You can also validate the `sub`, `iss` and `aud` but
|
||||||
Feel free to add a `validate` method to your claims struct to handle that: there is an example of that in `examples/claims.rs`.
|
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.
|
||||||
|
|
||||||
### Custom headers
|
### 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.
|
All the parameters from the RFC are supported but the default header only has `typ` and `alg` set: all the other fields are optional.
|
||||||
|
@ -60,5 +80,11 @@ let token = encode(&header, &my_claims, "secret".as_ref()).unwrap();
|
||||||
Look at `examples/custom_header.rs` for a full working example.
|
Look at `examples/custom_header.rs` for a full working example.
|
||||||
|
|
||||||
## Algorithms
|
## Algorithms
|
||||||
The HMAC SHA family is supported: HMAC SHA256, HMAC SHA384 and HMAC SHA512 as well as the RSA PKCS1: RSA_PKCS1_SHA256,
|
This library currently supports the following:
|
||||||
RSA_PKCS1_SHA384 and RSA_PKCS1_SHA512.
|
|
||||||
|
- HS256
|
||||||
|
- HS384
|
||||||
|
- HS512
|
||||||
|
- RS256
|
||||||
|
- RS384
|
||||||
|
- RS512
|
||||||
|
|
|
@ -1,5 +1,6 @@
|
||||||
extern crate jsonwebtoken as jwt;
|
extern crate jsonwebtoken as jwt;
|
||||||
#[macro_use] extern crate serde_derive;
|
#[macro_use]
|
||||||
|
extern crate serde_derive;
|
||||||
|
|
||||||
use jwt::{encode, decode, Header, Algorithm, Validation};
|
use jwt::{encode, decode, Header, Algorithm, Validation};
|
||||||
use jwt::errors::{ErrorKind};
|
use jwt::errors::{ErrorKind};
|
||||||
|
@ -11,18 +12,6 @@ struct Claims {
|
||||||
company: String
|
company: String
|
||||||
}
|
}
|
||||||
|
|
||||||
// Example validation implementation
|
|
||||||
impl Claims {
|
|
||||||
fn is_valid(&self) -> bool {
|
|
||||||
if self.company != "ACME" {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
// expiration etc
|
|
||||||
|
|
||||||
true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
fn main() {
|
fn main() {
|
||||||
let my_claims = Claims {
|
let my_claims = Claims {
|
||||||
sub: "b@b.com".to_owned(),
|
sub: "b@b.com".to_owned(),
|
||||||
|
@ -35,15 +24,16 @@ fn main() {
|
||||||
};
|
};
|
||||||
|
|
||||||
println!("{:?}", token);
|
println!("{:?}", token);
|
||||||
|
let validation = Validation {sub: Some("b@b.com".to_string()), ..Validation::default()};
|
||||||
|
|
||||||
let token_data = match decode::<Claims>(&token, key.as_ref(), Algorithm::HS256, Validation::default()) {
|
let token_data = match decode::<Claims>(&token, key.as_ref(), Algorithm::HS256, validation) {
|
||||||
Ok(c) => c,
|
Ok(c) => c,
|
||||||
Err(err) => match *err.kind() {
|
Err(err) => match *err.kind() {
|
||||||
ErrorKind::InvalidToken => panic!(), // Example on how to handle a specific error
|
ErrorKind::InvalidToken => panic!(), // Example on how to handle a specific error
|
||||||
|
ErrorKind::InvalidIssuer => panic!(), // Example on how to handle a specific error
|
||||||
_ => panic!()
|
_ => panic!()
|
||||||
}
|
}
|
||||||
};
|
};
|
||||||
println!("{:?}", token_data.claims);
|
println!("{:?}", token_data.claims);
|
||||||
println!("{:?}", token_data.header);
|
println!("{:?}", token_data.header);
|
||||||
println!("{:?}", token_data.claims.is_valid());
|
|
||||||
}
|
}
|
Loading…
Reference in New Issue