Laravel Fortify e gli starter kit

Il design interno di Laravel Fortify, il backend di autenticazione indipendente dal frontend. Perché è usato negli starter kit attuali, configurazione di FortifyServiceProvider, attivazione di 2FA e passkey.

​

Cos’è Fortify

Laravel Fortify è un’implementazione backend di autenticazione indipendente dal frontend. Fornisce tutte le rotte e i controller necessari per login, registrazione, reset della password, verifica email, 2FA e passkey.

Fortify non ha una UI. Funziona quando starter kit o UI personalizzate inviano richieste alle sue rotte.

Il concetto chiave del design è “indipendente dal frontend”. Puoi riutilizzare lo stesso backend di autenticazione con Blade, Inertia (React/Vue/Svelte) o API. È il motivo per cui Fortify è tuttora in uso da anni.

​

Storia: da Jetstream agli starter kit attuali

​

Perché Fortify è usato anche negli starter kit attuali

Inizialmente gli starter kit React/Vue erano implementati senza Fortify. Ma quando è stato necessario supportare l’autenticazione a due fattori (2FA), Fortify è stato adottato così com’era, portando l’intera autenticazione a basarsi su Fortify.

Essendo progettato “frontend-agnostic”, Fortify va d’accordo con gli starter kit basati su Inertia ed è ancora oggi in uso.

Fortify è attualmente il pacchetto ufficiale di autenticazione di Laravel usato da più tempo. Dal debutto nel 2020, tra Jetstream e gli starter kit attuali ha continuato a cambiare forma restando in servizio.

​

Configurazione degli starter kit attuali

Negli starter kit React/Vue, Fortify è configurato nei seguenti file.

• app/Providers/FortifyServiceProvider.php — registrazione di view, action e rate limit
• config/fortify.php — funzionalità abilitate e impostazioni di autenticazione

​

Impostazioni principali di config/fortify.php

use Laravel\Fortify\Features;

return [
    'guard'    => 'web',
    'username' => 'email',
    'home'     => '/dashboard',

    'limiters' => [
        'login'      => 'login',
        'two-factor' => 'two-factor',
    ],

    'features' => [
        Features::registration(),
        Features::resetPasswords(),
        Features::emailVerification(),
        Features::twoFactorAuthentication([
            'confirm'         => true,
            'confirmPassword' => true,
        ]),
    ],
];

Negli starter kit le passkey (Features::passkeys()) non sono abilitate di default. Per abilitarle le aggiungi all’array features.

​

Configurazione di FortifyServiceProvider

Il FortifyServiceProvider degli starter kit ha tre ruoli.

​

1. Configurazione delle action

private function configureActions(): void
{
    Fortify::resetUserPasswordsUsing(ResetUserPassword::class);
    Fortify::createUsersUsing(CreateNewUser::class);
}

Le classi in app/Actions/Fortify/ personalizzano la logica di creazione utente e reset password. Qui sono concentrate validazione e hashing.

​

2. Configurazione delle view

private function configureViews(): void
{
    Fortify::loginView(fn (Request $request) => Inertia::render('auth/login', [
        'canResetPassword' => Features::enabled(Features::resetPasswords()),
        'canRegister'      => Features::enabled(Features::registration()),
        'status'           => $request->session()->get('status'),
    ]));

    Fortify::resetPasswordView(fn (Request $request) => Inertia::render('auth/reset-password', [
        'email' => $request->email,
        'token' => $request->route('token'),
    ]));

    Fortify::requestPasswordResetLinkView(
        fn (Request $request) => Inertia::render('auth/forgot-password', [
            'status' => $request->session()->get('status'),
        ])
    );

    Fortify::verifyEmailView(
        fn (Request $request) => Inertia::render('auth/verify-email', [
            'status' => $request->session()->get('status'),
        ])
    );

    Fortify::registerView(fn () => Inertia::render('auth/register'));

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

    Fortify::confirmPasswordView(fn () => Inertia::render('auth/confirm-password'));
}

Ogni view method riceve una closure che restituisce un componente Inertia. Il punto chiave è controllare i feature flag con Features::enabled() e passarli alla view.

In un’app Blade, al posto di Inertia::render(...) restituisci view('auth.login'). Cambiando frontend basta modificare solo FortifyServiceProvider: la logica di autenticazione non cambia.

​

