Descripción General
El sistema utiliza Laravel Sanctum para autenticación basada en tokens. Los usuarios pueden autenticarse con email o nombre de usuario, y reciben un token JWT válido por 8 horas.Flujo de Autenticación
Usuario envía credenciales
El cliente envía
user (email o username) y password al endpoint /api/login.Validación de credenciales
El servidor verifica:
- Usuario existe en la base de datos
- Contraseña coincide (bcrypt)
- Usuario no está deshabilitado
Generación de token
Si las credenciales son válidas:
- Se inicia sesión de Laravel (para exportaciones vía web)
- Se genera token Sanctum válido por 8 horas
- Se cargan empresas y permisos del usuario
Respuesta al cliente
El servidor responde con:
- Token de acceso
- Datos del usuario
- Empresas disponibles
- Permisos asignados
Modelo de Usuario
Tabla users
Relaciones del Modelo
app/Models/User.php
Login Flexible
El sistema acepta email o nombre de usuario en el campouser:
app/Http/Controllers/Api/AuthController.php:26
- Email:
[email protected] - Username:
jperez
Sesión Dual: Token + Session
El sistema mantiene dos tipos de sesión:1. Token Sanctum (API)
Usado para peticiones AJAX desde el frontend:app/Http/Controllers/Api/AuthController.php:49
2. Sesión Laravel (Web)
Usada para rutas web como exportaciones de PDF:app/Http/Controllers/Api/AuthController.php:46
Esto permite que las descargas de PDF (que abren en nueva pestaña) funcionen sin pasar el token por URL.
Carga de Datos en Login
Empresas Disponibles
app/Http/Controllers/Api/AuthController.php:52
Permisos del Usuario
app/Http/Controllers/Api/AuthController.php:68
Gestión de Usuarios
Listar Usuarios
Crear Usuario
Nombre de usuario para login
Email único del usuario
Contraseña (mínimo 6 caracteres)
Confirmación de contraseña
ID del rol asignado
ID de la empresa
Actualizar Usuario
Todos los campos son opcionales. Solo se actualizan los campos enviados.
Eliminar Usuario
Obtener Roles Disponibles
Validaciones
Reglas de Validación
| Campo | Regla | Descripción |
|---|---|---|
| name | required, string, max:255 | Nombre de usuario |
| required, email, unique:users | Email único | |
| password | required, min:6, confirmed | Contraseña con confirmación |
| rol_id | required, exists:roles,rol_id | Rol válido |
| id_empresa | required, exists:empresas,id_empresa | Empresa válida |
Mensajes de Error
Validación fallida
Seguridad
Hash de Contraseñas
Las contraseñas se almacenan con bcrypt:Verificación de Contraseña
app/Http/Controllers/Api/AuthController.php:38
Tokens Sanctum
- Duración: 8 horas por defecto
- Scopes:
['*'](todos los permisos) - Revocación: Se elimina al hacer logout
Middleware de Autenticación
routes/api.php:24
token.query permite pasar el token como query parameter para PDFs:
Mejores Prácticas
Contraseñas Seguras
Requiere contraseñas de al menos 8 caracteres con mayúsculas, minúsculas y números.
Renovación de Tokens
Implementa refresh automático antes de que expire el token de 8 horas.
Auditoría de Accesos
Registra intentos de login fallidos y accesos exitosos.
Validación de Email
Implementa verificación de email para nuevos usuarios.
Códigos de Error
| Código | Mensaje | Causa |
|---|---|---|
| 401 | Usuario no encontrado | El usuario no existe |
| 401 | Contraseña incorrecta | Contraseña no coincide |
| 401 | No autenticado | Token inválido o expirado |
| 403 | No puedes eliminar tu propia cuenta | Intento de auto-eliminación |
| 404 | Usuario no encontrado | ID de usuario inválido |
| 422 | Error de validación | Datos inválidos |
| 500 | Error al crear usuario | Error de base de datos |