Skip to main content

Crate huskarl_axum

Crate huskarl_axum 

Source
Expand description

OAuth 2.0 resource protection and browser login for Axum applications.

Choose an entry point based on what your application needs:

TaskEntry pointStart here
Protect existing API routesValidatorLayerAuthorization guide
Mount resources with public discovery metadataResourceRouterFirst resource tutorial
Sign users in and maintain browser sessionslogin::LoginLayerBrowser login tutorial

Resource protection supports JWT and opaque access tokens, scopes, audiences, custom authorization, DPoP and mTLS binding, and RFC 9728 discovery through huskarl-resource-server. Browser login uses the huskarl-login engine. A browser session and a validated access token are independent credentials.

§Documentation

The example index links runnable applications and their inputs. For shared login policy, storage, lifetime and refresh behavior, see the huskarl-login documentation.

§Cargo features

Resource protection and the default verifier platform are enabled by default. Login and metrics are opt-in. Rust 1.92 or later is required.

FeatureDefaultPurpose
resourceYesValidation, authorization, token extractors and protected-resource metadata
default-jws-verifier-platformYesDefault verifier for enabled resource/login dependencies; enables neither subsystem itself
loginNoBrowser login, session loading/refresh and logout; independent of resource
metricsNoAdapter counters and shared metrics support; enables neither subsystem itself
# Resource server.
huskarl-axum = "0.1"

For browser login without resource support, use this declaration instead:

huskarl-axum = { version = "0.1", default-features = false, features = ["login", "default-jws-verifier-platform"] }

To supply your own verifier platform, disable defaults and enable the needed subsystem (resource, login, or both). Configure that subsystem’s validator or grant with your verifier. Cargo features are additive: another dependency can still enable the underlying default platform feature.

§Protect existing routes

Given a configured access-token validator, use ValidatorLayer::authenticated to require a token. The layer handles validation and enforcement in the correct order:

use axum::{Router, routing::get};
use huskarl_axum::{layers::ValidatorLayer, resource_server::validator::{
    AccessTokenValidator, metadata::ProvideValidatorMetadata,
}};

fn protected_routes<V>(validator: V) -> Router
where
    V: AccessTokenValidator + ProvideValidatorMetadata + 'static,
    V::Claims: 'static,
{
    let auth = ValidatorLayer::builder().validator(validator).build();
    Router::new()
        .route("/private", get(|| async { "authenticated" }))
        .layer(auth.authenticated())
}

The handler runs only after successful authentication; a missing token returns 401 with a challenge. ValidatorLayer alone allows absent tokens, but rejects invalid presented tokens. Handlers can read claims with ValidatedToken<C>; optional extraction does not bypass validation failures.

For discovery and resource audience binding, start with ResourceRouter. The first resource tutorial includes validator setup, dependencies, a listener and verification requests.

§Browser sessions

login::LoginLayer combines callback/logout handling, session loading and an authentication gate. Use its component layers for mixed public/protected routes; the login module includes checked composition examples. login::LoginSession reads a loaded session, and login::SessionTermination requests logout of the current application session.

Follow the browser login tutorial for provider registration, cookie keys and a runnable server.

Re-exports§

pub use huskarl_resource_server as resource_server;resource

Modules§

extensionslogin or resource
Request-extension types passed between the auth middleware layers.
extractorsresource
Axum extractors for validated access tokens.
layersresource
Tower Layer/Service middleware: access-token validation and authorization enforcement.
loginlogin
OAuth 2.0 browser login and session middleware for Axum.
prelude
Common traits and types for working with huskarl-axum.
resource_metadataresource
RFC 9728 Protected Resource Metadata endpoint support.
resource_routerresource
Server-level assembly of independently authenticated resources and metadata.
responseresource
Error/challenge response types for the auth middleware.