Expand description
OAuth 2.0 resource protection and browser login for Axum applications.
Choose an entry point based on what your application needs:
| Task | Entry point | Start here |
|---|---|---|
| Protect existing API routes | ValidatorLayer | Authorization guide |
| Mount resources with public discovery metadata | ResourceRouter | First resource tutorial |
| Sign users in and maintain browser sessions | login::LoginLayer | Browser 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
- Learn: protect a resource or add browser login.
- Configure: authorization, resources, routing and proxies, or observability.
- Look up: the API modules below, response behavior, and metrics.
- Understand: authentication and resource identity.
- Upgrade: migration notes.
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.
| Feature | Default | Purpose |
|---|---|---|
resource | Yes | Validation, authorization, token extractors and protected-resource metadata |
default-jws-verifier-platform | Yes | Default verifier for enabled resource/login dependencies; enables neither subsystem itself |
login | No | Browser login, session loading/refresh and logout; independent of resource |
metrics | No | Adapter 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§
- extensions
loginorresource - Request-extension types passed between the auth middleware layers.
- extractors
resource - Axum extractors for validated access tokens.
- layers
resource - Tower
Layer/Servicemiddleware: access-token validation and authorization enforcement. - login
login - OAuth 2.0 browser login and session middleware for Axum.
- prelude
- Common traits and types for working with
huskarl-axum. - resource_
metadata resource - RFC 9728 Protected Resource Metadata endpoint support.
- resource_
router resource - Server-level assembly of independently authenticated resources and metadata.
- response
resource - Error/challenge response types for the auth middleware.