Axum Integration API (oauth2-passkey-axum)

Overview

The oauth2-passkey-axum crate provides Axum web framework integration for the oauth2-passkey authentication library. It offers ready-to-use routers, middleware, and extractors for OAuth2 and WebAuthn/Passkey authentication.

Full API Documentation: https://docs.rs/oauth2-passkey-axum

Quick Start

use axum::{Router, response::Html};
use oauth2_passkey_axum::{oauth2_passkey_full_router, init};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize authentication
    init().await?;

    // Create application router
    let app: Router = Router::new()
        .route("/", axum::routing::get(|| async { Html("Hello World!") }))
        // Add all authentication routes with a single call
        .merge(oauth2_passkey_full_router());

    // Start server
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;
    axum::serve(listener, app).await?;

    Ok(())
}

Routers

oauth2_passkey_full_router (Recommended)

The unified router that provides all authentication endpoints. This is the recommended way to add authentication to your application.

#![allow(unused)]
fn main() {
use oauth2_passkey_axum::oauth2_passkey_full_router;

let app = Router::new()
    .merge(oauth2_passkey_full_router());
}

This router:

• Nests all auth endpoints under O2P_ROUTE_PREFIX (default: /o2p)
• Automatically includes /.well-known/webauthn when WEBAUTHN_ADDITIONAL_ORIGINS is configured
• Handles single-origin and multi-origin setups seamlessly

Endpoints provided:

See Endpoint Reference for complete details.

oauth2_passkey_router

The auth-only router without the prefix nesting. Use this for custom setups where you need more control.

#![allow(unused)]
fn main() {
use oauth2_passkey_axum::{oauth2_passkey_router, O2P_ROUTE_PREFIX};

let app = Router::new()
    .nest(O2P_ROUTE_PREFIX.as_str(), oauth2_passkey_router());
}

Endpoints provided (relative to mount point):

passkey_well_known_router

Router for the WebAuthn well-known endpoint. Only needed if you use oauth2_passkey_router() directly with a multi-origin setup.

#![allow(unused)]
fn main() {
use oauth2_passkey_axum::{oauth2_passkey_router, passkey_well_known_router, O2P_ROUTE_PREFIX};

let app = Router::new()
    .nest(O2P_ROUTE_PREFIX.as_str(), oauth2_passkey_router())
    .merge(passkey_well_known_router());
}

This creates a /.well-known/webauthn endpoint for WebAuthn relying party configuration. See Multi-Origin Passkey Setup for details.

Note: If you use oauth2_passkey_full_router(), this endpoint is included automatically when needed.

Middleware

Authentication middleware for protecting routes. All middleware functions:

1. Verify valid session cookie
2. For state-changing methods (POST, PUT, DELETE, PATCH), verify CSRF protection
3. Add CSRF token to response headers

is_authenticated_401

Returns HTTP 401 Unauthorized for unauthenticated requests.

#![allow(unused)]
fn main() {
use axum::{Router, middleware::from_fn};
use oauth2_passkey_axum::is_authenticated_401;

let app: Router = Router::new()
    .route("/api/data", axum::routing::get(handler))
    .layer(from_fn(is_authenticated_401));
}

is_authenticated_redirect

Redirects unauthenticated GET requests to login page; returns 401 for other methods.

#![allow(unused)]
fn main() {
use axum::{Router, middleware::from_fn};
use oauth2_passkey_axum::is_authenticated_redirect;

let app: Router = Router::new()
    .route("/dashboard", axum::routing::get(handler))
    .layer(from_fn(is_authenticated_redirect));
}

is_authenticated_user_401

Like is_authenticated_401, but also extracts user data into an Extension<AuthUser>.

#![allow(unused)]
fn main() {
use axum::{Router, middleware::from_fn, extract::Extension};
use oauth2_passkey_axum::{is_authenticated_user_401, AuthUser};

async fn handler(Extension(user): Extension<AuthUser>) -> String {
    format!("Hello, {}", user.account)
}

let app: Router = Router::new()
    .route("/api/profile", axum::routing::get(handler))
    .layer(from_fn(is_authenticated_user_401));
}

is_authenticated_user_redirect

Like is_authenticated_redirect, but also extracts user data into an Extension<AuthUser>.

