How maxcountryman/axum-login works
Project type and purpose
• This is primarily a library crate (axum-login/) exposing middleware, extractors, and traits to handle user identification, authentication, and authorization in Axum-based servers.
• The examples/ directory holds reference applications (full-stack web servers) that use the crate to demonstrate common use cases (OAuth2, permissions, SQLite backends, etc.).
File structure
• Top-level
• Cargo.toml, src/ (lib code), tests/ (integration tests)
• .github/workflows/rust.yml for CI
• Library modules in axum-login/src/:
• backend.rs – trait definitions (AuthnBackend, AuthzBackend)
• extract.rs – extractors (AuthSession)
• middleware.rs – middleware wrappers (login_required, permission_required)
• service.rs – high-level service interfaces
• session.rs – session management (powered by tower-sessions)
• Examples (each a standalone binary) under examples/…:
• Config (.env.example), database migrations
• src/main.rs, plus modules for users, web (routes, handlers, template rendering)
Key insights from README
• The library is built as Tower middleware for Axum.
• It supports pluggable backends (AuthnBackend for authentication, AuthzBackend for authorization) and session stores via tower-sessions.
• Examples illustrate integration with SQL (SQLite, Postgres), OAuth2, and custom permission schemes.
Main components
a. Client (Web browser or API consumer)
b. HTTP Server (Axum)
c. Middleware Layer (axum-login)
• AuthSession extractor
• login_required / permission_required
d. Authentication Backend (impl of AuthnBackend)
e. Authorization Backend (impl of AuthzBackend)
f. Session Store (tower-sessions: cookie store, Redis, etc.)
g. Data Store (SQL database—SQLite/Postgres—or external directory)
h. Handler Logic (business-specific routes / template rendering)
i. External OAuth Provider (only in oauth2 example)
Relationships & data flows
1. Client → HTTP Request → Axum Router
2. Axum passes request into axum-login middleware
• Load session from cookie or store
• If protected, enforce login or permission checks via extractor
3. Middleware invokes AuthnBackend to validate user credentials or session
4. On success, AuthSession injected into Handler
5. Handler may query the Data Store (users table, groups, permissions) via async DB client
6. On routes using OAuth, Handler redirects to external provider, exchanges code, calls AuthnBackend
7. Responses flow back through middleware → Axum → Client
Architectural patterns & principles
• Middleware pipeline (layered request processing)
• Trait-based abstraction for backends (pluggable implementations)
• Separation of concerns: session management vs. authentication logic vs. handler code
• Dependency injection: backends passed into the Router at startup
Technologies & frameworks
• Rust, Tokio (async)
• Axum (web framework)
• Tower & Tower-Sessions (middleware & session management)
• SQLx or Diesel (DB access in examples)
• Askama / Handlebars / Tera (template engines in examples)
Essential elements to capture
• The flow of an HTTP request through Axum → axum-login middleware → Handler → DB
• How and where session state is stored/retrieved
• Points of extension: where a user plugs in their own AuthnBackend / AuthzBackend