To use axum-login, you must implement two primary traits for your user type and your backend:

1. AuthUser: Implemented on your user struct. It requires defining a unique Id type and a session_auth_hash (used for session validation).
2. AuthnBackend: Implemented on your backend struct. It defines how to authenticate credentials and how to get_user via a UserId.

This allows you to use any user type and any backend (Database, LDAP, etc.).

use axum_login::{AuthUser, AuthnBackend, UserId};

#[derive(Clone, Debug)]
struct User;

impl AuthUser for User {
    type Id = i64;

    fn id(&self) -> Self::Id {
        0
    }

    fn session_auth_hash(&self) -> &[u8] {
        &[]
    }
}

#[derive(Clone)]
struct Backend;

impl AuthnBackend for Backend {
    type User = User;
    type Credentials = ();
    type Error = std::convert::Infallible;

    async fn authenticate(
        &self,
        _: Self::Credentials,
    ) -> Result<Option<Self::User>, Self::Error> {
        Ok(Some(User))
    }

    async fn get_user(
        &self,
        _: &UserId<Self>,
    ) -> Result<Option<Self::User>, Self::Error> {
        Ok(Some(User))
    }
}

The Require builder is the primary way to protect routes. You can configure how unauthenticated users are handled (e.g., via RedirectHandler) and customize access logic using .decision().

To use the builder, ensure the require-builder feature is enabled.

Behavior Contract:

• Unauthenticated: If the user is not logged in, the unauthenticated handler is used.
• Unauthorized: If the user is logged in but lacks permissions, the unauthorized handler is used.
• Redirects: Redirect fallbacks preserve existing redirect query parameters or append the configured redirect field. Errors in redirect construction return 500 Internal Server Error.

use axum_login::require::{RedirectHandler, Require};
use axum_login::{AuthUser, AuthnBackend, UserId};

// ... (Implement AuthUser and AuthnBackend as shown above) ...

let require = Require::<Backend>::builder()
    .unauthenticated(RedirectHandler::new().login_url("/login"))
    .build();

When using axum-login middleware, you can customize how the system responds when a user is unauthenticated (not logged in) or unauthorized (insufficient permissions) by providing a ResponseHandler.

There are three main ways to implement a handler:

1. RedirectHandler: Redirects unauthenticated users to a login page, typically appending the current URI as a query parameter so they can be returned to after signing in.
2. SimpleResponseHandler: Returns a static response with a specific status code, body, content type, and custom headers (e.g., returning JSON or plain text).
3. Closures: Any async closure that takes a Request and returns a type implementing IntoResponse can be used as a handler.

// Example using RedirectHandler with RequireBuilder
let require = Require::<Backend>::builder()
    .unauthenticated(
        RedirectHandler::new()
            .login_url("/login")
            .redirect_field("next"),
    )
    .build();

// Example using SimpleResponseHandler with RequireBuilder
let require = Require::<Backend>::builder()
    .unauthenticated(SimpleResponseHandler::text(
        StatusCode::UNAUTHORIZED,
        "Sign in to continue",
    ))
    .build();

The AuthSession struct is a specialized session wrapper used for identifying, authenticating, and authorizing users. It is generic over a type implementing AuthnBackend.

Key workflows:

• Authentication: Use .authenticate(creds) to verify credentials against the backend. It returns Ok(Some(user)) if valid, or Ok(None) if invalid.
• Logging In: Once credentials are verified, use .login(user) to persist the user's identity in the session. This method automatically mitigates session fixation by cycling the session ID if the user was not previously logged in.
• Logging Out: Use .logout() to clear the user from the session and flush the session state.
• Retrieving User: Use .user() to check if a user is currently authenticated in the session.

// Example workflow concept
let user = auth_session.authenticate(credentials).await?;
if let Some(user) = user {
    auth_session.login(&user).await?;
}

let current_user = auth_session.user().await;

The RequireService is a Tower service used to enforce authentication and authorization requirements on incoming requests. It operates by checking for an AuthSession<B> in the request extensions.

Its logic follows this flow:

1. Check Authentication: If no AuthSession is found in the request extensions, it returns an Internal Server Error (via InternalErrorFallback).
2. Evaluate Predicate: If an AuthSession is present, it executes the predicate defined in the Require layer to produce a Decision.
3. Handle Decision:
   • Decision::Allow: The request is forwarded to the inner service. Note that the service will wait for the inner service to be poll_ready before calling it.
   • Decision::Unauthorized: The request is intercepted, and the unauthorized handler defined in the Require layer is executed.
   • Decision::Unauthenticated: The request is intercepted, and the unauthenticated handler defined in the Require layer is executed.

This service ensures that authorization logic is decoupled from your main application handlers.