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 ausuario_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 esNOT NULL, y quien consume decide si le sirve. - Naming
snake_case, simétrico conusuario_idyempresa_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_iden 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.ides 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.