Laravel Passport (implementazione di server OAuth2)

Come implementare un server OAuth2 con Laravel Passport. Tratteremo la scelta tra Sanctum e Passport, l’installazione, la gestione dei client, gli scope e la gestione dei token.

​

Cos’è Passport

Laravel Passport è il pacchetto ufficiale per far funzionare un’app Laravel come server di autorizzazione OAuth2. Si usa per integrazioni con app di terze parti o per API che richiedono un flusso OAuth2 rigoroso.

​

Passport vs Sanctum

Se OAuth2 è necessario scegli Passport. Se l’obiettivo è una semplice autenticazione tramite API token o l’autenticazione SPA/mobile, scegli Sanctum.

Aspetto	Passport	Sanctum
Scopo	Implementazione di server OAuth2	Autenticazione API semplice
Casi d’uso	Integrazione con app esterne, conformità allo standard OAuth2	SPA proprie, mobile, token personali
Complessità	Elevata	Bassa

​

Installazione

La raccomandazione ufficiale di Laravel 13 è install:api --passport.

php artisan install:api --passport

Per l’installazione manuale in un progetto esistente puoi usare anche i seguenti comandi.

composer require laravel/passport
php artisan passport:install

Al primo deploy potresti voler eseguire solo la generazione delle chiavi.

php artisan passport:keys

​

Configurazione

​

Modello User

Aggiungi al modello User il trait HasApiTokens e l’interfaccia OAuthenticatable.

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\Contracts\OAuthenticatable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable implements OAuthenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

​

Guard auth

Nella guard api di config/auth.php usa il driver passport.

'guards' => [
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

​

Configurazione nel service provider

Nel metodo boot() di AppServiceProvider puoi configurare gli scope e la scadenza dei token.

use Carbon\CarbonInterval;
use Laravel\Passport\Passport;

public function boot(): void
{
    Passport::tokensCan([
        'orders:read' => 'Lettura degli ordini',
        'orders:create' => 'Creazione degli ordini',
    ]);

    Passport::defaultScopes(['orders:read']);

    Passport::tokensExpireIn(CarbonInterval::days(15));
    Passport::refreshTokensExpireIn(CarbonInterval::days(30));
    Passport::personalAccessTokensExpireIn(CarbonInterval::months(6));
}

​

Gestione dei client

​

Client per authorization code grant

php artisan passport:client

Questo client si usa nel flusso OAuth2 standard che prevede una schermata di consenso dell’utente.

​

Client per client credentials grant

php artisan passport:client --client

Per gli endpoint di comunicazione machine-to-machine usa il middleware EnsureClientIsResourceOwner.

use Laravel\Passport\Http\Middleware\EnsureClientIsResourceOwner;

Route::get('/orders', function () {
    // ...
})->middleware(EnsureClientIsResourceOwner::using('orders:read'));

​

Gestione dei token

​

Assegnare gli scope

$accessToken = $user->createToken(
    'dashboard-token',
    ['orders:read', 'orders:create']
)->accessToken;

​

Verifica degli scope

use Laravel\Passport\Http\Middleware\CheckToken;

Route::get('/orders', function () {
    // ...
})->middleware(['auth:api', CheckToken::using('orders:read')]);

​

Revoca

use Laravel\Passport\Passport;

$token = Passport::token()->find($tokenId);
$token?->revoke();

​

Protezione delle route API

Alle API protette tramite user access token applica auth:api.

Route::middleware('auth:api')->group(function () {
    Route::get('/user', fn (Request $request) => $request->user());
    Route::get('/orders', [OrderController::class, 'index']);
});

Per le route del client credentials grant non usare auth:api, ma EnsureClientIsResourceOwner.

​

Personal Access Token

Adatti agli scenari in cui gli utenti emettono da soli token API, senza usare il flusso OAuth2 completo.

php artisan passport:client --personal

$token = $request->user()->createToken('cli-token', ['orders:read'])->accessToken;

Se il caso d’uso principale sono i Personal Access Token, anche ufficialmente Laravel consiglia di valutare Sanctum.

​

Link correlati

• Documentazione ufficiale Laravel: Passport
• Documentazione ufficiale Laravel: Sanctum