#![allow(unused)]
fn main() {
use axum::{Router, middleware::from_fn, extract::Extension};
use oauth2_passkey_axum::{is_authenticated_user_redirect, AuthUser};

async fn handler(Extension(user): Extension<AuthUser>) -> String {
    format!("Hello, {}", user.account)
}

let app: Router = Router::new()
    .route("/dashboard", axum::routing::get(handler))
    .layer(from_fn(is_authenticated_user_redirect));
}

Extractors

AuthUser

Axum extractor for authenticated user information. Automatically verifies session and CSRF tokens.

#![allow(unused)]
fn main() {
use axum::routing::get;
use oauth2_passkey_axum::AuthUser;

async fn protected_handler(user: AuthUser) -> String {
    format!("Hello, {}!", user.label)
}

let app: Router = Router::new()
    .route("/protected", get(protected_handler));
}

Fields:

Methods:

• has_admin_privileges() - Returns true if user has admin rights (either is_admin flag or is first user)

Optional Extraction:

AuthUser also implements OptionalFromRequestParts, allowing optional user extraction:

#![allow(unused)]
fn main() {
async fn handler(user: Option<AuthUser>) -> String {
    match user {
        Some(u) => format!("Hello, {}!", u.label),
        None => "Hello, guest!".to_string(),
    }
}
}

URL Constants

Re-exports from oauth2-passkey

The following are re-exported from the core library for convenience:

Example: Protected API Routes

use axum::{Router, routing::{get, post}, middleware::from_fn, Json};
use oauth2_passkey_axum::{
    oauth2_passkey_full_router, is_authenticated_user_401, AuthUser, init
};
use serde::Serialize;

#[derive(Serialize)]
struct UserProfile {
    id: String,
    name: String,
    is_admin: bool,
}

async fn get_profile(user: AuthUser) -> Json<UserProfile> {
    Json(UserProfile {
        id: user.id,
        name: user.label,
        is_admin: user.has_admin_privileges(),
    })
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    init().await?;

    // Protected API routes
    let api_routes = Router::new()
        .route("/profile", get(get_profile))
        .layer(from_fn(is_authenticated_user_401));

    let app = Router::new()
        // Authentication routes (includes /.well-known/webauthn when needed)
        .merge(oauth2_passkey_full_router())
        // Protected API
        .nest("/api", api_routes);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;
    axum::serve(listener, app).await?;

    Ok(())
}

Example: Protected Web Pages with Redirect

#![allow(unused)]
fn main() {
use axum::{Router, routing::get, middleware::from_fn, response::Html};
use oauth2_passkey_axum::{is_authenticated_user_redirect, AuthUser};

async fn dashboard(user: AuthUser) -> Html<String> {
    Html(format!(
        "<h1>Welcome, {}!</h1><p>Your account: {}</p>",
        user.label,
        user.account
    ))
}

let protected_pages = Router::new()
    .route("/dashboard", get(dashboard))
    .layer(from_fn(is_authenticated_user_redirect));
}

Endpoint Reference

Complete list of all endpoints provided by oauth2_passkey_router().

OAuth2 Endpoints (/oauth2)

Passkey Endpoints (/passkey)

User Endpoints (/user)

Admin Endpoints (/admin)

Login history query parameters (for /audit and /user/{user_id}/login_history):

Admin safeguards: The admin API enforces protections to prevent admin lockout:

• Cannot delete or demote the last remaining admin user
• The first user (seq=1) cannot be demoted
• Admin users cannot delete their own account via the admin interface

Theme Endpoints (/themes)

These are optional CSS theme files that override o2p-base.css variables. Set O2P_CUSTOM_CSS_URL to apply a theme. See Themes for details.

Feature Flags

Endpoints marked with * are controlled by feature flags:

API endpoints (/user/info, /user/csrf_token, /user/logout, /user/update, /user/delete, authentication, CRUD operations) are always available regardless of feature flags.

# Disable all built-in UI
oauth2-passkey-axum = { version = "0.3", default-features = false }

# Custom login page, keep account management and admin UI
oauth2-passkey-axum = { version = "0.3", default-features = false, features = ["user-ui", "admin-ui"] }

# Keep admin UI only
oauth2-passkey-axum = { version = "0.3", default-features = false, features = ["login-ui", "admin-ui"] }

Additional Router: passkey_well_known_router()

This router should be merged at the root level (not nested under O2P_ROUTE_PREFIX). Only needed for multi-origin setups. See Multi-Origin Passkey Setup.