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.

​

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	SPA propia, móvil, tokens personales
Complejidad	Alta	Baja

Cuando construyas un servidor MCP al que accedan clientes de IA, oficialmente se recomienda usar Passport. Los clientes MCP habitualmente asumen autenticación con OAuth.

​

Instalación

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

php artisan install:api --passport

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

composer require laravel/passport
php artisan passport:install

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

php artisan passport:keys

​

Configuración

​

Modelo User

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

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.

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

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

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

php artisan passport:client --client

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

use Laravel\Passport\Http\Middleware\EnsureClientIsResourceOwner;

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

​

Gestión de tokens

​

Asignar scopes

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

​

Comprobar scopes

use Laravel\Passport\Http\Middleware\CheckToken;

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

​

Revocar

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.

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

Para las rutas con client credentials grant no uses auth:api, sino EnsureClientIsResourceOwner.

​

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.

php artisan passport:client --personal

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

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

​

Enlaces relacionados

• Documentación oficial de Laravel: Passport
• Documentación oficial de Laravel: Sanctum