Authentication & JWT

Relevant source files

The following files were used as context for generating this wiki page:

• src/auth/jwt.rs
• docs-site/content/blog/hello-world.md
• docs-site/content/blog/frontend-website.md
• docs-site/translations/tour-fr.md
• docs-site/config.toml

The Loco framework provides a robust, "batteries-included" authentication system inspired by established patterns like Rails' devise. It leverages JSON Web Tokens (JWT) for stateless authentication, enabling secure communication between clients and the server. This system is integrated into the core framework and available out-of-the-box in starters like the SaaS template.

The authentication logic encompasses user registration, login, and identity verification. It utilizes secure password hashing and JWT-based claims to manage user sessions and permissions.

Sources: docs-site/content/blog/hello-world.md:27, docs-site/translations/tour-fr.md:104

Core Components

JWT Management

Loco uses the jsonwebtoken crate to handle the creation and validation of tokens. The primary interface is the JWT struct, which manages the secret key and the algorithm used for signing (defaulting to HS512).

The system defines a UserClaims structure which holds the Public ID (pid) of the user, an expiration timestamp (exp), and a flexible map for custom claims.

Sources: src/auth/jwt.rs:17-50

Authentication Flow

When a user logs in, the server validates their credentials and generates a JWT. This token is then passed by the client in subsequent requests via the Authorization: Bearer <TOKEN> header.

The authentication state includes information such as whether the user is verified (is_verified) and their public identifier (pid).

Sources: docs-site/translations/tour-fr.md:118-144, src/auth/jwt.rs:65-75

API Implementation

Auth Controller Endpoints

The standard SaaS template provides a set of pre-configured authentication routes. These are typically prefixed under /api/auth.

Endpoint	Method	Description
/api/auth/register	POST	Creates a new user and sends verification email.
/api/auth/login	POST	Validates credentials and returns a JWT.
/api/auth/current	GET	Returns the currently authenticated user's profile.

Sources: docs-site/translations/tour-fr.md:107-144

Request Extraction

In Loco controllers, authentication is handled via extractors. The auth middleware can be injected directly into function signatures to enforce authentication and access the decoded JWT claims.

async fn current(
    auth: middleware::auth::Auth,
    State(ctx): State<AppContext>,
) -> Result<Response> {
    let user = users::Model::find_by_pid(&ctx.db, &auth.claims.pid).await?;
    format::json(CurrentResponse::new(&user))
}

Sources: docs-site/content/blog/hello-world.md:9-15

Configuration and Security

The JWT system is configured via the application environment files (e.g., config/development.yaml).

Feature	Default/Value	Source
Algorithm	HS512	src/auth/jwt.rs:14
Token Format	Bearer <JWT>	docs-site/translations/tour-fr.md:144
Token Validation	Expiration + Secret	src/auth/jwt.rs:88

Security Measures

1. Password Hashing: Passwords are not stored in plain text.
2. Registration Privacy: If a user is already registered, the system returns a 200 OK status without disclosing whether the account exists, preventing email enumeration.
3. Leeway: The JWT validator uses a leeway of 0 by default to ensure strict expiration enforcement.

Sources: src/auth/jwt.rs:89, docs-site/translations/tour-fr.md:115-118

Summary

Authentication in Loco is designed for the "one-person framework" philosophy, providing a secure, ready-to-use JWT implementation. It bridges the gap between low-level token management (via src/auth/jwt.rs) and high-level developer ergonomics (via controllers and extractors), allowing developers to focus on business logic while maintaining robust security standards.