Crate oauth2_passkey_axum 

oauth2-passkey-axum

Axum web framework integration for the oauth2-passkey authentication library.

This crate provides ready-to-use Axum handlers, middleware, and UI components for OAuth2 and passkey authentication in your Axum web applications.

Quick Start

For a complete working example, see the demo-both application which demonstrates both OAuth2 and passkey authentication in a single application.

Features

• Drop-in Axum Integration: Pre-built routers and middleware
• Admin UI: Optional admin interface for user management
• User UI: Authentication pages and flows
• Route Protection: Middleware for protecting routes
• CSRF Protection: Built-in CSRF token handling
• Static Assets: CSS and JavaScript for authentication UI

Basic Usage

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

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

    // Create your application router
    let app: Router = Router::new()
        .route("/", axum::routing::get(|| async { Html("Hello World!") }))
        // Add authentication routes (default: /o2p, configurable via O2P_ROUTE_PREFIX env var)
        .nest(O2P_ROUTE_PREFIX.as_str(), oauth2_passkey_router());
        // .merge(other_routes) // Add your other routes here

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

    Ok(())
}

See the repository documentation and examples for more details.

Structs

AuthUser

Authenticated user information, available as an Axum extractor

CredentialId

Type-safe wrapper for credential identifiers.

CsrfHeaderVerified

Indicates whether the CSRF token was verified via an HTTP header.

CsrfToken

CSRF (Cross-Site Request Forgery) token for request validation.

DbUser

Represents a core user identity in the system

LoginHistoryEntry

A single login history entry

OAuth2Account

Represents an OAuth2 account linked to a user

PasskeyCredential

Stored credential information for a WebAuthn/Passkey.

ProviderInfo

Public information about a single enabled OAuth2 provider.

ProviderUserId

Type-safe wrapper for provider-specific user identifiers.

ProviderView

Human-readable presentation data for an OAuth2 provider.

SessionId

Type-safe wrapper for session identifiers.

UserId

Type-safe wrapper for user identifiers.

Enums

LoginHistoryError

Errors that can occur during login history operations

Statics

O2P_ACCOUNT_URL

URL of the user account management page Default: “/o2p/user/account”

O2P_ADMIN_URL

URL of the admin index page Default: “/o2p/admin/index”

O2P_CUSTOM_CSS_URL

Optional URL for custom CSS to override default styles Example: O2P_CUSTOM_CSS_URL=/static/my-theme.css Users can override CSS Custom Properties in their custom CSS file

O2P_DEFAULT_REDIRECT

Default redirect URL for authenticated-user flows Used when: authenticated users visit login page, logout redirect target in templates Default: “/”

O2P_LOGIN_URL

URL of the login page, used by middleware and AuthUser extractor to redirect unauthenticated users

O2P_ROUTE_PREFIX

Route prefix for all oauth2_passkey endpoints

Functions

cleanup_old_login_history

Delete login history entries older than O2P_LOGIN_HISTORY_RETENTION_DAYS.

custom_css_vars_block

Build the inline :root { ... } CSS block injecting --o2p-custom{N} / --o2p-custom{N}-hover variables for every enabled generic OIDC slot.

delete_oauth2_account_admin

Deletes an OAuth2 account as an administrator.

delete_passkey_credential_admin

Deletes a passkey credential as an administrator.

delete_user_account_admin

Completely deletes a user account as an administrator.

enabled_provider_views

Returns ProviderView for every currently enabled OAuth2 provider, in stable display order (Google first, then optional providers).

enabled_providers

Returns UI info for every currently enabled OAuth2 provider, in stable display order (Google first, then enabled generic OIDC slots Custom1..Custom8 in order).

get_all_users

Retrieves a list of all users in the system.

get_user

Retrieves a specific user by their ID.

init

Initialize the authentication system

is_authenticated_401

Authentication middleware that returns HTTP 401 for unauthenticated requests

is_authenticated_redirect

Authentication middleware that redirects unauthenticated requests to login page

is_authenticated_user_401

Authentication middleware that provides user data and returns HTTP 401 for unauthenticated requests

is_authenticated_user_redirect

Authentication middleware that provides user data and redirects unauthenticated requests

is_provider_enabled

Returns true if the named OAuth2 provider is configured and enabled.

list_accounts_core

Lists all OAuth2 accounts associated with a user.

list_credentials_core

Core function that handles the business logic of listing passkey credentials

oauth2_passkey_full_router

Creates a complete router with all authentication endpoints

oauth2_passkey_router

Create a combined router for all authentication endpoints

passkey_well_known_router

Creates a router for the WebAuthn well-known endpoint Creates a router for WebAuthn/.well-known endpoints

spawn_login_history_cleanup

Spawn a background task that runs cleanup_old_login_history every 24 hours.

update_user_admin_status

Updates a user’s administrative status.