Tutorial Laravel Passport: Autenticación API OAuth2 Paso a Paso

• 02/09/2025

Tutorial Laravel Passport: Autenticación API OAuth2 Paso a Paso en Laravel

Bienvenido a dCreations.es, tu plataforma de confianza para tutoriales prácticos y educativos para programadores y emprendedores. Hoy nos adentraremos en uno de los pilares de la seguridad en el desarrollo de APIs con Laravel: Laravel Passport. Si alguna vez te has preguntado cómo implementar la autenticación API Laravel de forma robusta y estandarizada, o cómo integrar OAuth2 Laravel en tus proyectos, estás en el lugar correcto.

Este tutorial de Laravel Passport en español está diseñado para guiarte paso a paso, desde la instalación hasta la implementación de una autenticación API funcional. Nuestro objetivo es que, al finalizar esta guía, no solo entiendas qué es Laravel Passport, sino que también sepas cómo integrar Laravel Passport y usarlo eficazmente en tus proyectos. Prepárate para dominar la autenticación con Laravel Passport para tus APIs.

Únete a nuestra comunidad de Discord

Introducción a Laravel Passport: Autenticación OAuth2 para APIs robustas

En el mundo actual del desarrollo de software, las APIs (Interfaces de Programación de Aplicaciones) son el corazón de la interacción entre diferentes servicios y aplicaciones. Desde una aplicación móvil hasta un frontend de JavaScript moderno, todos necesitan una forma segura de comunicarse con el backend. Aquí es donde la autenticación API Laravel se vuelve fundamental.

Laravel Passport es el paquete oficial de Laravel que simplifica enormemente la implementación de OAuth2 para tus APIs. OAuth2 es un estándar de la industria que permite a las aplicaciones obtener acceso limitado a los datos de un usuario en un servicio HTTP, sin necesidad de que el usuario proporcione sus credenciales directamente a la aplicación.

Este sistema ofrece un marco robusto y flexible para manejar la autorización y la emisión de tokens Laravel Passport, garantizando que solo los clientes autorizados puedan interactuar con tus endpoints. Aprender a implementar Laravel Passport es crucial para cualquier desarrollador que aspire a construir APIs seguras y escalables con Laravel.

---

¿Qué es Laravel Passport y por qué es clave para la seguridad de tu API?

Laravel Passport es un paquete que proporciona una implementación completa de un servidor OAuth2 para tu aplicación Laravel. Esto significa que puedes proteger fácilmente tus APIs utilizando tokens de acceso, permitiendo a los usuarios autorizar a clientes (como aplicaciones móviles o aplicaciones de terceros) para acceder a sus datos sin compartir sus credenciales directamente.

La principal razón para utilizar Laravel Passport es su integración nativa y fluida con el ecosistema Laravel. Al ser un paquete oficial, sigue la filosofía de Laravel de ser elegante y fácil de usar, minimizando la complejidad de OAuth2. Esto se traduce en una guía de Laravel Passport sencilla para cualquier desarrollador de Laravel.

Sus ventajas son numerosas:

• - Estándar de la Industria: Al adherirse a OAuth2, Passport garantiza que tu API sea compatible con una amplia gama de clientes y prácticas de seguridad, fundamental para la seguridad API Laravel.

• - Facilidad de Uso: Abstrae gran parte de la complejidad de OAuth2, permitiéndote configurar Laravel Passport para un sistema de autenticación API robusto con unos pocos comandos.

• - Seguridad Mejorada: Proporciona un mecanismo seguro para la autenticación OAuth2 Laravel, protegiendo tus datos y los de tus usuarios.

• - Flexibilidad: Soporta diferentes tipos de grants o concesiones (código de autorización, contraseña, cliente, personal access tokens), adaptándose a diversas necesidades de autenticación con Laravel Passport.

• - Comunidad y Soporte: Al ser un paquete oficial, cuenta con una gran comunidad y una excelente documentación Laravel Passport, facilitando la resolución de dudas.

Si buscas una solución potente y bien integrada para la seguridad API Laravel, Passport es, sin duda, una de las mejores opciones disponibles para la autenticación API Laravel.

---

Requisitos Previos: Preparando tu entorno para Laravel Passport

