Laravel Passport para PHP: guía completa del servidor OAuth2

1. ¿Qué es y para qué sirve?

Laravel Passport es una implementación completa de un servidor OAuth2 para el framework Laravel (PHP). Proporciona un conjunto listo de herramientas para crear autenticación de API, permitiendo a los desarrolladores proteger sus API RESTful de forma rápida utilizando tokens de acceso estándar (access tokens) y tokens de actualización (refresh tokens). La librería está construida sobre el potente paquete League OAuth2 Server, adaptado al ecosistema de Laravel, incluyendo migraciones, fachadas, comandos Artisan y modelos Eloquent.

El objetivo principal de Passport es liberar al desarrollador de tener que escribir la lógica compleja de generación, verificación y almacenamiento de tokens manualmente. En su lugar, obtienes rutas listas para emitir tokens (a través de grant types), middleware para proteger rutas y métodos convenientes para gestionar clientes (aplicaciones) y tokens. Passport es ideal para crear Single Page Applications (SPA), aplicaciones móviles y clientes de servidor que necesiten acceso seguro a tu API.

¿Por qué usar Passport en lugar de una solución propia? Primero, por seguridad: la librería implementa todos los requisitos de la especificación OAuth2, incluyendo protección contra CSRF, manejo correcto de scopes y PKCE (Proof Key for Code Exchange). Segundo, por velocidad de desarrollo: obtienes migraciones, modelos y controladores listos. Tercero, por flexibilidad: Passport soporta todos los grant types principales (authorization code, client credentials, password grant, personal access tokens) y se puede extender fácilmente para necesidades específicas.

2. Instalación

La instalación de Laravel Passport se realiza a través de Composer, el gestor de paquetes estándar para PHP. Ejecuta el siguiente comando en la raíz de tu proyecto Laravel:

composer require laravel/passport

Después de instalar el paquete, debes ejecutar las migraciones y publicar la configuración. Passport utiliza su propio sistema de migraciones, que crea tablas para almacenar clientes, tokens, códigos de autorización y tokens personales:

php artisan migrate

Luego, ejecuta el comando passport:install, que creará las claves de cifrado y los clientes para tokens personales y password grant:

php artisan passport:install

Después de ejecutar el comando, verás en la consola dos client_id y client_secret. El primero es para tokens personales (Personal Access Client), el segundo para password grant (Password Grant Client). Guárdalos en el archivo .env:

PASSPORT_PERSONAL_ACCESS_CLIENT_ID=1
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=tu-secreto-aqui
PASSPORT_PASSWORD_GRANT_CLIENT_ID=2
PASSPORT_PASSWORD_GRANT_CLIENT_SECRET=tu-secreto-aqui

A continuación, añade el trait Laravel\Passport\HasApiTokens al modelo User (app/Models/User.php):

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;

    protected $fillable = [
        'name', 'email', 'password',
    ];

    protected $hidden = [
        'password', 'remember_token',
    ];
}

En el archivo config/auth.php, cambia el driver de autenticación a passport:

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

Finalmente, en el archivo app/Providers/AuthServiceProvider.php, añade la llamada a Passport::routes() en el método boot():

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
use Laravel\Passport\Passport;

class AuthServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $this->registerPolicies();
        Passport::routes();
    }
}