Saltar a contenido

0049. Entidad del usuario como claim del access token

Estado: Aceptado Fecha: 2026-10-22 Autor: David Garcia Módulo(s) afectado(s): app/domains/usuarios/, tests/unit/auth/, docs/adr/

Contexto

El access token identifica al usuario (sub / usuario_id), pero los demás servicios no guardan usuarios: guardan a la persona que actúa en su dominio. crm-svc-fuerza-ventas identifica al promotor por entidad_id (mae_entidades, persona natural o jurídica), la misma clave de mae_usuarios.entidad_id. Para limitar lo que ve cada usuario (un promotor ve lo suyo y lo de su equipo) necesita saber, en cada request, qué entidad está detrás del token.

Sin el dato en el token, cada servicio tendría que consultar a identidad en cada request, o guardar su propia copia de usuario_id.

Decisión

El access token suma el claim entidad_id: el mae_usuarios.entidad_id del usuario, como texto (igual que sub). Además:

  • Se arma en _claims_acceso, junto a usuario_id: lo emiten los tres endpoints que dan un access (/auth/login/empresa, /auth/refresh, /auth/cambiar-empresa). No requiere otra consulta: el usuario ya está cargado.
  • Siempre presente, también para root: la columna es NOT NULL, y quien consume decide si le sirve.
  • Naming snake_case, simétrico con usuario_id y empresa_id (ADR 0040).
  • El token del login administrativo (scope=admin, ADR 0047/0048) y el pre-token no cambian: no llevan empresa y los servicios de negocio los rechazan.

Alternativas descartadas

  • Que cada servicio consulte la entidad a identidad — una llamada por request, más latencia y una dependencia en caliente de identidad; rompe el diseño stateless (ADR 0031).
  • Que cada servicio guarde usuario_id en sus tablas — duplica el vínculo usuario↔persona que ya vive aquí y deja dos claves para lo mismo.
  • Poner el persona_id — no existe como clave propia: mae_personas.id es el de la entidad, y deja fuera a las personas jurídicas.

Consecuencias

  • Los servicios pueden resolver "quién es este usuario en mi dominio" sin llamar a identidad.
  • Tradeoff de frescura: si cambia la entidad de un usuario, el token viejo la conserva hasta el próximo refresh (TTL del access, 15 minutos). Es un cambio excepcional.
  • Los tokens emitidos antes de este cambio no traen el claim: quien lo consuma debe tolerar su ausencia hasta que roten.
  • get_current_user (ADR 0031) no lo exige.

Qué no cubre

  • Permisos por endpoint: el claim dice quién es, no qué puede hacer.
  • Datos de la persona (nombre, identificación) en el token: se consultan aparte si hacen falta.