Authentication and Two-Factor Auth in Avalúo Vehicular

Avalúo Vehicular uses Laravel Fortify as its authentication backend. Fortify is a headless authentication library — it provides the routes and controller logic for login, logout, password resets, email verification, and two-factor authentication, but it renders no views of its own. The React 19 frontend, served through Inertia.js, supplies every page the user sees. Authentication is entirely session-based: after a successful login Fortify issues an encrypted PHP session cookie, and every subsequent request is authenticated by reading that cookie. There are no API tokens, no JWT, and no Bearer headers — the same session cookie that drives the Inertia.js SPA is the authentication credential.

This is session-based authentication, not token-based. If you are building a standalone mobile app or a separate API client, you will need to implement token-based auth (e.g. Laravel Sanctum) separately. The current setup is optimised for the integrated Inertia.js SPA, where the frontend and backend share the same origin and CSRF context.

Authentication Features

Fortify is configured in config/fortify.php with the web guard and email as the username field. After a successful login, the user is redirected to /dashboard.

Active Routes

The following authentication routes are registered in routes/auth.php:

Method	Path	Name	Description
`GET`	`/login`	`login`	Renders the Inertia login page
`POST`	`/login`	`login.store`	Authenticates credentials, starts session
`POST`	`/logout`	`logout`	Destroys the session and redirects to `/login`
`GET`	`/forgot-password`	`password.request`	Renders the forgot-password page
`POST`	`/forgot-password`	`password.email`	Sends a password-reset link by email
`GET`	`/reset-password/{token}`	`password.reset`	Renders the reset-password form
`POST`	`/reset-password`	`password.store`	Validates token and updates the password
`GET`	`/verify-email`	`verification.notice`	Prompts the user to verify their email address
`GET`	`/verify-email/{id}/{hash}`	`verification.verify`	Processes the signed verification link
`POST`	`/email/verification-notification`	`verification.send`	Re-sends the verification email (throttled to 6/min)

Registration

Self-registration routes are present in routes/auth.php but are commented out by default. New accounts are created by an administrator through the user management panel. To re-enable public registration, uncomment the two register route definitions in routes/auth.php and add Features::registration() to the features array in config/fortify.php.

Two-Factor Authentication (2FA)

Avalúo Vehicular ships with TOTP-based two-factor authentication powered by Fortify. 2FA is opt-in per user — enabling it for one account has no effect on others.

How It Works

When 2FA is enabled for an account, Fortify inserts an additional challenge step between credential verification and session creation. The user must supply a valid TOTP code from their authenticator app (or a one-time recovery code) before gaining access. The challenge page is rendered by the React component at resources/js/pages/auth/two-factor-challenge.tsx, registered in FortifyServiceProvider:

Fortify::twoFactorChallengeView(
    fn () => Inertia::render('auth/two-factor-challenge')
);

A rate limiter (two-factor) caps failed 2FA attempts at 5 per minute per session to prevent brute-force attacks:

RateLimiter::for('two-factor', function (Request $request) {
    return Limit::perMinute(5)->by($request->session()->get('login.id'));
});

Enabling 2FA as a User

Log in and navigate to Settings → Security.
Click Enable Two-Factor Authentication.
Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.).
Enter a valid TOTP code to confirm the setup — this writes two_factor_confirmed_at to the database and activates the feature.
Save the displayed recovery codes somewhere secure — they are the only way to access the account if the authenticator app is lost.

Database Columns

The 2FA feature adds three columns to the users table via the 2025_08_26_100418_add_two_factor_columns_to_users_table migration:

Column	Type	Description
`two_factor_secret`	`text`, nullable	The encrypted TOTP secret key shared with the authenticator app
`two_factor_recovery_codes`	`text`, nullable	A JSON array of hashed single-use recovery codes
`two_factor_confirmed_at`	`timestamp`, nullable	The moment 2FA was confirmed; `null` means setup was started but not completed

The secret and recovery codes are listed in the User model’s $hidden array, ensuring they are never exposed in JSON responses. The two_factor_confirmed_at timestamp is intentionally excluded from $hidden so the frontend can determine whether 2FA setup has been completed:

protected $hidden = [
    'password',
    'two_factor_secret',
    'two_factor_recovery_codes',
    'remember_token',
];

