> ## 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 (implementación de servidor OAuth2)

> Explica cómo implementar un servidor OAuth2 con Laravel Passport. Cubre cuándo elegirlo frente a Sanctum, la instalación, la gestión de clientes, los scopes y la operativa con tokens.

## Qué es Passport

Laravel Passport es el paquete oficial para hacer que una aplicación Laravel funcione como servidor de autorización OAuth2.
Se utiliza en integraciones con aplicaciones de terceros y en APIs que requieren el flujo OAuth2 estricto.

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

    User->>Client: Inicia la integración
    Client->>App: Petición de autorización
    App->>User: Muestra la pantalla de consentimiento
    User->>App: Concede permiso
    App-->>Client: Código de autorización
    Client->>App: Intercambia el código por access token
    App-->>Client: Access token
    Client->>API: Invoca la API con el Bearer token
    API-->>Client: Respuesta
```

## Passport vs Sanctum

Si necesitas obligatoriamente OAuth2, elige Passport.
Si tu objetivo es una autenticación con tokens de API sencilla o autenticación SPA/móvil, elige Sanctum.

| Aspecto         | Passport                                                                                           | Sanctum                              |
| --------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Objetivo        | Implementar un servidor OAuth2                                                                     | Autenticación de API sencilla        |
| Casos adecuados | Integración con apps externas, cumplimiento del estándar OAuth2, [servidor MCP](/es/mcp#oauth-2-1) | SPA propia, móvil, tokens personales |
| Complejidad     | Alta                                                                                               | Baja                                 |

<Info>
  Cuando construyas un [servidor MCP](/es/mcp) al que accedan clientes de IA, oficialmente se recomienda usar Passport. Los clientes MCP habitualmente asumen autenticación con OAuth.
</Info>

## Instalación

La recomendación oficial en Laravel 13 es `install:api --passport`.

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

Si vas a introducirlo manualmente en un proyecto existente, también puedes configurarlo con los siguientes comandos.

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

En el primer despliegue puede que solo necesites generar las claves.

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

## Configuración

### Modelo User

Añade el trait `HasApiTokens` y la interfaz `OAuthenticatable` al modelo `User`.

```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 de auth

En el guard `api` de `config/auth.php` usa el driver `passport`.

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

### Configuración del service provider

En el `boot()` de `AppServiceProvider` puedes definir los scopes y la caducidad de los tokens.

```php theme={null}
use Carbon\CarbonInterval;
use Laravel\Passport\Passport;

public function boot(): void
{
    Passport::tokensCan([
        'orders:read' => 'Ver pedidos',
        'orders:create' => 'Crear pedidos',
    ]);

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

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

## Gestión de clientes

### Cliente para authorization code grant

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

Este cliente se usa en el flujo estándar de OAuth2 con pantalla de consentimiento del usuario.

### Cliente para client credentials grant

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

En endpoints de comunicación máquina a máquina, utiliza el middleware `EnsureClientIsResourceOwner`.

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

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

## Gestión de tokens

### Asignar scopes

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

### Comprobar scopes

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

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

### Revocar

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

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

## Proteger rutas de API

Añade `auth:api` a las APIs que quieras proteger con tokens de acceso de usuario.

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

<Warning>
  Para las rutas con client credentials grant no uses `auth:api`, sino `EnsureClientIsResourceOwner`.
</Warning>

## Personal Access Token

Sin usar el flujo completo de OAuth2, es apto para casos en los que el propio usuario emite un token de API.

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

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

<Info>
  Si tu uso principal son los Personal Access Tokens, la propia documentación oficial de Laravel recomienda valorar Sanctum.
</Info>

## Enlaces relacionados

* [Documentación oficial de Laravel: Passport](https://laravel.com/docs/13.x/passport)
* [Documentación oficial de Laravel: Sanctum](https://laravel.com/docs/13.x/sanctum)


## Related topics

- [Laravel Sanctum (autenticación con API tokens)](/es/sanctum.md)
- [Socialite for Discord](/es/packages/socialite-discord.md)
- [Crear un servidor MCP con Laravel](/es/advanced/mcp-server.md)
- [Laravel Nostr](/es/packages/laravel-nostr.md)
- [LINE SDK for Laravel](/es/packages/laravel-line-sdk/index.md)