Antes de sumergirnos en la implementación OAuth2 Laravel, es fundamental asegurarnos de que tu entorno de desarrollo está correctamente configurado. A continuación, te detallamos los requisitos básicos.

Proyecto Laravel: Tu punto de partida

Necesitarás un proyecto Laravel existente o, si lo prefieres, puedes crear uno nuevo. Si aún no tienes uno, puedes crear una nueva aplicación Laravel fácilmente. Asegúrate de tener una versión de PHP compatible con la última versión estable de Laravel.

Puedes crear un nuevo proyecto Laravel usando Composer con el siguiente comando:

composer create-project laravel/laravel nombre-de-tu-proyecto
cd nombre-de-tu-proyecto

Este comando instalará la última versión de Laravel y todas sus dependencias.

Composer: El gestor de paquetes de PHP

Composer es el gestor de paquetes de PHP y es absolutamente esencial para cualquier proyecto Laravel. Si no lo tienes instalado, puedes encontrar las instrucciones detalladas en su sitio web oficial (getcomposer.org). Es un proceso sencillo y muy bien documentado.

Verifica que Composer esté instalado correctamente abriendo tu terminal y ejecutando:

composer -V

Si ves un número de versión, estás listo para continuar. Composer nos permite instalar fácilmente todas las dependencias de Laravel Passport.

Base de Datos Configurada: El corazón de tus tokens

Laravel Passport requiere una base de datos para almacenar sus tokens de acceso, clientes y otra información relevante para la autenticación. Por lo tanto, es crucial que tengas una base de datos configurada y que Laravel pueda conectarse a ella.

Abre el archivo .env en la raíz de tu proyecto Laravel y configura tus credenciales de base de datos:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=tu_base_de_datos
DB_USERNAME=tu_usuario
DB_PASSWORD=tu_contraseña

Asegúrate de que la base de datos tu_base_de_datos exista en tu servidor de MySQL (o el motor de base de datos que uses) y que Laravel tenga permisos para leer y escribir en ella. Esto es vital para que las migraciones de Passport se ejecuten correctamente y para la integración Laravel Passport.

---

Tutorial Paso a Paso: Cómo integrar Laravel Passport en tu proyecto

Ahora que tenemos todo preparado, es momento de empezar con la integración Laravel Passport. Sigue estos pasos cuidadosamente para asegurar una configuración exitosa y configurar Laravel Passport en tu aplicación.

Paso 1: Instalación de Laravel Passport mediante Composer

El primer paso para implementar Laravel Passport es añadir el paquete a tu proyecto. Abre tu terminal en la raíz de tu proyecto Laravel y ejecuta el siguiente comando:

composer require laravel/passport

Este comando descargará e instalará todas las dependencias necesarias de Laravel Passport en tu directorio vendor. Es la forma más sencilla de obtener el paquete para tu autenticación con Laravel Passport.

Paso 2: Configuración de los Providers

Una vez instalado, necesitamos registrar el Service Provider de Passport en tu aplicación. Para Laravel 7 y versiones posteriores, esto a menudo se hace automáticamente gracias al auto-descubrimiento de paquetes.

Sin embargo, para versiones anteriores o si encuentras algún problema, puedes verificar o añadir manualmente Laravel\Passport\PassportServiceProvider::class en el array providers dentro de config/app.php:

// config/app.php
'providers' => [
    // ...
    Laravel\Passport\PassportServiceProvider::class,
],

Asegúrate de que esta línea esté presente para que Passport se registre correctamente con tu aplicación y puedas continuar con la implementación OAuth2 Laravel.

Paso 3: Ejecutar las Migraciones de Laravel Passport

Laravel Passport viene con sus propias migraciones de base de datos que crean las tablas necesarias para almacenar clientes, tokens de acceso, tokens de refresco, etc. Necesitas ejecutar estas migraciones para que Passport funcione correctamente.

Desde tu terminal, ejecuta el comando de migración de Artisan:

php artisan migrate

Este comando creará varias tablas en tu base de datos, incluyendo oauth_clients, oauth_access_tokens, oauth_refresh_tokens, oauth_auth_codes, y oauth_personal_access_clients. Sin estas tablas, Passport no podrá almacenar la información necesaria para la autenticación con Laravel Passport.

