Laravel Sanctum e Passport — Quale Scegliere per Autenticare API SPA e Mobile (con Esempi Concreti)

Hai un'app Vue o React che deve parlare con Laravel. Oppure un'app mobile che chiama le tue API. Il primo muro che incontri? L'autenticazione. Non basta mandare una password: devi proteggere ogni endpoint, gestire token, refresh, scadenze, e farlo in modo che un frontend SPA o un'app nativa possano connettersi senza diventare matti.

Laravel mette a disposizione due soluzioni ufficiali: Sanctum e Passport. Chi ci segue da tempo sa che noi di Meteora Web lavoriamo ogni giorno con Laravel — lo abbiamo scelto per il nostro stack proprio per il controllo totale che offre senza canoni a vita. In questa guida ti spieghiamo cosa cambia tra i due e, soprattutto, quando usarli.

Che cos'è Laravel Sanctum e come funziona?

Sanctum nasce per semplificare l’autenticazione di SPA (Single Page Application) e API token-based per mobile o applicazioni di terze parti. Non è un OAuth2 completo: è un wrapper leggero sopra i token API di Laravel.

Come funziona per SPA?

Sanctum sfrutta i cookie di sessione di Laravel. L’utente fa login, il server imposta un cookie di sessione (con SameSite=Strict) e tutte le richieste successive vengono autenticate via sessione, non via token. Questo è più sicuro contro XSS perché il token non è mai esposto al JavaScript.

// config/sanctum.php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost,localhost:3000')),

Nel frontend (Vue/Axios):

axios.get('/api/user', { withCredentials: true });

Come funziona per API token?

Per app mobile o servizi esterni, Sanctum genera token Bearer classici. L’utente richiede un token via login, lo salva lato client e lo invia nell’header Authorization: Bearer .... Semplice, senza OAuth.

// App\Models\User
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
}

// Creare un token
$token = $user->createToken('mobile-app', ['read', 'write'])->plainTextToken;

Sanctum è perfetto quando controlli sia il frontend che il backend e non hai bisogno del protocollo OAuth2 (es. client di terze parti non fidati).

Che cos'è Laravel Passport e perché è nato?

Passport è un’implementazione completa di OAuth2 Server. Nato quando Laravel doveva fornire API pubbliche a client esterni (es. sviluppatori che vogliono integrare la tua piattaforma). OAuth2 permette di concedere accesso limitato a risorse senza condividere la password dell’utente.

Passport supporta tutti i grant type: Authorization Code, Client Credentials, Password Grant, Personal Access Tokens, Refresh Tokens. È più complesso da configurare, ma è lo standard per API pubbliche.

Esempio con Password Grant

// routes/api.php
Route::post('/oauth/token', 'Laravel\Passport\Http\Controllers\AccessTokenController@issueToken');

// Richiesta tipica:
// POST /oauth/token
// grant_type=password
// client_id=...
// client_secret=...
// username=...
// password=...
// scope=...

Passport richiede un database aggiuntivo (oauth_clients, oauth_access_tokens, etc.) e la pubblicazione delle migration.

Quali sono le differenze principali tra Sanctum e Passport?

La domanda che ci fanno più spesso: “Quale devo usare?”. La risposta dipende da chi consuma le tue API.

• Sanctum: pensato per frontend che controlli tu (SPA + stessa app mobile). Zero overhead OAuth, token semplici, autenticazione via cookie per SPA.
• Passport: pensato per API pubbliche consumate da client di terze parti (es. una app mobile di un’altra azienda, un servizio esterno). Offre OAuth2 completo con refresh token e scopes.

Dal punto di vista della manutenzione, Sanctum è più snello — non richiede migrazioni extra, nessuna tabella oauth. Noi lo preferiamo per l’80% dei progetti. Passport lo tiriamo fuori solo quando serve realmente il protocollo OAuth2.

Come implementare l’autenticazione con Sanctum per SPA?

Supponiamo di avere un’app Vue che vive su app.miosito.it e Laravel su api.miosito.it. Vogliamo login via cookie di sessione.

Step 1: Configurare i domini stateful

// .env
SESSION_DOMAIN=.miosito.it
SANCTUM_STATEFUL_DOMAINS=app.miosito.it

Step 2: Middleware API

Nel middleware api assicurati che le rotte SPA usino web middleware (per sessioni) e Sanctum:

