jsonwebtoken

jsonwebtoken is a Rust library for encoding and decoding JSON Web Tokens (JWTs), covering the full range of common signing algorithms — HMAC (HS256/384/512), RSA (RS/PS 256/384/512), and elliptic-curve (ES256/384, EdDSA) — with claims modeled as ordinary strongly-typed Rust structs via serde, rather than loosely-typed maps.

A distinguishing design choice is its pluggable crypto backend: consumers select either the aws_lc_rs or rust_crypto feature (or supply their own CryptoProvider), letting the library be used in environments with different cryptography requirements — including FIPS-adjacent deployments — without forking the crate itself. It also includes JWK (JSON Web Key) support for working with key sets published by identity providers.

What You Get

• encode()/decode() functions operating on any Serialize/Deserialize claims struct instead of untyped JSON maps
• Support for HS256/384/512, RS256/384/512, PS256/384/512, ES256/384, and EdDSA signing algorithms
• EncodingKey/DecodingKey types for loading keys from PEM, DER, secrets, or raw components
• A Validation struct for configuring expiry (exp), audience, issuer, and other standard-claim checks during decode
• JWK (jwk.rs) support for parsing and working with published JSON Web Key Sets from identity providers
• Swappable crypto backends (aws_lc_rs or rust_crypto feature, or a caller-supplied CryptoProvider) instead of one hardcoded implementation

Common Use Cases

• Issuing and validating access/refresh tokens for a Rust web API’s authentication layer
• Verifying tokens issued by external identity providers (Auth0, Okta, AWS Cognito) using their published JWKS
• Building service-to-service auth where tokens carry strongly-typed custom claims (roles, tenant IDs, scopes)
• Deploying in regulated environments that require a specific cryptography backend (e.g. FIPS-validated) via the pluggable CryptoProvider
• Signing and verifying tokens with asymmetric keys (RSA/EC) for scenarios where the issuer and verifier are different services

Under The Hood

Architecture — The crate is organized around a small set of focused modules: encoding.rs/decoding.rs implement the top-level encode/decode entry points, header.rs models the JWT header (algorithm + type), validation.rs (~850 lines) implements claim validation (expiry, audience, issuer, leeway), jwk.rs (~850 lines) implements JSON Web Key parsing, and crypto/ plus pem/ house the per-algorithm signing/verification implementations and PEM key parsing. algorithms.rs defines the Algorithm enum that ties a JWT header’s alg field to the correct crypto backend call.

Tech Stack — Pure Rust (edition 2024, MSRV 1.88), built on serde/serde_json for claims serialization, base64 for JWT segment encoding, and the signature crate as a common trait for pluggable signing backends. Rather than hardcoding one crypto library, it depends on either aws_lc_rs or rust_crypto behind a Cargo feature flag, or accepts a caller-supplied CryptoProvider implementing the signature trait — a design that decouples the JWT logic from any single cryptography implementation.

Code Quality — Tests are organized per-algorithm-family under tests/ (hmac.rs, rsa/, ecdsa/, eddsa/, plus a dangerous.rs suite explicitly testing insecure/edge-case configurations like alg: none rejection), with benches/ for performance regression tracking. The crate is widely depended upon (150M+ cumulative downloads) and has a documented CHANGELOG tracking breaking changes across major versions, reflecting the care warranted by a security-sensitive library.

API Design — encode(&header, &claims, &encoding_key) and decode::<Claims>(&token, &decoding_key, &validation) are the only two calls most consumers need, with claims expressed as ordinary Rust structs deriving Serialize/Deserialize rather than stringly-typed maps — misspelled or missing claim fields become compile errors instead of runtime surprises. The Validation builder pattern for configuring expected audience/issuer/leeway keeps common security checks explicit and discoverable rather than buried in decode-time flags.