Paso 4: Generar las Claves de Encriptación de Passport

Laravel Passport utiliza claves de encriptación para asegurar los tokens. Necesitas generar estas claves. Afortunadamente, Passport proporciona un comando Artisan para hacer esto automáticamente.

Ejecuta el siguiente comando en tu terminal:

php artisan passport:install

Este comando realizará dos acciones importantes:

1. Creará las claves de encriptación necesarias para asegurar tus tokens de acceso. Estas claves se almacenan en el directorio storage/oauth-*.key.

2. Creará dos "clientes" OAuth predeterminados: un cliente de "personal access token" y un cliente de "password grant". Estos clientes son esenciales para los diferentes flujos de autenticación. Asegúrate de guardar el client_id y client_secret de estos clientes, ya que los necesitarás más adelante para usar Laravel Passport API.

Paso 5: Configurar el Modelo User para usar HasApiTokens

Para que tu modelo User pueda emitir y gestionar tokens API, necesita utilizar el trait HasApiTokens proporcionado por Passport.

Abre tu archivo app/Models/User.php y añade el trait:

<?php

namespace App\Models;

use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\HasApiTokens; // Importa el trait

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable; // Usa el trait

    // ...
}

Al añadir HasApiTokens, tu modelo User obtiene los métodos necesarios para crear y gestionar tokens de acceso, lo que es fundamental para la autenticación con Laravel Passport.

Paso 6: Registrar las Rutas de Autenticación API con Laravel Passport

Laravel Passport proporciona automáticamente las rutas necesarias para la emisión y gestión de tokens. Sin embargo, para que sean accesibles, debes indicarle a tu AuthServiceProvider que las registre.

Abre app/Providers/AuthServiceProvider.php y, dentro del método boot(), llama al método Passport::routes():

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Gate;
use Laravel\Passport\Passport; // Importa la clase Passport

class AuthServiceProvider extends ServiceProvider
{
    /**
     * The policy mappings for the application.
     *
     * @var array
     */
    protected $policies = [
        // 'App\Models\Model' => 'App\Policies\ModelPolicy',
    ];

