Saltar a contenido

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ó (el kid).
  • 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

  1. El usuario envía username y contraseña a POST /api/v1/auth/login.
  2. 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.
  3. Si el usuario está inactivo o eliminado → 403 «Usuario inactivo».
  4. Si el usuario tiene contraseña temporal → 403 con password_temp_required: se registra razon_fallo='password_temp_required' en log_sesiones, el frontend redirige al flujo de cambio de contraseña (CU-04) y NO se devuelven empresas ni pre-token.
  5. Se listan las empresas activas del usuario (rel_usuario_empresa activa + mae_empresas activa, ADR 0010 transversal). Si no tiene ninguna → 403 «Sin empresas asignadas».
  6. Con las credenciales validadas se firma el pre-token: un JWT de 5 minutos con scope=pre-auth y un solo uso. Su jti se persiste en trx_pre_tokens antes de responder, y la sesión se registra en log_sesiones con accion='login'.
  7. 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.
  8. El usuario envía pre-token y empresa elegida a POST /api/v1/auth/login/empresa.
  9. Si el pre-token no verifica (firma, expiración, audiencia o scope distinto de pre-auth) → 401 «Pre-token inválido».
  10. 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.
  11. Si el usuario está inactivo → 403 «Usuario inactivo». Si la empresa no está entre sus empresas activas → 403 «Sin acceso a la empresa».
  12. 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).
  13. 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.json para que los demás servicios verifiquen la firma (ADR 0006 transversal).
  • OpenAPI suma 6 endpoints bajo /api/v1/auth y el well-known.
  • log_sesiones registra cada intento, exitoso o no, con su razón de fallo; la bitácora es insert-only y particionada por mes (ADR 0021 transversal).
  • AuthRepository extiende UsuariosRepository y 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.