created_at2023-01-12 11:52:49.515325
updated_at2024-01-30 11:59:42.096694
descriptionA simple to use, well documented JWT validation library, mainly for validating OpenID Connect ID Tokens.



JWT validation library for basebox (and maybe others :-) )

Build Status


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 :-)


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 bbjwt::KeyStore;

async fn main() {

  // bbjwt provides a function to determine the public keyset URL by loading discovery
  // info from the issuer; this is common for OpenID Connect servers.

  // If you are using Keycloak, you can use this convenience function to get the discovery
  // endpoint URL; all you need is the base URL and the realm name:
  let discovery_url = KeyStore::keycloak_discovery_url(
    "https://server.tld", "testing"

  // If you're not using Keycloak, the URL might be different.
  let discovery_url = "https://idp-host.tld/.well-known/discovery";

  // Call IdP's discovery endpoint to query the keyset URL; this is a common feature on
  // OpenID Connect servers.
  let keyset_url = KeyStore::idp_certs_url(discovery_url).await.unwrap();

  // Now we can load the keys into a new KeyStore:
  let keystore = KeyStore::new_from_url(&keyset_url).await.unwrap();

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 bbjwt::{KeyStore, KeyAlgorithm, EcCurve};

async fn main() {
  // Create an empty keystore
  let mut keystore = KeyStore::new().await.unwrap();

  // Load public key from a JWK JSON; see
  let json_key = r#"
    ... abbreviated ...,
  // Add the key

  let pem_key = r#"-----BEGIN PUBLIC KEY-----

  // Load a RSA key from a PEM buffer

  // Load a EC key from a PEM buffer

  // Load EdDSA key from a PEM buffer

  // You can add more keys; in this case, the keys should have an ID and the JWT to be
  // validated should have a "kid" claim. Otherwise, bbjwt uses the first key in the set.

Validating JWTs

JWTs are passed as Base64 encoded strings; for details about this format, see e.g.

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).


use bbjwt::{KeyStore, default_validations, validate_jwt};

async fn main() {
  // Create a keystore; see examples above
  let keystore = KeyStore::new_from_url("https://server.tld/keyset").await.unwrap();

  // Validate a JWT
  let jwt = validate_jwt(
    "<Base64 encoded JWT>",
      // required value for the "iss" claim

  // Read some claims (JWT fields)
  assert_eq!(["nonce"].as_str().unwrap(), "UZ1BSZFvy7jKkj1o9p3r7w");

Copyright (c) 2022 basebox GmbH, all rights reserved.

License: MIT

Made with ❤️ and Emacs :-)

Commit count: 89

cargo fmt