ADR-005 - S10 construye JWT propio (no Keycloak), con arquitectura lista para reemplazo en U3¶
Estado¶
Aprobada, parcialmente superada. Esta ADR documenta correctamente la decisión y el diseño de S10 (JWT propio, "listo para reemplazo"). Lo que ya no refleja la realidad es el supuesto de que ese reemplazo quedaría "fuera de alcance... sin agendarse en ninguna sesión concreta": una decisión posterior adelantó la migración a Keycloak dentro de la propia Unidad 2, documentada en S10b (ejecución obligatoria, no opcional) y asumida como prerrequisito por S11. Pendiente: una ADR nueva que formalice esa decisión — esta queda como registro histórico de por qué S10 se diseñó así en primer lugar.
Contexto¶
El sílabo de LP2 pide para S10, explícitamente: "Seguridad backend: usuarios,
hash de contraseñas, autenticación JWT, roles, permisos y protección de
endpoints" (docs/lp2/silabo_lp2_2026_2.md) — es decir, construir la
pieza de seguridad, no delegarla a un tercero.
La práctica profesional actual tiende a delegar identidad a un proveedor
externo (Keycloak, Auth0, Amazon Cognito): custodia de credenciales fuera del
código propio, SSO (Single Sign-On) entre varias aplicaciones y login
social. Es una recomendación válida — y exactamente la que ya sigue
proyecto-sello (Sistema Universitario Integrado) con Keycloak como IAM
(Identity and Access Management) externo.
El curso paralelo de Aplicaciones Distribuidas (Sistemas Distribuidos, en
adelante DIST) enfrentó la misma decisión en su sesión S7
(docs/sesiones/S07_Seguridad_Distribuida_Control_Acceso.md del repositorio
pagatu). Su resolución: construir pagatu-auth-ms, un emisor de JWT
propio y explícitamente temporal, firmado con clave asimétrica (RS256),
con roles y claims nombrados exactamente igual que los que emite Keycloak
(sub, realm_access.roles), diseñado para que Keycloak lo reemplace
después cambiando una sola propiedad de configuración (jwk-set-uri →
issuer-uri), sin tocar el código de los microservicios que validan el
token. A la fecha de esta ADR, DIST ya entregó esa sesión (S7) y avanzó a S8
(mensajería); la sesión que reemplazaría pagatu-auth-ms por Keycloak (junto
al cliente Angular) todavía no existe como guía escrita — es una
dirección documentada (su Tabla 6), no un entregable construido.
LP2 además es un monolito modular por decisión explícita (ADR-001, ADR-002): no hay Gateway ni microservicios separados, y el backend sigue siendo un único proceso Spring Boot desplegable. Una primera versión de esta ADR asumió que, al ser un solo proceso, el emisor y el validador del JWT podían compartir directamente el mismo bean de clave en memoria, sin publicar nada por HTTP. Dos correcciones, hechas durante el diseño de esta sesión, revisaron ese punto:
- Acoplamiento oculto del validador. Inyectar el
JwtDecoderdirecto desde un@Bean RSAKeyataSecurityConfigal código Java deJwtKeyConfig— reemplazar el emisor después exigiría tocar esa clase, no solo una propiedad, contradiciendo la promesa de "reemplazo barato" que esta misma ADR hace. La corrección:seguridadpublica su clave pública en/.well-known/jwks.json(igual quepagatu-auth-msen DIST), ySecurityConfigla consume por la propiedadspring.security.oauth2.resourceserver.jwt.jwk-set-uri, apuntando hoy ahttp://localhost:8080/.well-known/jwks.json(la propia aplicación). Un IdP externo después solo exige cambiar esa URL. - Dónde vive el dato de identidad. Guardar
USUARIOS/ROLEScomo un esquema más de Oracle (BOM_SEGURIDAD, junto aBOM_CATALOGOyBOM_VENTAS) enseña un modelo que ningún IdP real sigue: Keycloak (yproyecto-sello, que ya lo usa) nunca comparte motor de base de datos con la aplicación que protege — corre con su propio Postgres. Siseguridadnaciera sobre Oracle, reemplazar el emisor después exigiría además migrar datos entre motores, la fricción exacta que esta ADR busca evitar.
Decisión¶
S10 construye un módulo seguridad propio (paquete
pe.edu.upeu.bomerp.seguridad): usuarios y roles en tablas propias,
contraseñas con BCrypt, JWT firmado con clave asimétrica RS256 (misma
elección que DIST y por la misma razón: ningún punto de validación guarda
ningún secreto), roles VENDEDOR/SUPERVISOR/ADMIN ya diseñados por ADS
(S8 Tabla 10, RN5/RN8; S9 Tabla 8), endpoints de catalogo y ventas
protegidos por rol con Spring Security, y vendedorId tomado del claim
sub del JWT ya validado — nunca de un campo libre del request.
A diferencia de los demás módulos de BomERP, seguridad no persiste en
Oracle: vive en un Postgres propio (bomerp-seguridad-db, contenedor nuevo
en compose-dev.yml), con su propio DataSource/EntityManagerFactory
dentro del mismo proceso Spring Boot (dos pares explícitos — Oracle para
catalogo/ventas, Postgres para seguridad —, en vez del único datasource
autoconfigurado que ADR-002 describe para el resto del backend). El proceso
sigue siendo uno solo (ADR-001/ADR-002 no se tocan); lo que se divide es
dónde vive el dato, no cuántos ejecutables existen.
No se integra Keycloak en S10, ni se agenda su reemplazo en ninguna sesión concreta de U3: el sílabo de S13-S16 no lo menciona. Queda como dirección arquitectónica documentada, no como entregable — igual que en DIST hoy.
"Listo para reemplazo" significa, en términos concretos (mismo criterio que la Tabla 6 de DIST S07):
- Nombres de claim estándar:
sub(identificador del usuario) yrealm_access.roles(lista de roles) — el mismo formato que emite Keycloak. - La clave de firma se genera en un
@Beanpropio (JwtKeyConfig), nunca hardcodeada, y su mitad pública se publica en/.well-known/jwks.json— nada depende de inyectar ese bean directamente. SecurityConfigvalida contra esa URL por configuración (jwk-set-uri), no por una referencia de código aJwtKeyConfig. Es la única propiedad que cambiaría si el emisor fuera otro.seguridadpersiste en su propio Postgres, nunca en el Oracle decatalogo/ventas— el mismo aislamiento de datos que tendría un IdP externo real, sin migración de datos pendiente si ese reemplazo llega.- Ningún controller ni service de
catalogooventasconoce JWT: solo reciben un rol ya resuelto por Spring Security (hasRole) o, cuando necesitan el identificador del usuario (RN5/RN8), unJwtya verificado vía@AuthenticationPrincipal.
Reemplazar el emisor después (por Keycloak u otro IdP) sería cambiar la
propiedad jwk-set-uri y apuntar los clientes a un endpoint de login
distinto — nunca recompilar ni tocar catalogo o ventas. El mismo
argumento que ya usa DIST (Tabla 6) para justificar su propio diseño.
Alternativas consideradas¶
| Alternativa | Por qué se descarta |
|---|---|
| Integrar Keycloak directamente en S10 | El sílabo pide construir hash+JWT+roles, no delegarlos; además adelantaría contenido que el propio curso de Sistemas Distribuidos (más avanzado en este tema) todavía no ha construido como guía escrita — sin ninguna ADR ni sesión propia que lo valide primero. |
Construir un servidor OAuth2 completo con Spring Authorization Server (spring-boot-starter-oauth2-authorization-server) |
DIST ya evaluó esta opción (S07, 2.4) y la descartó con una razón que aplica igual aquí: implementar client registration, consent, refresh tokens y el resto del protocolo completo "equivale a reescribir Keycloak". Lo que hace "reemplazable" al emisor es que el validador lea la clave por una URL configurable, no que el emisor implemente el estándar entero — ya se logra sin este costo adicional. |
Replicar el patrón de DIST con un servicio de autenticación aparte (auth como proceso independiente) |
LP2 es un monolito modular por decisión explícita (ADR-001, ADR-002); separar seguridad en otro proceso, con su propio pom.xml y su propio puerto, contradice esa decisión sin que el sílabo lo pida ni exista el problema (varios procesos sin memoria compartida) que ese patrón resuelve en DIST. El aislamiento que sí hacía falta (identidad separada del resto) se logra separando el dato (Postgres propio), no el proceso. |
Guardar USUARIOS/ROLES como un esquema más de Oracle (BOM_SEGURIDAD) |
Es más simple (un solo motor de base de datos, sin contenedor nuevo), pero enseña un modelo que ningún IdP real sigue, y dejaría una migración de datos pendiente el día de un reemplazo real — contradice la razón de ser de esta ADR. |
| No dejar ninguna previsión de reemplazo, tratar el JWT propio como definitivo | Contradice sin necesidad la recomendación profesional válida de delegar identidad a un IdP externo (SSO multi-app, login social, custodia de credenciales): nombrar los claims en el formato estándar y aislar el dato hoy cuesta lo mismo que no hacerlo, y evita un retrabajo si el proyecto lo adopta más adelante. |
Consecuencias¶
- Nuevo paquete
seguridad, con sus propias tablas — pero en Postgres, no en Oracle:docs/bd2/index.mdreservaBOM_SEGURIDADcomo esquema Oracle del módulo, y esta ADR decide explícitamente no usarlo para persistencia; queda documentado aquí como la excepción al patrón de los demás módulos de BomERP. compose-dev.ymlgana un segundo contenedor (bomerp-seguridad-db, Postgres) además debomerp-oracle— el ambiente DEV deja de depender de un solo motor de base de datos.bomerp-backenddeja de tener un únicoDataSourceautoconfigurado (la simplificación que ADR-002 destacaba): gana dos pares explícitos deDataSource/EntityManagerFactory/PlatformTransactionManager, uno para Oracle (catalogo,ventas, y los módulos futuros que se sumen a ese mismo motor) y otro para Postgres (seguridad, exclusivamente). Es infraestructura que se configura una vez en S10 y no se vuelve a tocar.- Nueva dependencia de runtime:
org.postgresql:postgresql. Ventagana la columnaVENDEDOR_ID(en Oracle,BOM_VENTAS), poblada únicamente por el servidor a partir del JWT (RN5 de ADS S8) — nunca existió como campo del request, así que no hay nada que "quitarle" al DTO de entrada (a diferencia deidClienteen DIST, que sí tuvo que removerse deOrdenRequest).- La migración real a un IdP externo (Keycloak u otro) queda fuera de
alcance de esta ADR: requiere su propia ADR y su propia sesión si el curso
decide adoptarla, con el mismo criterio que ADR-004 ya fijó para diferir
JWT a S10 — no se adelanta trabajo sin que una sesión concreta lo pida.
El procedimiento concreto de ese reemplazo (descarga, configuración del
realm, protocol mapper de
vendedorIdy cambios exactos enbomerp-backend) ya está documentado como guía de referencia, fuera del sílabo: S10b_Seguridad_Backend_Keycloak.md. - La propiedad
jwk-set-uri(y, del lado del cliente, la URL de login) quedan como el único punto de cambio documentado si esa decisión futura se toma.