docs: Update README to match new library API

This commit is contained in:
Vincent Ambo 2018-09-04 12:36:59 +02:00
parent dd527ecdf1
commit 29dfb6826f
2 changed files with 26 additions and 31 deletions

View file

@ -1,8 +1,8 @@
alcoholic_jwt alcoholic_jwt
============= =============
This is a barebones library for **validation** of **RS256** JWTs using This is a library for **validation** of **RS256** JWTs using keys from
keys from a JWKS. Nothing more, nothing less. a JWKS. Nothing more, nothing less.
The name of the library stems from the potential side-effects of The name of the library stems from the potential side-effects of
trying to use the other Rust libraries that are made for similar trying to use the other Rust libraries that are made for similar
@ -21,36 +21,28 @@ extern crate alcoholic_jwt;
use alcoholic_jwt::{JWKS, Validation, validate, token_kid}; use alcoholic_jwt::{JWKS, Validation, validate, token_kid};
fn validate_token() { // The function implied here would usually perform an HTTP-GET
// serde instances provided // on the JWKS-URL for an authentication provider and deserialize
let jwks: JWKS = some_http_client(jwks_url).json(); // the result into the `alcoholic_jwt::JWKS`-struct.
let jwks: JWKS = jwks_fetching_function();
let token: String = some_token_fetcher(); let token: String = some_token_fetching_function();
// Several types of built-in validations are provided: // Several types of built-in validations are provided:
let validations = vec![ let validations = vec![
Validation::Issuer("some-issuer"), Validation::Issuer("auth.test.aprila.no".into()),
Validation::Audience("some-audience"),
Validation::SubjectPresent, Validation::SubjectPresent,
]; ];
// Extracting a KID is about the only safe operation that can be // If a JWKS contains multiple keys, the correct KID first
// done on a JWT before validating it. // needs to be fetched from the token headers.
let kid = token_kid(token).expect("No 'kid' claim present in token"); let kid = token_kid(&token)
.expect("Failed to decode token headers")
.expect("No 'kid' claim present in token");
let jwk = jwks.find(kid).expect("Specified key not found in set"); let jwk = jwks.find(&kid).expect("Specified key not found in set");
match validate(token, jwk, validations) { validate(token, jwk, validations).expect("Token validation has failed!");
Valid => println!("Token is valid!"),
InvalidSignature(reason) => println!("Token signature invalid: {}", reason),
InvalidClaims(reasons) => {
println!("Token claims are totally invalid!");
for reason in reasons {
println!("Validation failure: {}", reason);
}
},
}
}
``` ```
## Under the hood ## Under the hood

View file