The User model also uses the TwoFactorAuthenticatable trait from Fortify, which provides the twoFactorQrCodeSvg(), twoFactorQrCodeUrl(), and recoveryCodes() helper methods:

use Laravel\Fortify\TwoFactorAuthenticatable;

class User extends Authenticatable
{
    use HasFactory, HasRoles, Notifiable, TwoFactorAuthenticatable;
    // ...
}

Fortify Features Configuration

Only twoFactorAuthentication is enabled in config/fortify.php. All other optional Fortify features are commented out, as Avalúo Vehicular manages registration, profile updates, and password changes through its own controllers:

'features' => [
    // Features::registration(),
    // Features::resetPasswords(),
    // Features::emailVerification(),
    // Features::updateProfileInformation(),
    // Features::updatePasswords(),
    Features::twoFactorAuthentication([
        'confirm'         => true,  // user must confirm a TOTP code to activate
        'confirmPassword' => true,  // user must re-enter password before managing 2FA
    ]),
],

Enable 2FA for all administrator accounts before going to production. Because Avalúo Vehicular manages vehicle appraisal records that may be shared externally via signed tokens, a compromised admin account can expose sensitive client data. Require 2FA for all users with elevated roles using a middleware gate or a Fortify feature flag at the role level.

Session Configuration

Sessions are stored in the sessions database table (created by the first migration) and configured in .env:

SESSION_DRIVER=database
SESSION_LIFETIME=120   # minutes of inactivity before expiry
SESSION_ENCRYPT=false
SESSION_PATH=/
SESSION_DOMAIN=null

The sessions table records the user ID, IP address, user agent, and last-activity timestamp for every active session, enabling administrators to view and terminate concurrent sessions from the database.

Security Features

CSRF Protection

Laravel automatically issues a CSRF token with every session and validates it on all state-changing requests (POST, PUT, PATCH, DELETE). Inertia.js automatically reads the XSRF-TOKEN cookie and injects it into every request header — no manual token handling is required in React components.

Password Hashing

All passwords are hashed with bcrypt before being stored. The work factor is controlled by:

BCRYPT_ROUNDS=12

A value of 12 is the Laravel default and provides a strong balance between security and performance on modern hardware (≈ 250 ms per hash). Do not lower this below 10 in production.

Email Verification

The email_verified_at column on the users table records when a user verified their email address. Protected routes apply the verified middleware, which redirects unverified users to /verify-email. The VerifyEmailController processes signed verification URLs and sets email_verified_at on success.

Route Middleware

All application routes that require an authenticated, verified user apply both middleware guards:

Route::middleware(['auth', 'verified'])->group(function () {
    // Dashboard, appraisal management, etc.
});

Authorization Policies

Beyond authentication, the AuthServiceProvider registers two Eloquent policies:

protected $policies = [
    Vehiculo::class => VehiculoPolicy::class,
    User::class     => UsuarioPolicy::class,
];

These policies, combined with the Spatie role/permission system (HasRoles trait on User), ensure that evaluators can only access vehicles and appraisals they own or have been explicitly granted access to.

Introducción

Instalación

Configuración

Características

Administración

Authentication and Two-Factor Auth in Avalúo Vehicular

Authentication Features

Active Routes

Registration

Two-Factor Authentication (2FA)

How It Works

Enabling 2FA as a User

Database Columns

Fortify Features Configuration

Session Configuration

Security Features

CSRF Protection

Password Hashing

Email Verification

Route Middleware

Authorization Policies

Build docs developers (and LLMs) love

Introducción

Instalación

Configuración

Características

Administración

Documentation Index

​Authentication Features

​Active Routes

​Registration

​Two-Factor Authentication (2FA)

​How It Works

​Enabling 2FA as a User

​Database Columns

​Fortify Features Configuration

​Session Configuration

​Security Features

​CSRF Protection

​Password Hashing

​Email Verification

​Route Middleware

​Authorization Policies

Build docs developers (and LLMs) love

Authentication Features

Active Routes

Registration

Two-Factor Authentication (2FA)

How It Works

Enabling 2FA as a User

Database Columns

Fortify Features Configuration

Session Configuration

Security Features

CSRF Protection

Password Hashing

Email Verification

Route Middleware

Authorization Policies