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

> Explicamos cómo implementar un servidor OAuth2 con Laravel Passport. Cubrimos su diferencia con Sanctum, la instalación, la gestión de clientes y la operación con scopes y 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 usa en integraciones con aplicaciones de terceros o en APIs que requieren un flujo OAuth2 estricto.

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

    User->>Client: Inicia la integración
    Client->>App: Solicitud de autorización
    App->>User: Muestra la pantalla de consentimiento
    User->>App: Autoriza
    App-->>Client: Código de autorización
    Client->>App: Intercambia el código por un access token
    App-->>Client: Access token
    Client->>API: Llama a la API con Bearer token
    API-->>Client: Respuesta
```

## Passport vs Sanctum

Si necesitas OAuth2, elige Passport.
Si tu objetivo es simplemente autenticación por API tokens o autenticación de SPA / móvil, elige Sanctum.

| Punto           | Passport                                                | Sanctum                                |
| --------------- | ------------------------------------------------------- | -------------------------------------- |
| Objetivo        | Implementación de servidor OAuth2                       | Autenticación de API sencilla          |
| Casos adecuados | Integraciones externas, cumplimiento estricto de OAuth2 | SPAs propias, móvil, tokens personales |
| Complejidad     | Alta                                                    | Baja                                   |

## Instalación

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

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

Para instalarlo manualmente en un proyecto existente, también puedes usar:

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

En un primer despliegue puede que solo quieras generar las claves:

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

## Configuración

### Modelo User

Añade al modelo `User` el trait `HasApiTokens` y la interfaz `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

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

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

### Configuración en el service provider

En el `boot()` de `AppServiceProvider` puedes definir los scopes y la vida útil 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 usa 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;
```

### Verificar scopes

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

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

### Revocación

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

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

## Protección de rutas de API

Añade `auth:api` a las APIs que quieras proteger con el access token del 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 del client credentials grant, usa `EnsureClientIsResourceOwner` en lugar de `auth:api`.
</Warning>

## Personal Access Token

Adecuados para casos en los que el propio usuario emite API tokens, sin usar el flujo OAuth2 completo.

```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 considerar 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)