Autenticación
Descripción
La autenticación permite a los usuarios acceder al sistema mediante credenciales (email y contraseña). El sistema utiliza tokens JWT para mantener sesiones activas y permite la renovación de tokens mediante refresh tokens.
Casos de uso
Login (inicio de sesión)
Actor: Usuario registrado en el sistema.
Objetivo: Autenticarse y obtener tokens de acceso.
Precondiciones: El usuario debe existir en el sistema y estar activo. La organización del usuario debe estar activa.
Flujo principal:
- El usuario envía email y contraseña (y opcionalmente información del dispositivo e IP).
- El sistema valida las credenciales.
- El sistema verifica que el usuario esté activo.
- El sistema verifica que la organización del usuario esté activa.
- El sistema genera tokens de acceso y refresh token.
- El sistema crea una sesión asociada al refresh token.
- El sistema devuelve los tokens al usuario.
Resultado esperado: El usuario queda autenticado y recibe tokens de acceso válidos.
Flujos alternativos:
- Credenciales inválidas: Error 401 (unauthorized).
- Usuario deshabilitado: Error 403 (forbidden).
- Organización deshabilitada: Error 403 (forbidden).
- Datos inválidos: Error 400 con detalle de validación.
Refresh Token (renovación de tokens)
Actor: Usuario autenticado con un refresh token válido.
Objetivo: Obtener nuevos tokens de acceso sin reautenticarse.
Precondiciones: El usuario debe tener un refresh token válido y no revocado.
Flujo principal:
- El usuario envía el refresh token (y opcionalmente información del dispositivo e IP).
- El sistema valida que el refresh token exista.
- El sistema verifica que el refresh token no esté revocado.
- El sistema verifica que el refresh token no haya expirado.
- El sistema genera un nuevo refresh token y revoca el anterior (rotación de tokens).
- El sistema actualiza la sesión con el nuevo refresh token.
- El sistema genera nuevos tokens de acceso.
- El sistema devuelve los nuevos tokens al usuario.
Resultado esperado: El usuario recibe nuevos tokens de acceso y un nuevo refresh token. El refresh token anterior queda revocado.
Flujos alternativos:
- Refresh token no existe: Error 401 (unauthorized).
- Refresh token revocado: Error 401 (unauthorized).
- Refresh token expirado: Error 498 (token expired).
- Sesión no encontrada: Error 401 (unauthorized).
- Usuario/Organización/Rol no encontrado: Error 401 (unauthorized).
- Datos inválidos: Error 400 con detalle de validación.
Perfil de usuario (GET /auth/me)
Actor: Usuario autenticado (JWT válido).
Objetivo: Obtener el perfil del usuario actual (datos de usuario, organización y rol con permisos).
Precondiciones: El usuario debe enviar un access token JWT válido en el header Authorization: Bearer <token>.
Flujo principal:
- El cliente envía la petición con el JWT en el header de autorización.
- El sistema valida el token y extrae el identificador del usuario.
- El sistema obtiene el usuario, su organización y su rol (con permisos).
- El sistema devuelve el perfil con estructura:
user(id, email, name, level),organization(id, name),role(id, name, permissions como array de claves).
Resultado esperado: El usuario recibe su perfil completo.
Flujos alternativos:
- No autenticado o token inválido: Error 401 (unauthorized).
- Usuario no encontrado: Error 404 (not found).
Datos de las peticiones
Login
| Campo | Obligatorio | Reglas |
|---|---|---|
| Sí | Formato email válido | |
| password | Sí | 8–255 caracteres |
| info | No | Objeto con información opcional |
| info.device_info | No | Información del dispositivo |
| info.ip_address | No | Dirección IP del cliente |
Refresh Token
| Campo | Obligatorio | Reglas |
|---|---|---|
| refresh_token | Sí | UUID del refresh token |
| info | No | Objeto con información opcional |
| info.device_info | No | Información del dispositivo |
| info.ip_address | No | Dirección IP del cliente |
Respuestas del sistema
Login
- Éxito: Código 200 y cuerpo con tokens:
access_token: Token JWT de accesorefresh_token: Token UUID para renovaciónexpires_in: Tiempo de expiración en segundos (900 = 15 minutos)-
token_type: Tipo de token ("Bearer") -
Credenciales inválidas: Código 401 (unauthorized).
- Usuario deshabilitado: Código 403 (forbidden).
- Organización deshabilitada: Código 403 (forbidden).
- Validación: Código 400 con detalle de los campos que no cumplen las reglas.
Refresh Token
- Éxito: Código 200 y cuerpo con tokens (misma estructura que login).
- Refresh token inválido/revocado/no existe: Código 401 (unauthorized).
- Refresh token expirado: Código 498 (token expired).
- Validación: Código 400 con detalle de los campos que no cumplen las reglas.
Comportamiento de los tokens
Access Token
- Duración: 15 minutos (900 segundos).
- Uso: Incluido en el header
Authorization: Bearer <token>para acceder a rutas protegidas. - Expiración: Cuando expira, el usuario debe usar el refresh token para obtener uno nuevo.
Refresh Token
- Duración: 7 días desde la creación.
- Rotación: Cada vez que se usa para renovar tokens, se genera uno nuevo y se revoca el anterior.
- Revocación: Los tokens revocados no pueden usarse. El sistema mantiene un registro de qué token reemplazó a cada token revocado para detectar posibles robos de tokens.
- Expiración: Cuando expira, el usuario debe hacer login nuevamente.
Condiciones de negocio
Seguridad
- Los refresh tokens se rotan en cada uso para prevenir reutilización de tokens robados.
- Los tokens revocados almacenan referencia al token que los reemplazó para detectar intentos de uso de tokens robados.
- Los tokens incluyen información del dispositivo e IP para auditoría de seguridad.
- Las sesiones están vinculadas a refresh tokens específicos.
Validaciones
- El usuario debe estar activo para poder hacer login.
- La organización del usuario debe estar activa para poder hacer login.
- Los refresh tokens expirados no pueden usarse.
- Los refresh tokens revocados no pueden usarse.
- Las sesiones deben existir y estar vinculadas al refresh token usado.
Rutas públicas
POST /auth/login: Ruta pública (no requiere autenticación).POST /auth/refresh: Ruta pública (no requiere autenticación).POST /auth/register: Ruta pública (no requiere autenticación). Ver 08-registro.md.
Rutas protegidas (requieren JWT)
GET /auth/me: Devuelve el perfil del usuario autenticado (user, organization, role con permissions).
Relación con otros módulos
- Usuarios: La autenticación requiere que el usuario exista y esté activo. Ver 07-usuarios.md.
- Organizaciones: La autenticación requiere que la organización del usuario esté activa. Ver 01-organizaciones.md.
- Roles: Los tokens incluyen información del rol del usuario para autorización. Ver 03-roles.md.
- Permisos: Los permisos del rol del usuario determinan qué acciones puede realizar. Ver 02-permisos.md.