axum-jose

Lightweight authorization middleware for axum, following JOSE (JSON Object Signing and Encryption) standards.

Overview

Add JWT-based authorization to your axum applications with a simple, tower-compatible middleware layer that integrates seamlessly with OpenID Connect and OAuth2 providers.

More broadly speaking, this crate follows the JOSE (JSON Object Signing and Encryption) framework which is an umbrella for specifications that form the foundation of modern authentication and authorization protocols. Core specifications include e.g. JSON Web Signatures (JWS), JSON Web Encryption (JWE), JSON Web Algorithms (JWA), JSON Web Keys (JWK), which provide the building blocks for JSON Web Tokens (JWT).

Features

JWT Validation: Transparently extract JWTs from Authorization headers and validate them against JWK sets to authorize incoming requests.
Caching: Use caching to minimize latency and avoid fetching JWK sets from authorization servers on every request.
Rate Limiting: Prevent running into your identity provider's rate limits when fetching JWKs by configuring client-side rate limiting.

Quickstart

use axum::{routing::get, Router};
use axum_jose::{AuthorizationLayer, RemoteJwkSet};
use std::num::NonZero;
use std::time::Duration;
use url::Url;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure a `RemoteJwkSet` to fetch the JWK set e.g. from your OpenID
    // Connect provider which typically exposes JWK sets at a
    // `.well-known/jwks.json` endpoint
    let remote_jwk_set = RemoteJwkSet::builder(Url::parse(
        "https://your.oidc.provider/.well-known/jwks.json",
    )?)
    // Use caching to avoid fetching the JWK set on every request
    .with_cache(Duration::from_secs(300))
    // Configure rate limiting to avoid hitting provider limits
    .with_rate_limit(NonZero::new(10).unwrap(), Duration::from_secs(60))
    .build();

    // Create an authorization layer using the remote JWK set to validate JWTs.
    let authorization_layer = AuthorizationLayer::with_remote_jwk_set(
        remote_jwk_set,
        Url::parse("https://your.jwt.issuer")?,
        "your.jwt.audience".to_string(),
    );

    // Protect your `axum` routes with the authorization layer.
    let router = Router::new()
        .route("/protected", get(|| async { "Hello, authorized user!" }))
        .layer(authorization_layer);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
    axum::serve(listener, router).await?;
    Ok(())
}

See the documentation for more examples and configuration options.

Related Projects

At the time of writing, the ecosystem around JOSE, OpenID Connect, and OAuth2 for axum and Rust is not yet as mature as in other languages and web frameworks. There is no clear best practice for implementing authorization for axum-based APIs but a number of crates, similar to this one, exist. To name a few:

License