@ -1,5 +1,9 @@
//! Implements a library for verifying JSON Web Tokens using the //! Implements a library for for **validation** of **RS256** JWTs
//! `RS256` signature algorithm. //! using keys from a JWKS. Nothing more, nothing less.
//!
//! The name of the library stems from the potential side-effects of
//! trying to use the other Rust libraries that are made for similar
//! purposes.
//! //!
//! This library is specifically aimed at developers that consume //! This library is specifically aimed at developers that consume
//! tokens from services which provide their RSA public keys in //! tokens from services which provide their RSA public keys in
@ -21,8 +25,7 @@
//! # let jwks_json = "{\"keys\":[{\"kty\":\"RSA\",\"alg\":\"RS256\",\"use\":\"sig\",\"kid\":\"8rDq8Pw0FZcaoXWTEVQo7+Tf2YzSL1fBxNKPCebaai4=\",\"n\":\"l4UTgk1zr-8C8utt0E57DtBV6qqAPWzVRrIuQS2j0_hp2CviaNl5XzGRDnB8gwk0Hx95YOhJupAe6RNq5ok3fDdxL7DLvppJNRLz3Ag9CsmDLcbXgNEQys33fBJaPw1v3GcaFC4tisU5p-o1f5RfWwvwdBtdBfGiwT1GRvbc5sFx6M4iYjg9uv1lNKW60PqSJW4iDYrfqzZmB0zF1SJ0BL_rnQZ1Wi_UkFmNe9arM8W9tI9T3Ie59HITFuyVSTCt6qQEtSfa1e5PiBaVuV3qoFI2jPBiVZQ6LPGBWEDyz4QtrHLdECPPoTF30NN6TSVwwlRbCuUUrdNdXdjYe2dMFQ\",\"e\":\"DhaD5zC7mzaDvHO192wKT_9sfsVmdy8w8T8C9VG17_b1jG2srd3cmc6Ycw-0blDf53Wrpi9-KGZXKHX6_uIuJK249WhkP7N1SHrTJxO0sUJ8AhK482PLF09Qtu6cUfJqY1X1y1S2vACJZItU4Vjr3YAfiVGQXeA8frAf7Sm4O1CBStCyg6yCcIbGojII0jfh2vSB-GD9ok1F69Nmk-R-bClyqMCV_Oq-5a0gqClVS8pDyGYMgKTww2RHgZaFSUcG13KeLMQsG2UOB2OjSC8FkOXK00NBlAjU3d0Vv-IamaLIszO7FQBY3Oh0uxNOvIE9ofQyCOpB-xIK6V9CTTphxw\"}]}"; //! # let jwks_json = "{\"keys\":[{\"kty\":\"RSA\",\"alg\":\"RS256\",\"use\":\"sig\",\"kid\":\"8rDq8Pw0FZcaoXWTEVQo7+Tf2YzSL1fBxNKPCebaai4=\",\"n\":\"l4UTgk1zr-8C8utt0E57DtBV6qqAPWzVRrIuQS2j0_hp2CviaNl5XzGRDnB8gwk0Hx95YOhJupAe6RNq5ok3fDdxL7DLvppJNRLz3Ag9CsmDLcbXgNEQys33fBJaPw1v3GcaFC4tisU5p-o1f5RfWwvwdBtdBfGiwT1GRvbc5sFx6M4iYjg9uv1lNKW60PqSJW4iDYrfqzZmB0zF1SJ0BL_rnQZ1Wi_UkFmNe9arM8W9tI9T3Ie59HITFuyVSTCt6qQEtSfa1e5PiBaVuV3qoFI2jPBiVZQ6LPGBWEDyz4QtrHLdECPPoTF30NN6TSVwwlRbCuUUrdNdXdjYe2dMFQ\",\"e\":\"DhaD5zC7mzaDvHO192wKT_9sfsVmdy8w8T8C9VG17_b1jG2srd3cmc6Ycw-0blDf53Wrpi9-KGZXKHX6_uIuJK249WhkP7N1SHrTJxO0sUJ8AhK482PLF09Qtu6cUfJqY1X1y1S2vACJZItU4Vjr3YAfiVGQXeA8frAf7Sm4O1CBStCyg6yCcIbGojII0jfh2vSB-GD9ok1F69Nmk-R-bClyqMCV_Oq-5a0gqClVS8pDyGYMgKTww2RHgZaFSUcG13KeLMQsG2UOB2OjSC8FkOXK00NBlAjU3d0Vv-IamaLIszO7FQBY3Oh0uxNOvIE9ofQyCOpB-xIK6V9CTTphxw\"}]}";
//! # serde_json::from_str(jwks_json).unwrap() //! # serde_json::from_str(jwks_json).unwrap()
//! # } //! # }
//! //! #
//!
//! // The function implied here would usually perform an HTTP-GET //! // The function implied here would usually perform an HTTP-GET
//! // on the JWKS-URL for an authentication provider and deserialize //! // on the JWKS-URL for an authentication provider and deserialize
//! // the result into the `alcoholic_jwt::JWKS`-struct. //! // the result into the `alcoholic_jwt::JWKS`-struct.