// routes/api.php
Route::middleware(['api', 'auth:sanctum'])->group(function () {
    Route::get('/user', function (Request $request) {
        return $request->user();
    });
});

Step 3: Login (backend)

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

public function login(Request $request)
{
    $credentials = $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (Auth::attempt($credentials, $request->boolean('remember'))) {
        $request->session()->regenerate();
        return response()->json(['user' => Auth::user()]);
    }

    return response()->json(['message' => 'Credenziali non valide'], 401);
}

Step 4: Lato frontend (Axios)

// Imposta withCredentials globalmente
axios.defaults.withCredentials = true;

// Login
axios.post('https://api.miosito.it/login', {
    email: 'user@example.com',
    password: '...'
}).then(response => {
    // Ora l'utente ha un cookie di sessione
    // Possiamo chiamare /api/user senza token
});

// Logout
axios.post('https://api.miosito.it/logout');

Attenzione: il CORS deve permettere credenziali. Configura cors.php con supports_credentials => true e allowed_origins corretti.

Come implementare l’autenticazione con Passport per API mobile?

Passiamo a un caso tipico: un’app mobile React Native (di terze parti) che vuole autenticarsi con le nostre API. Usiamo Password Grant (utente fidato).

Step 1: Installare Passport

composer require laravel/passport
php artisan passport:install

Questo genera le chiavi e crea un client con grant password.

Step 2: Configurare User model

// App\Models\User
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
}

Step 3: Rotte per token

Passport espone già le rotte per ottenere token. Basta aggiungere:

// routes/api.php
Route::post('/oauth/token', 'Laravel\Passport\Http\Controllers\AccessTokenController@issueToken');

// Proteggi le rotte con auth:api
Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});

Step 4: Lato mobile (esempio Flutter con http package)

http.Response response = await http.post(
  Uri.parse('https://api.miosito.it/oauth/token'),
  headers: {'Content-Type': 'application/json'},
  body: jsonEncode({
    'grant_type': 'password',
    'client_id': 'your-client-id',
    'client_secret': 'your-secret',
    'username': 'user@example.com',
    'password': '...',
    'scope': '',
  }),
);
var data = jsonDecode(response.body);
String accessToken = data['access_token'];
// Salva token in secure storage

Poi usa il token in ogni richiesta: Authorization: Bearer $accessToken.

Passport gestisce automaticamente il refresh token: se ricevi 401, chiedi un nuovo token a /oauth/token con grant_type=refresh_token.

Quale scegliere per il tuo progetto e perché?

La scelta è semplice se ti fai queste domande:

• Controlli sia frontend che backend? Usa Sanctum. È più veloce da configurare, non hai complessità OAuth, e la sicurezza via cookie per SPA è superiore.
• Hai bisogno di esporre API a client esterni? Usa Passport. OAuth2 è lo standard. Non reinventare la ruota con token custom.
• Hai già un’app mobile che consuma altre API OAuth2? Passport si integra meglio con provider esterni (es. Google, Facebook).
• Sei indeciso? Inizia con Sanctum. Puoi sempre migrare a Passport in seguito se il bisogno di OAuth2 diventa reale. Noi lo abbiamo fatto in un progetto di e-commerce B2B: prima Sanctum per il pannello admin SPA, poi Passport per l’API pubblica dei partner.

Noi di Meteora Web nel nostro stack proprietario usiamo Sanctum per le dashboard interne e Passport per le API pubbliche. Conosciamo i costi di entrambi — non solo in termini di codice, ma anche di manutenzione e sicurezza. Se vuoi approfondire l’architettura completa di un’applicazione Laravel enterprise, dai un’occhiata al nostro Pillar su Laravel Framework.

Cosa fare adesso

1. Identifica se le tue API saranno consumate da frontend che controlli o da terze parti.
2. Se sanctum: installalo con composer require laravel/sanctum e segui gli step sopra.
3. Se passaporto: composer require laravel/passport > php artisan passport:install.
4. Proteggi subito le rotte sensibili: non lasciare mai API pubbliche senza autenticazione.
5. Leggi la documentazione ufficiale di Sanctum e la documentazione di Passport per i casi avanzati (scopes, refresh token, multi-token).

La sicurezza delle API è un tema che vediamo spesso sottovalutato nelle PMI italiane. Non cadere nell’errore di usare token fatti in casa. Sanctum e Passport sono curati dal team Laravel, testati e sicuri. Scegli quello giusto e costruisci la tua API sapendo che la parte più delicata è già risolta.