JWT validation library for basebox (and maybe others :-) )
Synopsis
This lib was created to provide a straight forward, simple and reliable way to validate JWTs against a set of public keys loaded from a URL. We at basebox use it to validate OpenID Connect ID Tokens (which are JWTs) using the set of public keys published by the OpenID server (e.g. Keycloak).
It provides the following features:
- Download a set of public keys from a URL (a JSON Web Key Set)
- Provide an entry point to update the keyset if necessary
- Parse JWTs and validate them using the key(s) in the downloaded keyset.
And that's it.
Besides, we designed bbjwt to meet the following requirements:
- No unsecure code
- Never panic
- No lifetime specifiers in the API
- Asynchronous
- Thread safe
Algorithm Support
The following table shows all signing algorithms supported by bbjwt, along with some info about their usage in JWKs, JWTs etc.
Note Please note that support for Ed448 and ES512 signatures was dropped in bbjwt 0.3.0.*
Name | JOSE "kty" | JOSE "alg" | JOSE "curve" |
---|---|---|---|
RSA256 | RSA | RS256 | |
RSA384 | RSA | RS384 | |
RSA512 | RSA | RS512 | |
ES256 | EC | ES256 | P-256 |
ES384 | EC | ES384 | P-384 |
Ed25519 | OKP | EdDSA | Ed25519 |
Encrypted JWTs are not supported.
BTW, if you have the choice, use Ed25519. It is safe and fast.
Why yet another Rust JWT validation lib?
We tried various other Rust JWT libraries, but none worked for us. Problems were complicated APIs, lacking documentation and/or functionality. This is our attempt at doing better :-)
Usage
To validate JWTs, you have to have the issuer's public keys available. Using bbjwt, you can get them either by downloading them from a URL provided by the issuer, or you load them from a local buffer/file.
Download public keys from a URL
See the following example:
use KeyStore;
async
Using public keys from memory
When loading public keys from local file or buffer, you can either load a JWK JSON or a PEM encoded text. JWKs contain all required info to identify the type of key, but for PEM you need to use the function that corresponds to the type of key.
See the following example:
use ;
async
Validating JWTs
JWTs are passed as Base64 encoded strings; for details about this format, see e.g. https://jwt.io.
To validate a JWT, you pass the base64 encoded JWT and a vector of [ValidationStep
]s into [validate_jwt
]. bbjwt provides a convenience function named [default_validations
] to create a vector of default validation steps.
If the JWT is valid, [validate_jwt
] returns all claims that the JWT contains (header and payload).
Example:
use ;
async
Copyright (c) 2022 basebox GmbH, all rights reserved.
License: MIT
Made with ❤️ and Emacs :-)