> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```mermaid theme={null}
sequenceDiagram
    participant User as Utente
    participant Client as Client OAuth
    participant App as App Laravel<br>(Passport)
    participant API as API protetta

    User->>Client: Avvia l'integrazione
    Client->>App: Richiesta di autorizzazione
    App->>User: Mostra la schermata di consenso
    User->>App: Consenso
    App-->>Client: Codice di autorizzazione
    Client->>App: Scambia il codice con un access token
    App-->>Client: Access token
    Client->>API: Chiama l'API con il token Bearer
    API-->>Client: Risposta
```

## 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`.

```shell theme={null}
php artisan install:api --passport
```

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

```shell theme={null}
composer require laravel/passport
php artisan passport:install
```

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

```shell theme={null}
php artisan passport:keys
```

## Configurazione

### Modello User

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

```php theme={null}
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`.

```php theme={null}
'guards' => [
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],
```

### Configurazione nel service provider

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

```php theme={null}
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

```shell theme={null}
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

```shell theme={null}
php artisan passport:client --client
```

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

```php theme={null}
use Laravel\Passport\Http\Middleware\EnsureClientIsResourceOwner;

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

## Gestione dei token

### Assegnare gli scope

```php theme={null}
$accessToken = $user->createToken(
    'dashboard-token',
    ['orders:read', 'orders:create']
)->accessToken;
```

### Verifica degli scope

```php theme={null}
use Laravel\Passport\Http\Middleware\CheckToken;

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

### Revoca

```php theme={null}
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`.

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

<Warning>
  Per le route del client credentials grant non usare `auth:api`, ma `EnsureClientIsResourceOwner`.
</Warning>

## Personal Access Token

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

```shell theme={null}
php artisan passport:client --personal
```

```php theme={null}
$token = $request->user()->createToken('cli-token', ['orders:read'])->accessToken;
```

<Info>
  Se il caso d'uso principale sono i Personal Access Token, anche ufficialmente Laravel consiglia di valutare Sanctum.
</Info>

## Link correlati

* [Documentazione ufficiale Laravel: Passport](https://laravel.com/docs/13.x/passport)
* [Documentazione ufficiale Laravel: Sanctum](https://laravel.com/docs/13.x/sanctum)


## Related topics

- [Laravel Sanctum (autenticazione con API token)](/it/sanctum.md)
- [Socialite for Discord](/it/packages/socialite-discord.md)
- [LINE SDK for Laravel](/it/packages/laravel-line-sdk/index.md)
- [Creare un server MCP con Laravel](/it/advanced/mcp-server.md)
- [Laravel LSP — estensione delle funzionalità IDE tramite Language Server Protocol](/it/blog/laravel-lsp-introduction.md)