    /**
     * Register any authentication / authorization services.
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();

        Passport::routes(); // Registra las rutas de Passport
    }
}

Esto creará rutas como /oauth/token y /oauth/authorize, que son esenciales para el flujo de autenticación OAuth2 Laravel. También puedes añadir las rutas para gestionar los tokens personales de acceso aquí si lo deseas.

Paso 7: Implementar el Middleware 'auth:api' para proteger rutas

Finalmente, para proteger tus rutas API y asegurar que solo los usuarios autenticados puedan acceder a ellas, debes especificar que usen el guard api y el middleware de Passport.

Abre config/auth.php y asegúrate de que el guard api esté configurado para usar el driver passport:

// config/auth.php
'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'passport', // Asegúrate de que el driver sea 'passport'
        'provider' => 'users',
    ],
],

Ahora, puedes proteger cualquier ruta API añadiendo el middleware auth:api a su definición:

// routes/api.php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});

// Otra ruta protegida
Route::middleware('auth:api')->get('/productos', function () {
    return ['Laptop', 'Ratón', 'Teclado'];
});

Con esto, cualquier petición a /api/user o /api/productos requerirá un token de acceso válido. ¡Has configurado Laravel Passport paso a paso y ya puedes autenticar API con Laravel!

---

Cómo usar Laravel Passport: Ejemplo de Autenticación API en acción

Ahora que Laravel Passport está configurado, veamos cómo usar Laravel Passport para autenticar a tus usuarios y proteger tus rutas API. Usaremos el tipo de "grant" password (concesión de contraseña), que es común para aplicaciones propias o móviles. Este es un ejemplo de Laravel Passport muy práctico.

Crear un Usuario para Pruebas

Para probar la autenticación, primero necesitamos un usuario en nuestra base de datos. Puedes registrar un usuario a través de un formulario web si lo tienes, o crearlo directamente usando Artisan Tinker.

Abre tu terminal y ejecuta:

php artisan tinker

Dentro de Tinker, crea un nuevo usuario:

App\Models\User::create([
    'name' => 'Usuario Prueba',
    'email' => '[email protected]',
    'password' => bcrypt('password123'),
]);

Esto creará un usuario con el email [email protected] y la contraseña password123. Recuerda que en un entorno de producción, nunca usarías contraseñas tan sencillas.

Obtener un Token de Acceso OAuth2

Para obtener un token de acceso utilizando el "password grant", necesitarás hacer una petición POST al endpoint /oauth/token. Este endpoint requiere el client_id y client_secret de tu cliente de "password grant", que se generaron cuando ejecutaste php artisan passport:install. Puedes encontrarlos en la tabla oauth_clients de tu base de datos. Busca el cliente con password_client = 1.

Aquí tienes un ejemplo de Laravel Passport de cómo podrías hacer esta petición usando curl o herramientas como Postman:

curl -X POST -H "Accept: application/json" \
    -d "grant_type=password" \
    -d "client_id=TU_CLIENT_ID" \
    -d "client_secret=TU_CLIENT_SECRET" \
    -d "[email protected]" \
    -d "password=password123" \
    -d "scope=*" \
    http://localhost:8000/oauth/token

Reemplaza TU_CLIENT_ID y TU_CLIENT_SECRET con los valores de tu base de datos. Si todo va bien, recibirás una respuesta JSON similar a esta:

{
    "token_type": "Bearer",
    "expires_in": 31536000,
    "access_token": "eyJ0eXAiOiJKV1...",
    "refresh_token": "def50200..."
}

¡Felicidades! Has obtenido tu primer token Laravel Passport. El access_token es lo que usarás para acceder a tus rutas API protegidas. El refresh_token se utiliza para obtener un nuevo access_token cuando el actual caduca, sin necesidad de que el usuario vuelva a introducir sus credenciales.

Proteger una Ruta de la API con Autenticación

Ahora que tienes un token de acceso, puedes usarlo para acceder a las rutas protegidas con el middleware auth:api.

Abre tu archivo routes/api.php y añade una ruta de prueba:

// routes/api.php

Route::middleware('auth:api')->get('/user-info', function (Request $request) {
    return response()->json([
        'message' => '¡Has accedido a una ruta protegida!',
        'user' => $request->user(),
    ]);
});

Para acceder a esta ruta, debes incluir el access_token en el encabezado Authorization de tu petición, con el prefijo Bearer.

Usando curl:

curl -H "Accept: application/json" \
     -H "Authorization: Bearer TU_ACCESS_TOKEN" \
     http://localhost:8000/api/user-info

Reemplaza TU_ACCESS_TOKEN con el access_token que obtuviste en el paso anterior. Si la petición es exitosa, verás los detalles del usuario, lo que confirma que la autenticación API Laravel funciona correctamente. Si el token es inválido o falta, Laravel devolverá un error 401 Unauthorized.

---

Personalización Avanzada de Laravel Passport: Adapta tu autenticación

Laravel Passport ofrece opciones de personalización para adaptarse a las necesidades específicas de tu aplicación. A continuación, exploraremos algunas de las más comunes, ampliando tu guía Laravel Passport.

Modificar el Tiempo de Expiración de los Tokens

Por defecto, los tokens de acceso personal de Passport tienen una larga duración. Puedes modificar el tiempo de vida de los tokens de acceso y de refresco en tu AuthServiceProvider.php.

Dentro del método boot(), puedes añadir las siguientes líneas:

// app/Providers/AuthServiceProvider.php

public function boot()
{
    $this->registerPolicies();

    Passport::routes();

    // Establece la expiración para tokens de acceso
    Passport::tokensExpireIn(now()->addDays(15)); // 15 días

    // Establece la expiración para tokens de refresco
    Passport::refreshTokensExpireIn(now()->addDays(30)); // 30 días

    // Establece la expiración para tokens de acceso personal (personal access tokens)
    Passport::personalAccessTokensExpireIn(now()->addMonths(6)); // 6 meses
}

Es crucial ajustar estos valores según los requisitos de seguridad y usabilidad de tu aplicación. Un menor tiempo de expiración aumenta la seguridad, pero puede requerir refrescos más frecuentes para el token Laravel Passport.

Uso de Grants Personalizados

Laravel Passport soporta varios tipos de "grants" (concesiones): Authorization Code, Implicit, Password, Client Credentials y Personal Access Tokens. Cada uno sirve para un caso de uso diferente (aplicaciones de terceros, SPA, aplicaciones propias, etc.).

Puedes habilitar o deshabilitar grants específicos si no los necesitas. Por ejemplo, si solo vas a usar Personal Access Tokens y Password Grants, puedes especificarlo. Passport, por defecto, habilita los más comunes. Revisa la documentación Laravel Passport para un uso más avanzado de los grants y su impacto en la autenticación Oauth2 Laravel*.

Revocar Tokens de Acceso

En ocasiones, un usuario o una aplicación puede necesitar revocar un token de acceso; por ejemplo, al cerrar sesión en todos los dispositivos o si se sospecha de una brecha de seguridad.

Passport facilita la revocación de tokens. Puedes hacerlo desde el controlador o donde sea necesario:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

public function logout(Request $request)
{
    Auth::user()->token()->revoke(); // Revoca el token actual
    return response()->json(['message' => 'Sesión cerrada exitosamente.'], 200);
}

// Para revocar todos los tokens de un usuario
public function revokeAllTokens()
{
    Auth::user()->tokens->each(function ($token) {
        $token->revoke();
    });
    return response()->json(['message' => 'Todos los tokens han sido revocados.'], 200);
}

La revocación de tokens es una característica de seguridad importante para la seguridad API Laravel y la autorización Laravel API.

---

Seguridad en Laravel Passport: Mejores prácticas esenciales

Implementar la autenticación no es solo hacer que funcione, sino también asegurarse de que sea segura. Laravel Passport proporciona una base sólida, pero tú eres responsable de seguir las buenas prácticas. Esto es clave para la seguridad API Laravel.

Almacenamiento Seguro de las Claves de Encriptación

Las claves de encriptación de Passport (ubicadas en storage/oauth-*.key) son críticas para la seguridad de tus tokens. Si estas claves caen en manos equivocadas, un atacante podría crear tokens válidos para tu API.

Recomendaciones:

• - No las versiones en Git: Asegúrate de que storage/*.key esté en tu .gitignore.

• - Permisos de archivo restrictivos: Las claves deben tener permisos que solo permitan al usuario del servidor web leerlas.

• - Entornos de Producción: Genera las claves directamente en el servidor de producción y asegúrate de que el directorio storage sea seguro.

Validación de Datos en las Rutas de Autenticación

Aunque Passport maneja la autenticación, tú eres responsable de la validación de los datos de entrada para la creación de usuarios o cualquier otra lógica de negocio asociada a la autenticación (p. ej., creación de usuarios, cambio de contraseña).

Asegúrate de que toda la entrada de usuario esté validada estrictamente para prevenir ataques como inyecciones SQL o XSS. Laravel Validator es tu mejor aliado aquí.

Uso Obligatorio de HTTPS

Siempre, y queremos decir siempre, utiliza HTTPS para todas las comunicaciones con tu API. Los tokens de acceso se envían en el encabezado Authorization, y si se envían a través de HTTP (no cifrado), pueden ser interceptados fácilmente por atacantes.

El uso de un certificado SSL/TLS es fundamental para proteger la privacidad y la integridad de los datos transmitidos. Esta es una práctica estándar para cualquier Laravel Passport API moderna.

---

Conclusión: Autenticación Segura y Eficiente con Laravel Passport

Hemos recorrido un camino completo, desde los fundamentos hasta la implementación y las mejores prácticas de Laravel Passport. Con este tutorial de Laravel Passport en español, ahora tienes las herramientas y el conocimiento para integrar una autenticación OAuth2 robusta y estandarizada en tus APIs de Laravel.

Laravel Passport no solo simplifica un proceso complejo como OAuth2, sino que también te permite construir aplicaciones más seguras y escalables. Recuerda la importancia de la validación, el uso de HTTPS y la gestión segura de las claves para mantener tu API protegida. Continúa explorando las posibilidades que ofrece Passport, como la gestión de scopes y clientes, para adaptar aún más tu autenticación a las necesidades de tu proyecto.

Para más tutoriales de Laravel y guías sobre desarrollo web y productividad, ¡no dudes en explorar el resto de contenido en dCreations.es!