3. Configurazione del rate limiting

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

    RateLimiter::for('login', function (Request $request) {
        $throttleKey = Str::transliterate(
            Str::lower($request->input(Fortify::username())) . '|' . $request->ip()
        );

        return Limit::perMinute(5)->by($throttleKey);
    });
}

• Limiter login: limita per combinazione email + indirizzo IP (protezione da brute force)
• Limiter two-factor: limita per ID del tentativo di login in sessione

Le chiavi registrate in RateLimiter::for() devono coincidere con quelle di limiters in config/fortify.php.

​

Funzionalità principali e rotte registrate

Le rotte principali registrate da Fortify, per funzionalità.

Funzionalità	Metodo	Rotta
Login	GET	/login
Login	POST	/login
Logout	POST	/logout
Registrazione	GET	/register
Registrazione	POST	/register
Richiesta reset password	GET / POST	/forgot-password
Reset password	GET / POST	/reset-password
Verifica email	GET	/email/verify
Invio nuovo link di verifica	POST	/email/verification-notification
Conferma password	GET / POST	/user/confirm-password
Abilitare 2FA	POST	/user/two-factor-authentication
Challenge 2FA	GET / POST	/two-factor-challenge
Login con passkey	GET / POST	/passkeys/login
Gestione passkey	GET / POST / DELETE	/user/passkeys

Con php artisan route:list --name=fortify o semplicemente php artisan route:list verifichi le rotte effettivamente registrate.

​

Autenticazione a due fattori (2FA)

Negli starter kit Features::twoFactorAuthentication() è abilitata. Sia confirm che confirmPassword sono impostati a true.

Opzione	Significato
confirm	Richiede conferma con codice dopo l’abilitazione
confirmPassword	Richiede conferma password prima delle modifiche alle impostazioni 2FA

Dalla schermata di configurazione 2FA l’utente può:

1. Abilitare 2FA

   Invia una POST a /user/two-factor-authentication. In caso di successo, la sessione ottiene lo status two-factor-authentication-enabled.

2. Vedere il QR code

   Con una GET a /user/two-factor-qr-code ottieni l’SVG del QR code da scansionare con l’app di autenticazione.

3. Confermare con il codice di autenticazione

   Invia il codice via POST a /user/confirmed-two-factor-authentication per completare l’impostazione.

4. Salvare i codici di recupero

   Con una GET a /user/two-factor-recovery-codes ottieni i codici di recupero: salvali in un luogo sicuro.

​

Passkey

Le passkey sono state aggiunte a Fortify di recente. Sono un’autenticazione senza password basata su WebAuthn e supportano Face ID, Touch ID, Windows Hello e chiavi hardware.

​

Abilitazione

Aggiungi la voce all’array features di config/fortify.php.

'features' => [
    Features::registration(),
    Features::resetPasswords(),
    Features::emailVerification(),
    Features::twoFactorAuthentication([
        'confirm'         => true,
        'confirmPassword' => true,
    ]),
    Features::passkeys([
        'confirmPassword' => true,
    ]),
],

Poi aggiungi al modello User il contract PasskeyUser e il trait PasskeyAuthenticatable.

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Fortify\Contracts\PasskeyUser;
use Laravel\Fortify\PasskeyAuthenticatable;

class User extends Authenticatable implements PasskeyUser
{
    use PasskeyAuthenticatable;
}

Le impostazioni WebAuthn si gestiscono con la chiave passkeys di config/fortify.php.

'passkeys' => [
    'relying_party_id'  => parse_url(config('app.url'), PHP_URL_HOST),
    'allowed_origins'   => [config('app.url')],
    'user_handle_secret' => config('app.key'),
    'timeout'           => 60000,
],

Le passkey di Fortify avvolgono internamente il pacchetto Composer laravel/passkeys. Non è necessario pubblicare il file di configurazione di laravel/passkeys: prevale la chiave passkeys di config/fortify.php.

Per l’implementazione dettagliata delle passkey (client JS @laravel/passkeys, helper React/Vue/Svelte, ecc.) consulta anche Analisi iniziale delle passkey.

​

Pagine correlate

Guard di autenticazione personalizzato

Come creare un guard di autenticazione personalizzato implementando le interfacce Guard e StatefulGuard.

Documentazione ufficiale: Laravel Fortify

Per l’installazione, tutte le funzionalità e le personalizzazioni consulta la documentazione ufficiale.