0030. Autenticación: login en dos pasos y firma JWT¶
Estado: Aceptado Fecha: 2026-09-30 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/usuarios/, app/main.py, tests/unit/auth/, docs/adr/
Contexto¶
Este servicio es el único de la plataforma que firma los JWT (ADR 0007 de este
servicio; ADR 0011 y 0020 transversales). El login debe emitir tokens que los
demás servicios acepten sin consultar una base central: por eso la firma es
la garantía. Esta decisión explica, en criollo, qué es un JWT, qué significa
firmarlo y por qué el login se hace en dos pasos. Las empresas del usuario se
resuelven con rel_usuario_empresa (ADR 0010 transversal) y los permisos con
rel_usuario_accion (ADR 0023 transversal).
Qué es un JWT en criollo¶
Un JWT es un carnet firmado: un texto con tres partes separadas por puntos que cualquiera puede leer pero nadie puede modificar sin que se note.
- Cabecera (la primera parte): dice qué algoritmo se usó para firmar (en
nuestro caso
RS256) y qué clave pública se usó (elkid). - Datos o claims (la segunda parte): quién es el usuario, en qué empresa trabaja, qué permisos tiene y hasta cuándo vale el carnet.
- Firma (la tercera parte): el resultado de firmar las dos primeras con la clave privada del servicio.
Las tres partes van codificadas en base64url, una forma de escribir binario como texto seguro para URLs. Un JWT real se ve así:
eyJhbGciOiJSUzI1NiIsImtpZCI6ImlkZW50aWRhZC0xIn0.eyJzdWIiOiI4ZjhmOGY4Zi4uLiIsImVtcHJlc2FfaWQiOjF9.firma_que_nadie_puede_falsificar
Los datos se pueden leer sin ninguna clave: son base64. Lo que NO se puede hacer es cambiar un dato y volver a firmar, porque la firma se calcula sobre el contenido y sólo el dueño de la clave privada puede generarla.
Qué es firmar con clave privada/pública (RS256)¶
Imaginemos un sello de goma. El servicio de identidad es el único que tiene
el sello (la clave privada): cada token que emite lleva su sello estampado.
Los demás servicios no tienen el sello, pero tienen una copia del dibujo del
sello (la clave pública, publicada en /.well-known/jwks.json): pueden
comprobar que el sello es auténtico sin poder falsificarlo. Por eso un token
firmado por este servicio se acepta en toda la plataforma sin consultar una
base de datos central.
Se elige RS256 (firma asimétrica) y no HS256 (secreto compartido) porque con HS256 todos los servicios tendrían que conocer el mismo secreto: si uno de ellos se compromete, el atacante podría firmar tokens de cualquier servicio. Con RS256 la clave privada vive sólo en este servicio y el resto sólo verifica: comprometer a un verificador no permite falsificar nada (ADR 0020 transversal).
Por qué el login es en dos pasos¶
Las empresas del usuario son información sensible: no se deben mostrar antes de validar la contraseña. Por eso el paso 1 sólo valida credenciales y devuelve un pre-token de 5 minutos junto con las empresas; el paso 2 consume ese pre-token, valida la empresa elegida y recién ahí emite los tokens de acceso (ADR 0018 transversal).
La contraseña temporal se valida en el paso 1, no en el paso 2. Antes se
detectaba al elegir la empresa, después de que el usuario ya había visto el
selector; ahora el paso 1 corta de entrada: un usuario con contraseña temporal
ni ve sus empresas ni recibe pre-token, y el frontend lo manda directo al flujo
de cambio de contraseña (CU-04). El orden de validaciones del paso 1 es:
usuario → contraseña → estado (is_activo/deleted_at) → contraseña temporal →
empresas → pre-token.
Los claims del token (la segunda parte del carnet)¶
| Claim | Qué significa | Ejemplo |
|---|---|---|
sub |
Quién soy (id del usuario) | 8f8f8f8f-... |
usuario_id |
El id del usuario, explícito (mismo valor que sub) |
8f8f8f8f-... |
empresa_id |
En qué empresa trabajo | 1 |
empresa_nombre |
Nombre que se muestra de esa empresa (ADR 0045) | SIGFA |
username |
Mi nombre de usuario | ana |
tipo_usuario |
Mi rol (usuario, root, externo) |
usuario |
permisos |
Acciones que puedo ejecutar (códigos) | ["ventas.crear", "reportes.ver"] |
iss |
Quién firmó el carnet | com.godexerp.identidad |
aud |
Para quién es válido | com.godexerp.plataforma |
exp |
Hasta cuándo vale | 2026-09-30T12:15:00Z |
iat |
Cuándo se emitió | 2026-09-30T12:00:00Z |
jti |
Número de serie único del carnet | 9f9f9f9f-... |
iss y aud son fijos de plataforma: firmar_token los impone y el llamador
no puede cambiarlos (ADR 0007 de este servicio). permisos se omite para
root: su acceso es implícito (ADR 0023 transversal). empresa_nombre es
material de presentación (ADR 0045): viaja siempre, con null si la empresa no
existe o está borrada lógicamente, y no se usa para autorizar.
Decisión¶
Se implementa el flujo completo de autenticación bajo /api/v1/auth con el
patrón router -> service -> repository (ADR 0001 transversal). AuthRepository
extiende UsuariosRepository y reutiliza sus lecturas de usuarios, empresas y
permisos; AuthService recibe la configuración para firmar con las claves y
los TTLs; el router traduce las excepciones del dominio en 401/403.
| Endpoint | Función | Respuesta |
|---|---|---|
POST /api/v1/auth/login |
Paso 1: valida credenciales y contraseña temporal, devuelve pre-token + empresas | 200 |
POST /api/v1/auth/login/empresa |
Paso 2: consume el pre-token, emite access + refresh | 200 |
POST /api/v1/auth/refresh |
Rota el refresh token y re-emite el access | 200 |
POST /api/v1/auth/logout |
Revoca el refresh de esa sesión (idempotente) | 204 |
POST /api/v1/auth/logout-all |
Revoca todos los refresh del usuario (idempotente) | 204 |
GET /.well-known/jwks.json |
Publica la clave pública del servicio | 200 |
Flujo completo, en pasos¶
- El usuario envía username y contraseña a
POST /api/v1/auth/login. - El servicio busca al usuario por username y verifica la contraseña con Argon2id (ADR 0020 transversal). Si el username no existe o la contraseña es incorrecta → 401 «Credenciales inválidas»: el mensaje es genérico a propósito, para nunca revelar si el username existe.
- Si el usuario está inactivo o eliminado → 403 «Usuario inactivo».
- Si el usuario tiene contraseña temporal → 403 con
password_temp_required: se registrarazon_fallo='password_temp_required'enlog_sesiones, el frontend redirige al flujo de cambio de contraseña (CU-04) y NO se devuelven empresas ni pre-token. - Se listan las empresas activas del usuario (
rel_usuario_empresaactiva +mae_empresasactiva, ADR 0010 transversal). Si no tiene ninguna → 403 «Sin empresas asignadas». - Con las credenciales validadas se firma el pre-token: un JWT de 5
minutos con
scope=pre-authy un solo uso. Sujtise persiste entrx_pre_tokensantes de responder, y la sesión se registra enlog_sesionesconaccion='login'. - El frontend decide según la cantidad de empresas: con una entra directo (la elige por el usuario), con varias muestra un selector (modal) y con cero ya falló en el paso 5.
- El usuario envía pre-token y empresa elegida a
POST /api/v1/auth/login/empresa. - Si el pre-token no verifica (firma, expiración, audiencia o
scopedistinto depre-auth) → 401 «Pre-token inválido». - Si el pre-token ya fue usado → replay: se invalidan todos los
pre-tokens pendientes del usuario (reutilizar un token emitido indica una
fuga), se registra
razon_fallo='pre_token_replay'y se responde 401. - Si el usuario está inactivo → 403 «Usuario inactivo». Si la empresa no está entre sus empresas activas → 403 «Sin acceso a la empresa».
- Se marca el pre-token como usado, se arman los claims del access token (permisos = unión de las acciones del rol y del usuario en esa empresa, ADR 0023 transversal) y se firma el access token (15 minutos).
- Se genera el refresh token opaco: 64 bytes aleatorios en hex que el
usuario guarda y el servicio NO conoce: sólo persiste su SHA-256 en
trx_refresh_tokens(30 días), con la empresa, el user agent y la IP.
El pre-token y el replay¶
El pre-token dura 5 minutos y es de un solo uso: su jti se guarda en
trx_pre_tokens al emitirlo y se marca usado_en al consumirlo. Un segundo
intento con el mismo pre-token significa que alguien copió el token en
tránsito; por eso se trata como fuga y se invalidan todos los pre-tokens
pendientes del usuario (ADR 0018 transversal).
El refresh token opaco y la rotación¶
El refresh dura 30 días y se guarda sólo hasheado (SHA-256): si la base de
datos se filtra, los tokens no sirven (ADR 0011 transversal). En cada
renovación (/refresh) el token viejo se revoca y se emite uno nuevo
(rotación). Si un token ya revocado vuelve a usarse, se revocan TODOS los
refresh del usuario: un token revocado reutilizado es señal de robo.
Alternativas descartadas¶
- Login en un solo paso — expondría las empresas del usuario antes de validar la contraseña.
- Firma simétrica (HS256) — todos los servicios compartirían el secreto; un servicio comprometido podría falsificar tokens de los demás.
- Refresh token opaco sin rotación — un token robado seguiría siendo válido hasta su vencimiento y el replay no sería detectable.
- Guardar el refresh token en claro — una filtración de la base expondría las sesiones activas (ADR 0011 transversal).
Consecuencias¶
- El servicio publica su clave pública en
/.well-known/jwks.jsonpara que los demás servicios verifiquen la firma (ADR 0006 transversal). - OpenAPI suma 6 endpoints bajo
/api/v1/authy el well-known. log_sesionesregistra cada intento, exitoso o no, con su razón de fallo; la bitácora es insert-only y particionada por mes (ADR 0021 transversal).AuthRepositoryextiendeUsuariosRepositoryy reutiliza sus lecturas; el service de autenticación es nuevo y no toca SQLAlchemy.- El consumo del pre-token y la detección de replay dependen de la marca de
usado_en; la protección contra carreras a nivel de base (marcado condicional) queda como endurecimiento futuro si el análisis de carga lo pide.