Implementa autenticación en Laravel con confianza: desde el scaffolding básico de registro con Laravel UI hasta la protección de rutas API con Laravel Sanctum, pruebas automatizadas sin errores 401 y emisión de tokens seguros con un controlador de acción única. Todo con sesiones basadas en cookies, protección CSRF y defensa ante XSS para SPA.

Configuración de autenticación con Laravel UI y Sanctum

Para iniciar, Laravel ofrece varios tipos de autenticación. Primero, Laravel UI brinda un scaffolding básico para registro y acceso por web. Luego, Sanctum habilita autenticación para SPA y APIs con sesiones y cookies o con tokens personales.

¿Cómo habilitar el scaffolding de Laravel UI?

• Instala el paquete y publica sus recursos con vendor publish.
• Se generan una migración y un archivo de configuración.
• Ejecuta las migraciones para preparar la base de datos.

fullscreen
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

¿Qué trait y middleware activan Sanctum para SPA?

• En el modelo User añade el trait HasApiTokens para poder crear tokens.

fullscreen
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens; // habilita creación de tokens
}

• En el Kernel agrega el middleware de Sanctum en el grupo 'api' para solicitudes de SPA con cookies stateful, protección CSRF y defensa ante filtración de credenciales por XSS.

fullscreen
protected $middlewareGroups = [
    'api' => [
        \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
        // ...
    ],
];

¿Cómo proteger rutas API con auth:sanctum?

• Aplica el middleware a las rutas que quieras proteger.

fullscreen
// routes/api.php
Route::middleware('auth:sanctum')->get('/ruta-protegida', function () {
    return 'OK';
});

• Si un cliente no está autenticado, obtendrá un 401: no autorizado.

Pruebas de autenticación con Sanctum

Al proteger las rutas con auth:sanctum, tus pruebas pueden fallar con 401. Sanctum provee una forma simple de simular un usuario autenticado en tests.

¿Qué indica un 401 en los tests?

• Que la ruta requiere autenticación y el test no está actuando como usuario.
• Solución: autenticar un usuario de prueba antes de la solicitud.

¿Cómo usar Sanctum::actingAs con factory?

• Crea un usuario con factory y autentícalo con acting_as.

fullscreen
use Laravel\Sanctum\Sanctum;
use App\Models\User;

Sanctum::actingAs(User::factory()->create());

• Repite esto en cada prueba que lo requiera.

¿Cómo aplicar autenticación en setUp?

• Centraliza la autenticación para toda la clase de pruebas.

fullscreen
protected function setUp(): void
{
    parent::setUp();

    Sanctum::actingAs(User::factory()->create());
}

• Resultado: las pruebas pasan al tener contexto autenticado por API.

Generación de tokens con un Single Action Controller

Para emitir tokens personales, crea un controlador de acción única que valide credenciales y retorne el token en formato JSON.

¿Cómo crear el controlador y validar el request?

• Genera el controlador e implementa el método __invoke.

fullscreen
php artisan make:controller UserTokenController

fullscreen
namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

class UserTokenController extends Controller
{
    public function __invoke(Request $request)
    {
        $data = $request->validate([
            'email' => ['required', 'email'],
            'password' => ['required'],
            'device_name' => ['required'],
        ]);

        $user = User::where('email', $data['email'])->first();

¿Cómo verificar credenciales y lanzar errores?

• Si el usuario no existe o la contraseña no coincide, lanza una excepción de validación.

fullscreen
        if (! $user || ! Hash::check($data['password'], $user->password)) {
            throw ValidationException::withMessages([
                'email' => 'El email no existe o no coincide con nuestros datos.',
            ]);
        }

• Importa Hash por namespace y usa Hash::check para comparar la contraseña con el hash almacenado.

¿Cómo crear el token, ruta y probar el endpoint?

• Crea el token con el trait HasApiTokens y retorna JSON.

fullscreen
        $token = $user->createToken($data['device_name'])->plainTextToken;

        return response()->json(['token' => $token]);
    }
}

• Define la ruta tipo POST hacia el controlador.

fullscreen
use App\Http\Controllers\UserTokenController;

Route::post('/sanctum-token', UserTokenController::class);

• Prueba con tu HTTP client: envía email, password y device_name a la ruta configurada. Si omites la contraseña, verás un mensaje de error de validación.

fullscreen
{
  "email": "usuario@correo.com",
  "password": "secreto",
  "device_name": "mi-dispositivo"
}

¿Quieres que revisemos tu configuración o tu flujo de pruebas con Sanctum? Cuéntame en los comentarios qué parte te gustaría profundizar y en qué entorno estás trabajando.