S7 - Seguridad distribuida y control de acceso¶
Por: Angel Sullon Macalupu @asullom - 2026
1. Introducción¶
Tiempo: 20 min.
1.1 Presentación de la sesión¶
Hasta S6, pagatu-orden-ms confía en el idCliente que el propio request declara — el DTO (Data Transfer Object, objeto de transferencia de datos) OrdenRequest lo trae como un campo más, igual que metodoPago. Nada impide que cualquiera, con Swagger o una simple petición, escriba "idCliente": 1 y cree una orden a nombre de otra persona: el sistema nunca pregunta quién eres, solo confía en lo que el request dice ser. Esta sesión cierra esa puerta: aparece pagatu-auth-ms, un microservicio nuevo que autentica usuarios y emite un JWT (JSON Web Token) firmado; pagatu-gateway pasa a exigir y validar ese JWT antes de dejar pasar cualquier petición (Resource Server); y pagatu-orden-ms deja de aceptar idCliente en el request — lo toma directo del JWT, que también valida por su cuenta.
1.2 Índice¶
- Autenticación stateless con JWT.
- Autorización basada en roles.
- OAuth2 y OpenID Connect: el estándar detrás de un proveedor de identidad.
- Resource Server y validación de tokens con claves públicas.
- Observabilidad y diagnóstico.
1.3 Propósito de aprendizaje¶
Al concluir la clase, estarás en condiciones de:
- Implementar autenticación y autorización distribuida con JWT y Spring Security, aplicando el modelo de OAuth2 (servidor de autorización, resource server, claves públicas) para validar tokens en el Gateway y en los microservicios, y protegiendo rutas del sistema por rol, con evidencia real de accesos permitidos y denegados.
1.4 Producto de sesión¶
pagatu-auth-ms funcional — con usuarios y roles en tablas propias, login que emite un JWT firmado con clave privada y publica su clave pública, conectado a Config Server y a Eureka —; pagatu-gateway protegido como Resource Server, con rutas restringidas por rol (ADMIN/CLIENTE); y pagatu-orden-ms, también Resource Server, tomando idCliente del claim del JWT ya validado, no del request. pagatu-auth-ms es una pieza temporal de aprendizaje: está diseñado para que el reemplazo posterior por Keycloak cambie una propiedad de configuración, no el código del Gateway ni de los microservicios de negocio.
1.5 Metodología¶
Tabla 1. Metodología de la sesión
| Actividades a Realizar en el Periodo | Orientaciones generales (Orientaciones Metodológicas) | Material de estudio recomendado |
|---|---|---|
| Revisión previa individual | Confirmar que pagatu-config, pagatu-eureka, pagatu-gateway, pagatu-catalogo-ms y pagatu-orden-ms (S1-S6) siguen arrancando en DEV (entorno de desarrollo). Revisar el OrdenRequest actual de pagatu-orden-ms (S6, 3.5) y confirmar que idCliente hoy es un campo libre del request. Trabajo individual, antes de clase. |
Evidencia individual de S6, Alcance por microservicio y proyecto base. |
| Clase presencial | Construcción guiada de pagatu-auth-ms de punta a punta, protección de pagatu-gateway como Resource Server, y conversión de pagatu-orden-ms en Resource Server que toma idCliente del JWT. Trabajo individual, siguiendo al docente paso a paso; consulta inmediata ante un 401/403 inesperado. |
Pasos 3.1 a 3.27 de esta guía. |
| Evaluación formativa | Revisión en clase de la matriz de accesos (3.25): login exitoso, acceso denegado sin token, acceso denegado por rol incorrecto, y pagatu-orden-ms creando una orden con el idCliente tomado del JWT. La evidencia se completa y sustenta de forma individual, fuera del aula, según los criterios mínimos de la sección 4.4. |
Indicaciones de entrega (4.3), rúbrica de evaluación (4.6). |
1.6 Motivación de la sesión¶
1.6.1 Caso: la orden que se creó a nombre de otra persona¶
Un compañero de equipo revisa pagatu-orden-ms con Swagger, un día antes de la sustentación de S5. Prueba el endpoint POST /api/v1/ordenes con el cuerpo de ejemplo que ya trae la documentación — y sin querer, sin ninguna credencial, crea una orden real con idCliente: 1. El sistema la acepta sin preguntar nada: ni quién hizo la petición, ni si esa persona tiene permiso de actuar en nombre del cliente 1. idCliente es solo un número más dentro de un JSON (JavaScript Object Notation), tan editable como metodoPago.
El problema no es que alguien haya probado el endpoint — es que el sistema nunca definió quién puede decir que es quién. Cualquier dato que el propio cliente declara sobre sí mismo (su identidad, su rol) no es un dato confiable: hay que verificarlo contra algo que el cliente no controla. Un JWT firmado por un servicio de confianza (pagatu-auth-ms) es exactamente eso — el cliente no puede fabricar uno válido sin la clave privada con la que se firma, así que cualquier claim dentro de un JWT válido (incluido idCliente) sí es confiable.
Preguntas de análisis
Activación de conocimientos previos
- ¿Por qué un campo
idClientedentro del cuerpo de un request HTTP (HyperText Transfer Protocol) no es, por sí solo, una prueba de identidad? - Si
pagatu-gatewayya rechaza peticiones sin token válido, ¿por quépagatu-orden-msnecesita además validar el JWT por su cuenta — no le alcanza con que el Gateway ya lo validó?
Comprensión de seguridad distribuida
- Con
pagatu-gatewaycomo único punto de acceso (S4) y como Resource Server (hoy), ¿qué pasaría si alguien intentara llamar apagatu-orden-msdirecto por su puerto (8082), sin pasar por el Gateway? Relaciónalo con 2.1 y con S4 (producción local, ningún microservicio expone puerto al host salvo el Gateway). - ¿Qué diferencia hay entre "autenticar" (confirmar quién eres) y "autorizar" (confirmar qué puedes hacer)? Ubica un ejemplo de cada uno en el caso de 1.6.1.
1.7 Ubicación en el curso¶
- Unidad: U2 - Sistema distribuido robusto.
- Producto del curso: Proyecto Sello: sistema distribuido de microservicios end-to-end, configurable, escalable, seguro, resiliente, consistente, observable, integrado con frontend y defendido técnicamente.
- Producto de unidad: sistema distribuido seguro, resiliente, consistente, observable e integrado con cliente frontend.
- Avance del producto en esta sesión: tercer microservicio del proyecto (
pagatu-auth-ms), conpagatu-gatewayprotegido como Resource Server ypagatu-orden-msconsumiendo el JWT ya validado.
Figura 1. Roadmap del producto de la unidad
flowchart TB
ClientePrueba["Cliente de prueba<br/>PowerShell / bash / Swagger"]
ClienteAngular["Cliente real<br/>Angular 22 (S11)<br/>puerto 4200 (DEV)"]
Config["pagatu-config<br/>S2 · puerto 18888 (DEV)<br/>carga de configuración"]
Obs[("Observabilidad<br/>S10 · logs, métricas, paneles<br/>Prometheus 19090, Loki 13100<br/>Grafana 13000 (DEV)")]
Gateway["pagatu-gateway<br/>S4 · puerto 18080 (DEV)"]
Auth["pagatu-auth-ms<br/>S7 · JWT<br/>(temporal, luego Keycloak)"]
Catalogo["pagatu-catalogo-ms<br/>S1 · REST + BD + health"]
Orden["pagatu-orden-ms<br/>S6 · Feign + Circuit Breaker<br/>(S9: coordina Saga)<br/>produce: orden-eventos<br/>consume: pago-eventos"]
Pago["pagatu-pago-ms<br/>S8<br/>(S9: coordina Saga)<br/>consume: orden-eventos<br/>produce: pago-eventos"]
Eureka["pagatu-eureka<br/>S3 · puerto 18761 (DEV)<br/>registra instancias"]
Kafka[("Kafka<br/>S8 · puerto 19092 (DEV)<br/>topics: orden-eventos, pago-eventos")]
Pasarela["Pasarela de pagos<br/>(externa)"]
ClientePrueba --> Gateway
ClienteAngular --> Gateway
Gateway -->|"lb://pagatu-auth-ms"| Auth
Gateway -->|"lb://pagatu-catalogo-ms"| Catalogo
Gateway -->|"lb://pagatu-orden-ms"| Orden
Gateway -->|"lb://pagatu-pago-ms"| Pago
Gateway -. "descubre<br/>servicios" .-> Eureka
Eureka -. "carga<br/>configuración" .-> Config
Orden -->|"Feign: consulta<br/>producto"| Catalogo
Orden -.->|"1) orden.creada"| Kafka
Kafka -.->|"2) consume"| Pago
Pago -.->|"3) pago.validado<br/>(S9: pago.fallido)"| Kafka
Kafka -.->|"4) consume<br/>(S9: compensa)"| Orden
Pago -->|"autoriza / confirma<br/>pago"| Pasarela
classDef done fill:#e8f5e9,stroke:#2e7d32,color:#111;
classDef today fill:#ffe08a,stroke:#9a6b00,stroke-width:2px,color:#111;
classDef futuro fill:#f5f5f5,stroke:#9e9e9e,color:#555,stroke-dasharray: 5 5;
classDef externo fill:#e3f2fd,stroke:#1565c0,color:#0d3c73;
class Catalogo,Config,Eureka done;
class Auth,Gateway,Orden today;
class ClienteAngular,Kafka,Pago,Obs futuro;
class Pasarela externo;
Leyenda. Este diagrama es el mismo en todas las sesiones de la unidad; solo cambia el color: verde = construido en sesiones anteriores, amarillo = se trabaja hoy, gris punteado = todavía no existe, azul = sistema externo.
pagatu-cliente-ms (autónomo desde S2) y su consulta a RENIEC (Registro Nacional de Identificación y Estado Civil) / SUNAT (Superintendencia Nacional de Aduanas y de Administración Tributaria) no se dibujan para mantener legible el diagrama: siguen el mismo patrón de rutas, registro y configuración que los demás microservicios.
Hoy: aparece pagatu-auth-ms; pagatu-gateway y pagatu-orden-ms validan el JWT que emite, y pagatu-orden-ms deja de confiar en el idCliente del request. pagatu-cliente-ms se protege como trabajo autónomo (sección 4). pagatu-auth-ms es temporal: Keycloak lo reemplaza sin tocar el Gateway ni pagatu-orden-ms (2.4).
Relaciones con la infraestructura (no se dibujan, para mantener legible el diagrama):
pagatu-config:pagatu-gateway,pagatu-eurekay cada microservicio cargan su configuración desde él al arrancar (S2).pagatu-eureka: cada microservicio se registra en él como instancia (S3), ypagatu-gatewaylo consulta para descubrir servicios y resolver las rutaslb://.
Aún no existen (ya están agendados en el sílabo de esta unidad): Kafka y pago-ms (S8), Saga (S9), Observabilidad (S10) y el cliente Angular (S11).
2. Explica¶
Tiempo: 30 min.
2.1 Arquitectura de la sesión¶
Figura 2. pagatu-auth-ms emite el JWT y publica su clave pública; pagatu-gateway y pagatu-orden-ms lo validan
flowchart TB
Cliente["Cliente<br/>PowerShell / bash / Postman / Swagger"]
subgraph Paso1["1. Autenticación y emisión del token"]
direction LR
Auth["pagatu-auth-ms<br/>POST /api/v1/auth/login<br/>POST /api/v1/auth/registro<br/>GET /.well-known/jwks.json"]
AuthDB[("pagatu_auth_db<br/>usuarios, roles")]
Auth --> AuthDB
end
subgraph Paso2["2. Validación y autorización por ruta"]
direction LR
GW["pagatu-gateway<br/>Resource Server<br/>valida firma + rol"]
end
subgraph Paso3["3. Validación dentro del servicio"]
direction LR
Orden["pagatu-orden-ms<br/>Resource Server<br/>lee idCliente del JWT"]
Catalogo["pagatu-catalogo-ms"]
end
Cliente -->|"1. email + password"| Auth
Auth -->|"access_token (JWT, RS256)<br/>sub, realm_access.roles, idCliente"| Cliente
Cliente -->|"2. Authorization: Bearer JWT"| GW
GW -->|"3a. reenvía el mismo header"| Orden
GW -->|"3b. reenvía el mismo header"| Catalogo
GW -. "descarga la clave<br/>pública (JWKS)" .-> Auth
Orden -. "descarga la clave<br/>pública (JWKS)" .-> Auth
style Paso1 fill:transparent,stroke:transparent
style Paso2 fill:transparent,stroke:transparent
style Paso3 fill:transparent,stroke:transparent
Tres pasos, tres responsabilidades que no se mezclan. pagatu-auth-ms (Paso 1) solo confirma credenciales, firma el JWT con su clave privada y publica la clave pública — no sabe nada de órdenes ni de productos. pagatu-gateway (Paso 2) es la primera línea de defensa: verifica la firma con esa clave pública y decide si el rol alcanza para la ruta, antes de que la petición llegue a ningún microservicio. pagatu-orden-ms (Paso 3) también verifica la firma por su cuenta, sin asumir que alguien más ya lo hizo: en producción local (S4) ningún microservicio publica su puerto al host salvo el Gateway, pero en DEV pagatu-orden-ms sigue escuchando directo en 8082 (3.24 lo demuestra), y el Producto de la unidad pide que el token se valide en cada microservicio, no solo en el borde. pagatu-catalogo-ms todavía no valida nada por sí mismo — extenderle esta protección es exactamente el mismo cambio de 3.21.
Ni el Gateway ni pagatu-orden-ms guardan ningún secreto: solo necesitan saber dónde descargar la clave pública. Esa es la razón por la que reemplazar pagatu-auth-ms por Keycloak después es un cambio de configuración y no de código (2.4).
2.2 Autenticación stateless con JWT¶
Un sistema tradicional con sesiones guarda, en el servidor, quién está autenticado — una cookie de sesión es solo una referencia a ese estado guardado. Eso no encaja con un sistema distribuido: si la sesión vive en la memoria de una instancia de pagatu-gateway, y el balanceador (S4) manda la siguiente petición a otra instancia, esa instancia no tiene idea de que el usuario ya se autenticó.
Un JWT (JSON Web Token) resuelve esto sin guardar nada en el servidor: es un token que lleva dentro de sí mismo toda la información necesaria (sus claims — quién es el usuario, sus roles, idCliente, cuándo expira), firmado con una clave privada que solo conoce el sistema que lo emitió. Cualquier instancia puede verificar esa firma con la clave pública correspondiente, sin consultarle nada a pagatu-auth-ms en cada petición ni a ninguna base de datos — por eso es stateless: el propio token es la prueba, no una referencia a un estado guardado en otro lado. Quien tiene la clave pública puede comprobar un token, pero no puede fabricar uno.
Tabla 2. Autenticación con sesión vs. autenticación con JWT
| Con sesión (stateful) | Con JWT (stateless) | |
|---|---|---|
| Dónde vive el estado de "quién está autenticado" | En el servidor (memoria o BD de sesiones) | Dentro del propio token, firmado |
| Qué necesita cada instancia para validar | Consultar el mismo almacén de sesiones que las demás | Solo la clave pública del emisor (se descarga una vez) — no depende de las demás instancias |
| Qué pasa si el balanceador manda la petición a otra instancia | Falla, salvo que las instancias compartan el almacén de sesiones | Funciona igual: cualquier instancia valida el mismo token |
| Cómo se revoca antes de que expire | Borrando la sesión del almacén | No es trivial (2.2, Error frecuente) |
Error frecuente: asumir que un JWT se puede "cerrar sesión" como una sesión tradicional. Como el token no depende de ningún estado en el servidor, invalidarlo antes de su expiración natural exige un mecanismo aparte (una lista negra de tokens revocados, por ejemplo) — fuera del alcance de esta sesión. Por eso jwt.expiracion-segundos (3.5) debe ser un valor corto en un sistema real; en esta sesión se deja largo (una hora) solo para no complicar las pruebas manuales.
2.3 Autorización basada en roles¶
Autenticación responde quién eres; autorización responde qué puedes hacer — son dos preguntas distintas, y un JWT válido solo resuelve la primera. Un CLIENTE autenticado con un JWT perfectamente válido no debería poder borrar un producto del catálogo — ese JWT prueba su identidad, no le da permiso para esa acción.
Esta sesión usa RBAC (Role-Based Access Control): los permisos no se asignan usuario por usuario, sino a roles, y a cada usuario se le asignan uno o más roles. Así, cambiar lo que puede hacer una persona (porque cambió de puesto, o porque dejó la organización) es cambiarle el rol, no buscar permiso por permiso. Por eso los roles viven en su propia tabla (roles) y se relacionan con usuarios de muchos a muchos (3.3): agregar un rol nuevo, o darle dos roles a un mismo usuario, es agregar filas, no cambiar el esquema. Los roles del usuario viajan dentro del JWT como el claim realm_access.roles (["ADMIN"], ["CLIENTE"]), y cada ruta del Gateway declara qué rol necesita (3.18) — hasRole("ADMIN") en vez de una lista de usuarios autorizados uno por uno, que no escalaría a medida que el sistema crece.
Figura 3. Comprobación RBAC en pagatu-gateway: el rol del usuario decide si la petición pasa
flowchart TB
Usuario(["Usuario<br/>cliente@pagatu.com"])
Rol["Rol: CLIENTE"]
P1["ordenes: crear y consultar"]
P2["productos: consultar"]
Peticion(["POST /api/v1/productos<br/>con el token de CLIENTE"])
Check{"¿el rol tiene permiso<br/>para esta ruta?"}
Denegado["403 Forbidden"]
Permitido["Petición autorizada"]
Usuario -->|"tiene el rol"| Rol
Rol -->|"permisos"| P1
Rol -->|"permisos"| P2
Peticion --> Check
Check -->|"productos: escribir<br/>no asignado"| Denegado
Check -->|"permiso presente"| Permitido
Nota. Adaptado de RBAC / Control de Acceso, por SACAViX, s. f.-a, System Design (https://systemdesign.sacavix.com/patterns).
Un permiso es una acción sobre un recurso (ordenes:crear, productos:escribir); un rol es un paquete de permisos que se asigna a personas. En esta sesión los permisos no se guardan en ninguna tabla: están implícitos en las reglas por ruta de SecurityConfig (3.18) — cada hasRole(...) dice "este rol tiene permiso para esta ruta y este método HTTP". Si el sistema crece, ese es el punto donde conviene separar rol y permiso en dos conceptos distintos.
Cuando la autorización falla, el código HTTP dice cuál de las dos preguntas falló: 401 Unauthorized significa que no se pudo confirmar quién eres (sin token, token mal formado, firma inválida o expirado); 403 Forbidden significa que sí se confirmó, pero ese rol no alcanza para esa ruta.
RBAC es simple, y eso lo hace popular, pero tiene límites que conviene conocer:
- Explosión de roles: si cada combinación de condiciones se convierte en un rol nuevo (
CLIENTE_LIMA_PREMIUM,CLIENTE_CUSCO_BASICO...), los roles dejan de poder gestionarse. - No maneja contexto dinámico: "un
CLIENTEsolo puede ver sus propias órdenes" no se expresa con un rol, sino comparando un atributo del usuario con un atributo del recurso. Ese enfoque se llama ABAC (Attribute-Based Access Control): más flexible y más complejo. El claimidClientede hoy ya es un atributo, y compararlo con el dueño del recurso es el primer paso hacia ABAC (4.1, "consultar el propio perfil"). - Requiere revisiones periódicas: quién tiene qué rol cambia con el tiempo, y nadie lo revisa solo (3.26).
Y los errores de diseño más comunes al aplicarlo:
- Asignar permisos directamente a usuarios, en vez de a roles — vuelve al problema original de no escalar.
- Crear roles demasiado amplios "por comodidad" (un
ADMINpara todo), porque es más fácil que pensar qué necesita cada persona. - No hacer revisiones periódicas: roles acumulados que nadie revisó en años.
- No registrar en un audit log las verificaciones de autorización, y quedarse sin evidencia cuando hay que investigar un incidente.
2.4 OAuth2 y OpenID Connect: el estándar detrás de un proveedor de identidad¶
OAuth 2.0 (Open Authorization) es un estándar de autorización delegada (RFC 6749: Request for Comments, un documento del IETF —Internet Engineering Task Force—, el organismo que define los estándares de Internet): define cómo una aplicación obtiene acceso limitado a un recurso protegido sin conocer la contraseña del usuario, presentando un token emitido por un servidor de autorización en el que ambos confían. OpenID Connect (OIDC) es una capa de identidad encima de OAuth 2.0: agrega un formato estándar para decir quién es el usuario (el ID Token) y un mecanismo de descubrimiento (dónde están las claves, dónde se pide el token). Un proveedor de identidad como Keycloak implementa ambos estándares — por eso lo que se aprende hoy con Spring Security no se tira cuando llega Keycloak: cambia quién emite el token, no cómo se valida.
Estos conceptos se confunden con facilidad, así que conviene fijar hasta dónde llega cada uno. SSO (Single Sign-On) no es un estándar aparte sino un resultado: iniciar sesión una sola vez y entrar a varias aplicaciones sin volver a escribir la contraseña. Es posible porque la sesión vive en el servidor de identidad (una cookie en ese servidor), y cada aplicación lo consulta mediante OpenID Connect en vez de pedir credenciales por su cuenta. OAuth 2.0 por sí solo no da SSO: resuelve la autorización, no la sesión compartida.
Tabla 3. Alcance de cada pieza: estándar, librería y producto
| Pieza | Qué es | Qué resuelve | En esta sesión |
|---|---|---|---|
| OAuth 2.0 | Estándar de autorización delegada. | Que una aplicación acceda a una API (Application Programming Interface) con un token, sin conocer la contraseña. | Se implementa el lado Resource Server: el Gateway y pagatu-orden-ms validan tokens. pagatu-auth-ms no es un servidor OAuth 2.0 completo. |
| OpenID Connect | Capa de identidad sobre OAuth 2.0. | Saber quién inició sesión (ID Token), y publicar el descubrimiento y las claves. | Solo conceptual. pagatu-auth-ms publica claves (JWKS (JSON Web Key Set)) y claims parecidos, sin ID Token ni descubrimiento. |
| SSO | Resultado: una sola sesión para varias aplicaciones. | No volver a iniciar sesión en cada aplicación. | No existe hoy: pagatu-auth-ms no tiene sesión central. Llega con Keycloak (cliente Angular, S11). |
| Spring Security 7 | Librería de seguridad de Spring. | Autenticación, autorización por rol, resource server y cliente OAuth 2.0/OIDC. Desde la versión 7 incluye además un servidor de autorización. | Se usa para autenticar con usuario y contraseña, validar tokens en el Gateway y en pagatu-orden-ms, y emitir el JWT simple de pagatu-auth-ms. No se usa su servidor de autorización. |
| Keycloak | Producto: proveedor de identidad (servidor). | Servidor OAuth 2.0/OIDC completo: usuarios, roles, sesión y SSO, refresh token, MFA (Multi-Factor Authentication, autenticación en varios factores), federación y consola de administración. | No se usa en la sesión; reemplaza a pagatu-auth-ms después (Tabla 6). |
La regla práctica: Spring Security 7 se usa para proteger tus APIs (validar tokens); Keycloak se usa para emitir tokens y dar SSO. Spring Security 7 también podría ser el servidor de identidad, pero construir con él la sesión central, el cierre de sesión global, MFA, federación y la consola de administración equivale a reescribir Keycloak — por eso no se hace en este curso.
Tabla 4. Los cuatro actores de OAuth 2.0 en esta sesión
| Actor | Qué es | En esta sesión | Con Keycloak |
|---|---|---|---|
| Resource Owner | La persona dueña de los datos que se protegen. | El usuario cliente@pagatu.com. |
Igual. |
| Client | La aplicación que actúa en nombre del usuario y presenta el token. | PowerShell / curl hoy; Angular en S11. |
Igual — se registra como client del realm. |
| Authorization Server | Autentica al usuario y emite los tokens. | pagatu-auth-ms (temporal). |
Keycloak. |
| Resource Server | La API que valida el token y protege sus recursos. | pagatu-gateway y pagatu-orden-ms. |
Igual — no cambia de código. |
Figura 4. Los cuatro actores de OAuth 2.0 y el recorrido de un token
flowchart TB
Usuario["Resource Owner<br/>el usuario"]
Cliente["Client<br/>PowerShell hoy<br/>Angular en S11"]
AS["Authorization Server<br/>HOY: pagatu-auth-ms<br/>DESPUÉS: Keycloak"]
RS["Resource Server<br/>pagatu-gateway<br/>pagatu-orden-ms"]
Usuario -->|"entrega sus credenciales"| Cliente
Cliente -->|"1. pide un token"| AS
AS -->|"2. access_token (JWT)"| Cliente
Cliente -->|"3. Authorization: Bearer"| RS
RS -. "4. verifica la firma con la<br/>clave pública (JWKS)" .-> AS
Un proveedor de identidad completo emite tres tipos de token, y hoy solo construimos uno:
- Access token: el que las APIs aceptan (
Authorization: Bearer ...). Es de vida corta. Es el único que emitepagatu-auth-ms— su campoaccess_tokenyexpires_in(en segundos) siguen los nombres del estándar a propósito. - Refresh token: permite pedir un access token nuevo sin volver a pedir la contraseña. Hoy no existe; Keycloak lo emite.
- ID Token (OIDC): le dice al client quién inició sesión. No se manda a las APIs. Hoy no existe; Keycloak lo emite.
Cómo obtiene un token cada tipo de client¶
Un flujo (grant type) define cómo un client obtiene el token, y elegirlo depende de dos preguntas: ¿hay una persona presente que pueda iniciar sesión?, y ¿el client puede guardar un secreto sin que nadie lo vea? Un servidor con su propio backend sí puede (confidential client); una aplicación web que corre en el navegador, o una app móvil, no (public client): cualquiera puede inspeccionar su código.
Tabla 5. Flujos de OAuth 2.0 y cuándo se usa cada uno
| Flujo | ¿Hay persona? | ¿El client guarda un secreto? | Cuándo se usa | En pagatu |
|---|---|---|---|---|
| Authorization Code | Sí | Sí (confidential client) | Aplicación web con backend propio: el navegador va al servidor de autorización, la aplicación recibe un code de un solo uso y su backend lo canjea por tokens con su client_secret. |
No se usa hoy. |
| Authorization Code + PKCE (Proof Key for Code Exchange) | Sí | No (public client) | Aplicaciones que no pueden proteger un secreto (SPA, Single-Page Application; apps móviles). Hoy es la recomendación estándar, incluso para aplicaciones con backend. | Es el flujo del cliente Angular con Keycloak (S11). |
| Client Credentials | No | Sí | Comunicación servicio a servicio: el servicio se autentica con su propio client_id y client_secret, y el token lo representa a él, no a una persona. |
Ninguna llamada de hoy lo necesita (la llamada Feign de S6 consulta un endpoint público). |
| Device Code (RFC 8628) | Sí, desde otro dispositivo | No | Dispositivos sin teclado o navegador cómodo (televisores, consolas, terminales): el dispositivo muestra un código y la persona lo ingresa desde su celular. | No aplica al proyecto. |
| Resource Owner Password | Sí | — | El client recibe el usuario y la contraseña y los envía al servidor. No usar (RFC 9700). | El POST /api/v1/auth/login de hoy se parece a este flujo. |
Nota. Adaptado de OAuth2 / OpenID Connect, por SACAViX, s. f.-b, System Design (https://systemdesign.sacavix.com/patterns/oauth2-security). La lista oficial de tipos de flujo (grant types) de OAuth.net, en OAuth Grant Types (Parecki, s. f.; https://oauth.net/2/grant-types/), coincide con esta tabla: marca Implicit y Password Grant como legacy (heredados) y agrega el Refresh Token, que aquí se explica como tipo de token.
Authorization Code. Lo importante es por dónde viaja cada cosa: el navegador solo ve el code (que por sí solo no sirve), y el canje por tokens ocurre de servidor a servidor, con el client_secret, sin pasar nunca por el navegador. Por eso es el flujo más seguro cuando hay un backend que pueda guardar ese secreto.
Figura 5. Flujo Authorization Code
sequenceDiagram
actor U as Usuario
participant A as Aplicación web (backend)
participant AS as Servidor de autorización
participant API as API protegida
U->>AS: 1. login (redirigido desde la aplicación)
AS-->>A: 2. redirect + code (un solo uso)
A->>AS: 3. code + client_secret
AS-->>A: 4. access_token
A->>API: 5. Authorization: Bearer access_token
API-->>A: 6. 200 OK
Nota. Adaptado de OAuth2 / OpenID Connect, por SACAViX, s. f.-b, System Design (https://systemdesign.sacavix.com/patterns/oauth2-security).
Authorization Code + PKCE. Una SPA no puede guardar un client_secret, así que PKCE (Proof Key for Code Exchange, RFC 7636) lo reemplaza por un valor aleatorio que el client inventa en cada inicio de sesión: el code_verifier. El client envía primero su hash (code_challenge, calculado con SHA-256: Secure Hash Algorithm, de 256 bits) y, al canjear el code, debe presentar el code_verifier original; el servidor calcula el hash y comprueba que coincide. Aunque alguien intercepte el code en el redirect, no puede canjearlo, porque no conoce el code_verifier y un hash no se puede invertir (3.27 lo muestra con datos reales).
Figura 6. Flujo Authorization Code con PKCE
sequenceDiagram
actor U as Usuario
participant SPA as SPA (Angular)
participant AS as Servidor de autorización
participant API as API protegida
Note over SPA: genera un code_verifier aleatorio<br/>y calcula code_challenge = SHA-256(code_verifier)
SPA->>AS: 1. redirect + code_challenge
U->>AS: 2. login
AS-->>SPA: 3. redirect + code
SPA->>AS: 4. code + code_verifier
Note over AS: comprueba que SHA-256(code_verifier)<br/>coincide con el code_challenge del paso 1
AS-->>SPA: 5. access_token + refresh_token
SPA->>API: 6. Authorization: Bearer access_token
API-->>SPA: 7. 200 OK
Nota. Adaptado de OAuth2 / OpenID Connect, por SACAViX, s. f.-b, System Design (https://systemdesign.sacavix.com/patterns/oauth2-security).
Client Credentials. No hay persona ni redirects: un servicio le pide un token al servidor de autorización con su propia identidad. Sirve para llamadas entre servicios "por cuenta propia", sin un usuario detrás.
Figura 7. Flujo Client Credentials
sequenceDiagram
participant A as Servicio A
participant AS as Servidor de autorización
participant B as Servicio B (API protegida)
A->>AS: 1. client_id + client_secret
AS-->>A: 2. access_token (representa al servicio)
A->>B: 3. Authorization: Bearer access_token
B-->>A: 4. 200 OK
Nota. Adaptado de OAuth2 / OpenID Connect, por SACAViX, s. f.-b, System Design (https://systemdesign.sacavix.com/patterns/oauth2-security).
¿Qué flujo usamos hoy? Uno solo, no una combinación: el POST /api/v1/auth/login que construyes hoy, donde el client envía el usuario y la contraseña directo al servidor y recibe un access_token, equivale al flujo Resource Owner Password Credentials. Después, el client solo presenta ese token (Authorization: Bearer) al Gateway y a pagatu-orden-ms, que lo validan con la clave pública: ese segundo tramo no es otro flujo, es el uso normal de un access token. Ningún otro flujo de la Tabla 5 interviene hoy: Authorization Code y Authorization Code + PKCE llegan con Keycloak y el cliente Angular (S11), y Client Credentials no se necesita porque ninguna llamada entre servicios exige token. Y "equivale" es aproximado: pagatu-auth-ms no es un servidor OAuth 2.0 completo, así que su endpoint no recibe grant_type ni client_id; solo imita lo esencial del flujo, y por eso responde con los nombres estándar access_token, token_type y expires_in.
¿Qué es la RFC 9700? Como viste en el inicio de 2.4, una RFC es un documento del IETF; las de la serie BCP (Best Current Practice) no definen un protocolo nuevo, sino que fijan la práctica recomendada vigente. La RFC 9700, Best Current Practice for OAuth 2.0 Security (Lodderstedt et al., enero de 2025; BCP 240), es la guía oficial actual de seguridad de OAuth 2.0: actualiza y extiende las RFC 6749 (el propio OAuth 2.0), 6750 y 6819 con lo aprendido desde entonces, y depreca los modos de operación que resultaron inseguros. Los verbos en mayúscula son los de las RFC: MUST NOT es una prohibición, y SHOULD NOT es un desaconsejo con excepciones muy acotadas. Tres puntos de esta RFC son los que usa esta sesión:
- Sección 2.4: el flujo Resource Owner Password Credentials "MUST NOT be used", porque expone las credenciales del usuario al client. Es exactamente el flujo de hoy, y por eso
pagatu-auth-mses una pieza temporal de laboratorio y no un diseño final. OAuth 2.1, todavía en borrador, lo elimina. - Sección 2.1.2: el flujo Implicit "SHOULD NOT" usarse.
- Sección 2.1.1: los clients públicos "MUST" usar PKCE, y los servidores de autorización deben soportarlo; es la razón por la que el cliente Angular de S11 usará Authorization Code + PKCE.
Con Keycloak, la persona escribe su contraseña en la pantalla de Keycloak, nunca en la aplicación.
No confundas rol con scope: un rol es un atributo del usuario (ADMIN, CLIENTE) y se usa hoy; un scope es un permiso que el client pide en nombre del usuario (por ejemplo, ordenes:leer) y queda fuera del alcance de esta sesión, aunque Keycloak lo soporta.
Lo que cuesta usar OAuth 2.0. Es el estándar correcto, pero no es gratis: los flujos son más complejos (redirects, varios tokens); el servidor de autorización (Keycloak, Auth0) pasa a ser un componente crítico — si cae, nadie inicia sesión —; hay que gestionar tokens (refresh, rotación, revocación); y depurar un flujo de autorización es difícil porque el problema puede estar en cualquiera de los actores. Con Client Credentials hay un riesgo extra: no involucra a ninguna persona, así que un client_secret comprometido da acceso total a la identidad de ese servicio.
Errores de diseño más comunes al usarlo (todos aplican cuando llegue el cliente Angular de S11):
- Usar el flujo Implicit: obsoleto y vulnerable a la filtración de tokens; RFC 9700 desaconseja usarlo.
- No validar el parámetro
stateen el redirect, que protege contra CSRF (Cross-Site Request Forgery). - Guardar access tokens en
localStorage, vulnerable a XSS (Cross-Site Scripting). La alternativa habitual es guardarlos en memoria y dejar el refresh token en una cookiehttpOnly. - No rotar los refresh tokens, de modo que uno robado sirve indefinidamente.
- Usar Authorization Code sin PKCE en un cliente público (SPA, app móvil) que no puede proteger un
client_secret.
Por último, la tabla que resume qué de todo esto reemplaza Keycloak:
Tabla 6. Qué reemplaza Keycloak de pagatu-auth-ms, y qué código cambia
| Pieza | Hoy: pagatu-auth-ms |
Con Keycloak | ¿Cambia el código del Gateway / pagatu-orden-ms? |
|---|---|---|---|
| Servidor de autorización | pagatu-auth-ms (puerto 8085) |
Keycloak, en un realm del proyecto | No |
| Cómo se pide el token | POST /api/v1/auth/login |
POST /realms/{realm}/protocol/openid-connect/token |
No — lo llama el client, no los servicios |
| Usuarios, contraseñas y roles | Tablas usuarios, roles, usuario_roles (Flyway, 3.3) |
Usuarios y realm roles del realm | No |
| Claim de roles | realm_access.roles |
realm_access.roles (el mismo formato) |
No — el conversor de 3.17 sirve tal cual |
Identificador del usuario (sub) |
id numérico de usuarios |
UUID (Universally Unique Identifier) del usuario | No |
idCliente |
Columna id_cliente de usuarios |
User attribute + protocol mapper que lo agrega al token | No — el claim se llama igual |
| Claves de firma | Par RSA (Rivest–Shamir–Adleman, criptografía de clave pública) generado al arrancar; se pierde al reiniciar | Administradas, persistidas y rotadas por Keycloak | No |
| Dónde descargan la clave pública los resource servers | jwk-set-uri: http://localhost:8085/.well-known/jwks.json |
issuer-uri: http://localhost:{puerto}/realms/{realm} |
Sí — una propiedad YAML (YAML Ain't Markup Language) |
| Refresh token, ID Token, cierre de sesión, SSO, MFA | No existen | Incluidos | — |
El único cambio de configuración de la penúltima fila tiene una consecuencia extra: con issuer-uri, Spring descubre solo la ubicación de las claves (Keycloak publica un documento de descubrimiento OIDC) y además valida que el claim iss del token coincida con ese emisor. Hoy configuramos jwk-set-uri a mano porque pagatu-auth-ms no implementa el documento de descubrimiento.
2.5 Resource Server y validación de tokens con claves públicas¶
Un Resource Server es una aplicación que protege recursos y acepta access tokens como prueba de acceso. No emite tokens ni guarda contraseñas: solo los valida. Validar un JWT significa comprobar, como mínimo, tres cosas: que la firma es auténtica, que el token no expiró (exp) y, si el emisor lo define, que viene del emisor esperado (iss).
Hay dos formas de firmar un JWT, y la diferencia importa para un sistema distribuido:
- Simétrica (HS256, HMAC con SHA-256; HMAC significa Hash-based Message Authentication Code): una única clave secreta firma y verifica. Todo servicio que valida tiene que conocer el secreto — y quien conoce el secreto también puede fabricar un token de
ADMIN. Con diez microservicios, hay diez lugares desde donde se puede filtrar la clave que rompe todo el sistema. - Asimétrica (RS256, RSA con SHA-256): un par de claves. La privada firma y solo la conoce el emisor; la pública verifica y puede estar en cualquier lugar. Los resource servers no guardan ningún secreto: si alguien compromete el Gateway, no obtiene nada con qué fabricar tokens. Es la forma que usa Keycloak, y la que usa esta sesión.
La clave pública se publica en un documento JSON llamado JWKS (JSON Web Key Set), en una URL (Uniform Resource Locator, dirección web) conocida. Cada clave lleva un identificador (kid), y el encabezado de cada JWT dice con qué kid fue firmado — así el emisor puede rotar claves sin romper los tokens vigentes. Spring Security descarga el JWKS, lo guarda en memoria y lo vuelve a pedir solo cuando aparece un kid desconocido.
En un sistema de microservicios, cada resource server valida el token por su cuenta, en vez de confiar en que otro ya lo hizo. El Gateway es la primera línea (rechaza temprano y aplica el rol por ruta); el microservicio es la segunda (no depende de que nadie más haya verificado nada). Esa es la respuesta a "¿y si alguien llama directo al microservicio, sin pasar por el Gateway?" (1.6.1, pregunta de comprensión 1).
Decodificar un JWT no es validarlo. Un JWT es solo tres partes en Base64 — cualquiera puede leer sus claims, y cualquiera puede escribir un token con los claims que quiera. Lo que lo hace confiable es la firma verificada; leer idCliente de un token sin verificarla es exactamente el problema de 1.6.1, con un paso más.
2.6 Observabilidad y diagnóstico¶
Cuando una petición falla con 401 o 403, el problema puede estar en tres lugares distintos, y diagnosticarlo bien depende de saber cuál:
- El JWT no se envió o está mal formado — revisa el header
Authorizationque realmente salió del cliente (Bearer+ token, sin comillas ni espacios de más). - El JWT no se pudo verificar o expiró — revisa que
jwk-set-uriapunte de verdad al JWKS depagatu-auth-ms(ábrelo en el navegador), quepagatu-auth-msesté arriba cuando llega el primer token (sin él, el resource server no puede descargar la clave y rechaza todo), y que no lo hayas reiniciado desde que pediste el token (3.11: el par de claves se regenera al arrancar, y los tokens anteriores dejan de verificar). - El JWT es válido pero el rol no alcanza para esa ruta — revisa la regla de
SecurityConfig(3.18) contra los roles reales que trae el claimrealm_access.roles.
Para distinguir estos tres casos sin adivinar, sube el nivel de log de seguridad mientras diagnosticas (logging.level.org.springframework.security: DEBUG en pagatu-gateway): el log dice el motivo exacto del rechazo. Los logs del Gateway (3.19) y el traceId de cada petición (el mismo CorrelationIdFilter de S1/S6, que pagatu-auth-ms trae desde 3.7) son el punto de partida.
3. Aplica: actividad práctica guiada¶
Tiempo: 4h.
Actividad: construcción guiada de pagatu-auth-ms (un servidor de autorización didáctico, con usuarios y roles en tablas propias), protección de pagatu-gateway como Resource Server, y conversión de pagatu-orden-ms en Resource Server que toma idCliente del JWT ya validado (Producto de la sesión en 1.4).
Propósito de la actividad: que cada estudiante implemente autenticación stateless con un JWT firmado con clave asimétrica y autorización basada en roles, validando el token tanto en el Gateway como dentro del microservicio, y verificando con evidencia real accesos permitidos y denegados — no solo el caso feliz.
Orientaciones metodológicas: en el laboratorio, el docente construye las tres partes de construcción de la sesión en orden frente a la clase — primero pagatu-auth-ms completo (Parte A), después la protección del Gateway (Parte B), al final la conversión de pagatu-orden-ms (Parte C) —, y cierra con una revisión de accesos y un ejercicio de PKCE (Parte D); los estudiantes replican cada paso en su propio equipo, y provocan ellos mismos los casos denegados (3.19, 3.24) para ver el 401/403 real en su propia consola, no solo leer el resultado esperado en la guía. pagatu-auth-ms se construye a mano a propósito y es temporal: el objetivo es entender qué hace por dentro un servidor de autorización, para saber exactamente qué se le pide a Keycloak cuando lo reemplace (Tabla 6).
Actividades para realizar:
Parte A — Construir pagatu-auth-ms:
- 3.1 Crear el proyecto base de
pagatu-auth-ms. - 3.2 Levantar la base de datos de
pagatu-auth-ms. - 3.3 Crear la migración Flyway con usuarios, roles y datos semilla.
- 3.4 Conectar
pagatu-auth-msapagatu-configy apagatu-eureka. - 3.5 Configurar
pagatu-auth-msenconfig-repo. - 3.6 Agregar la ruta de
pagatu-auth-msal Gateway. - 3.7 Crear el manejador de errores y el filtro de trazabilidad.
- 3.8 Crear las entidades
UsuarioyRol. - 3.9 Crear los DTO de login.
- 3.10 Crear el repositorio y el servicio que carga usuarios en Spring Security.
- 3.11 Generar las claves RSA y crear el servicio de JWT.
- 3.12 Crear el servicio de autenticación, el controlador y el endpoint de claves públicas.
- 3.13 Configurar Spring Security en
pagatu-auth-ms. - 3.14 Levantar y probar
pagatu-auth-msde punta a punta. - 3.15 Agregar el registro de usuarios y probarlo con Swagger.
Parte B — Proteger pagatu-gateway como Resource Server:
- 3.16 Agregar la dependencia de OAuth2 Resource Server.
- 3.17 Apuntar el Gateway a las claves públicas y configurar el conversor de roles.
- 3.18 Proteger las rutas del Gateway por rol.
- 3.19 Probar accesos permitidos y denegados a través del Gateway.
Parte C — pagatu-orden-ms valida el JWT y toma el idCliente de él:
- 3.20 Quitar
idClientedel DTO de entrada. - 3.21 Convertir
pagatu-orden-msen Resource Server. - 3.22 Actualizar el controlador y el servicio de
pagatu-orden-ms. - 3.23 Probar de punta a punta, autenticado como
CLIENTE. - 3.24 Probar el llamado directo a
pagatu-orden-ms, sin pasar por el Gateway. - 3.25 Documentar la matriz de roles y accesos.
Parte D — Verificar y entender lo que viene:
- 3.26 Revisar los accesos y revocar un rol.
- 3.27 Ver PKCE en acción.
Punto de partida común: todo el equipo debe comenzar exactamente desde donde quedó S6 (Feign y Circuit Breaker), no desde su propio avance individual. Clona la rama s06-feign-circuit-breaker:
git clone --branch s06-feign-circuit-breaker https://github.com/262dist/pagatu.git
Levanta en DEV los servicios base ya construidos hasta S6 (pagatu-config, pagatu-eureka, pagatu-gateway, pagatu-catalogo-ms, pagatu-orden-ms) antes de tocar código nuevo — si alguno falla en arrancar, el problema es de una sesión anterior, no de esta.
Parte A — Construir pagatu-auth-ms¶
3.1 Crear el proyecto base de pagatu-auth-ms¶
Producto del paso: proyecto pagatu-auth-ms creado, con las mismas dependencias base que pagatu-orden-ms (S6) más Spring Security.
Tabla 7. Configuración de pagatu-auth-ms en Spring Initializr
| Campo | Valor |
|---|---|
| Project | Maven Project |
| Spring Boot | 4.1.1 |
| Language | Java |
| Group Id | pe.edu.upeu |
| Artifact Id | pagatu-auth-ms |
| Package name | pe.edu.upeu.auth |
| Packaging | Jar |
| Java | 21 |
| Dependencias | Spring Web, Validation, Lombok, Spring Boot DevTools, SpringDoc OpenAPI WebMvc UI, Spring Boot Actuator, Spring Data JPA, PostgreSQL Driver, Flyway, Prometheus (categoría Observability, io.micrometer:micrometer-registry-prometheus, scope runtime), Config Client y Eureka Discovery Client (categorías Spring Cloud Config y Spring Cloud Discovery) y Spring Security — las mismas de pagatu-orden-ms (S6, Tabla 3) más Spring Security, nueva hoy. Además, agrega MapStruct a mano en el pom.xml (S1, 3.5.20), igual que en pagatu-orden-ms: Spring Initializr no lo ofrece como opción. |
| Ubicación sugerida | services/pagatu-auth-ms |
Prometheus deja a pagatu-auth-ms visible en obs/ desde que arranca, con el mismo criterio que pagatu-orden-ms (S6).
Config Client y Eureka Discovery Client se marcan aquí, desde el inicio: son las dos dependencias con las que pagatu-auth-ms trae su configuración de pagatu-config y se registra en pagatu-eureka (3.4). pagatu-auth-ms no necesita ninguna dependencia de Gateway: el Gateway es quien enruta hacia él (3.6), no al revés.
Al marcar esas dos dependencias, Spring Initializr genera por su cuenta las tres piezas del pom.xml: las dos dependencias, la propiedad <spring-cloud.version> y el bloque <dependencyManagement> que importa el BOM (Bill of Materials, lista de versiones compatibles) de Spring Cloud (con Spring Boot 4.1.1, la versión es 2025.1.3). No hay nada que copiar a mano.
MapStruct se agrega a mano en el pom.xml, en dos lugares, igual que en pagatu-orden-ms (S1, 3.5.20). Queda listo aunque hoy pagatu-auth-ms no tenga ningún mapper: así el pom.xml no vuelve a tocarse cuando aparezcan DTO de usuario más adelante.
Lugar 1 — la dependencia, dentro de <dependencies>:
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>1.6.3</version>
</dependency>
Lugar 2 — el procesador de anotaciones, dentro de maven-compiler-plugin. El proyecto generado ya trae ese plugin con dos ejecuciones (default-compile para src/main y default-testCompile para src/test), cada una con un annotationProcessorPaths que solo tiene Lombok. Agrega mapstruct-processor después de Lombok en las dos ejecuciones — MapStruct necesita ver los getters y setters que Lombok genera. El plugin completo queda así:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<executions>
<execution>
<id>default-compile</id>
<phase>compile</phase>
<goals>
<goal>compile</goal>
</goals>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</path>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>1.6.3</version>
</path>
</annotationProcessorPaths>
</configuration>
</execution>
<execution>
<id>default-testCompile</id>
<phase>test-compile</phase>
<goals>
<goal>testCompile</goal>
</goals>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</path>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>1.6.3</version>
</path>
</annotationProcessorPaths>
</configuration>
</execution>
</executions>
</plugin>
Agrega también a mano, en el pom.xml, la librería con la que Spring Security firma un JWT — Spring Initializr no la ofrece como opción por separado (mismo criterio que MapStruct en S1, 3.5.20):
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-jose</artifactId>
</dependency>
Sin <version>: la gestiona el padre spring-boot-starter-parent. Trae NimbusJwtEncoder (para emitir tokens) y la librería Nimbus JOSE que sabe generar y publicar claves. No se agrega ninguna librería JWT aparte: la misma familia de Spring Security que valida el token en el Gateway y en pagatu-orden-ms es la que lo emite aquí — una sola manera de leer y escribir JWT en todo el sistema. Tampoco se agrega el starter de Resource Server: pagatu-auth-ms emite tokens, no valida los de otros, y ese starter activaría configuración automática que aquí no hace falta.
El puerto de base de datos (15431 en desarrollo, DEV; 25431 en producción local, PROD) y el nombre pagatu_auth_db ya estaban reservados desde la arquitectura del proyecto (docs/index.md) — no se inventan en esta sesión. El puerto de aplicación en DEV es 8085 — el siguiente libre después de 8080/8081 (pagatu-catalogo-ms, S1/S3), 8082/8083 (pagatu-orden-ms, S6) y 8084 (pagatu-cliente-ms).
3.2 Levantar la base de datos de pagatu-auth-ms¶
Producto del paso: PostgreSQL de pagatu-auth-ms corriendo en DEV.
services/pagatu-auth-ms/compose-dev.yml:
name: pagatu-auth-dev
services:
postgres-auth-dev:
image: postgres:16-alpine
container_name: pagatu-postgres-auth-dev
restart: unless-stopped
environment:
POSTGRES_DB: pagatu_auth_db
POSTGRES_USER: pagatu
POSTGRES_PASSWORD: pagatu
ports:
- "15431:5432"
volumes:
- pagatu_auth_dev_data:/var/lib/postgresql/data
volumes:
pagatu_auth_dev_data:
PowerShell / bash macOS/Linux:
cd services/pagatu-auth-ms
docker compose -f compose-dev.yml up -d
Comprueba que la base de datos está lista, mismo criterio que S1/S6:
docker exec -it pagatu-postgres-auth-dev psql -U pagatu -d pagatu_auth_db -c "SELECT current_database();"
docker exec -it pagatu-postgres-auth-dev psql -U pagatu -d pagatu_auth_db -c "\dt"
Resultado esperado: current_database devuelve pagatu_auth_db, y \dt responde No relations found. — todavía no hay tablas, porque la migración Flyway (3.3) ni siquiera se ha creado.
3.3 Crear la migración Flyway con usuarios, roles y datos semilla¶
Producto del paso: tres tablas — usuarios, roles y la tabla intermedia usuario_roles —, con dos usuarios de prueba: uno ADMIN, uno CLIENTE.
Los roles viven en su propia tabla, y usuario_roles los relaciona con los usuarios de muchos a muchos (2.3): un usuario puede tener varios roles, y un rol nuevo es una fila más, no una columna ni un enum que obligue a recompilar. Es, además, el mismo modelo que usa Keycloak (un usuario, varios realm roles), lo que hace la migración de la Tabla 6 casi directa.
services/pagatu-auth-ms/src/main/resources/db/migration/V1__create_usuarios_roles.sql:
CREATE TABLE IF NOT EXISTS roles (
id BIGINT GENERATED BY DEFAULT AS IDENTITY,
nombre VARCHAR(50) NOT NULL,
PRIMARY KEY (id),
CONSTRAINT uk_roles_nombre UNIQUE (nombre)
);
CREATE TABLE IF NOT EXISTS usuarios (
id BIGINT GENERATED BY DEFAULT AS IDENTITY,
email VARCHAR(150) NOT NULL,
password VARCHAR(100) NOT NULL,
habilitado BOOLEAN NOT NULL DEFAULT TRUE,
id_cliente BIGINT,
PRIMARY KEY (id),
CONSTRAINT uk_usuarios_email UNIQUE (email)
);
CREATE TABLE IF NOT EXISTS usuario_roles (
usuario_id BIGINT NOT NULL,
rol_id BIGINT NOT NULL,
PRIMARY KEY (usuario_id, rol_id),
CONSTRAINT fk_usuario_roles_usuario
FOREIGN KEY (usuario_id) REFERENCES usuarios (id) ON DELETE CASCADE,
CONSTRAINT fk_usuario_roles_rol
FOREIGN KEY (rol_id) REFERENCES roles (id) ON DELETE CASCADE
);
INSERT INTO roles (nombre) VALUES ('ADMIN'), ('CLIENTE');
INSERT INTO usuarios (email, password, habilitado, id_cliente) VALUES
('admin@pagatu.com', '$2b$10$ndX5v/xbbP8LAFlts57QweeqsmxNNDTkWZG4wpmShADMaVTON9bfC', TRUE, NULL),
('cliente@pagatu.com', '$2b$10$zCONDt0UNbJJh4C936JZyubU7ceojmoItVznixqKnivxjuxsofAPC', TRUE, 1);
INSERT INTO usuario_roles (usuario_id, rol_id)
SELECT u.id, r.id
FROM usuarios u
JOIN roles r ON (u.email = 'admin@pagatu.com' AND r.nombre = 'ADMIN')
OR (u.email = 'cliente@pagatu.com' AND r.nombre = 'CLIENTE');
El rol se guarda sin el prefijo ROLE_ (ADMIN, no ROLE_ADMIN) — igual que Keycloak. Spring Security sí exige ese prefijo internamente para hasRole(...), y se agrega en los dos lugares donde se traduce el rol a autoridad de Spring (3.10 y 3.17), nunca en la base de datos.
Las contraseñas ya están hasheadas con BCrypt (nunca se guarda una contraseña en texto plano, ni siquiera en datos semilla de práctica): el usuario admin@pagatu.com tiene contraseña real admin123, y cliente@pagatu.com tiene cliente123 — verificados de antemano contra esos dos hashes exactos. id_cliente: 1 en el usuario CLIENTE es el mismo idCliente que S6 usaba a mano en el request (3.22 lo reemplaza por este valor, tomado del JWT en vez de escrito por quien llama). Ojo: id_cliente es un dato de negocio que este servicio guarda por comodidad, no un dato de identidad — con Keycloak pasa a ser un atributo del usuario (Tabla 6).
¿Necesitas generar un hash? (opcional) Para esta sesión, no: los dos hashes de la migración ya están calculados, y con ellos funcionan el login y todas las pruebas. Solo lo necesitas si quieres agregar un usuario más con una contraseña tuya, por ejemplo un segundo CLIENTE para probar.
La razón es esta: el INSERT de la migración va directo a la base de datos, y ahí no corre ningún código Java que encripte. Por eso la contraseña debe llegar ya convertida en hash BCrypt. La contraseña real (cliente123) es lo que escribes al hacer login; el hash es lo único que se guarda.
1. Genera el hash. Cambia cliente123 por tu contraseña. x es un nombre de usuario cualquiera que htpasswd exige y aquí se descarta.
PowerShell:
(docker run --rm httpd:2.4-alpine htpasswd -nbBC 10 x cliente123).Split(':')[1]
bash macOS/Linux:
docker run --rm httpd:2.4-alpine htpasswd -nbBC 10 x cliente123 | cut -d: -f2
htpasswd viene en la imagen httpd de Docker y genera BCrypt con costo 10. La primera vez, Docker descarga la imagen y muestra varias líneas de progreso (Pull complete, Digest, Status): son de Docker, no del hash. El hash es la última línea, la que empieza con $2y$10$ y tiene 60 caracteres. Es un prefijo distinto al $2b$10$ de arriba, pero BCrypt igual, y BCryptPasswordEncoder de Spring lo acepta. Cada vez que lo ejecutes sale un hash distinto para la misma contraseña (BCrypt agrega una sal aleatoria): todos son válidos.
2. Úsalo en un INSERT. Pega el hash completo en la columna password, y asígnale un rol:
INSERT INTO usuarios (email, password, habilitado, id_cliente)
VALUES ('otro@pagatu.com', 'PEGA_AQUI_EL_HASH', TRUE, 2);
INSERT INTO usuario_roles (usuario_id, rol_id)
SELECT u.id, r.id FROM usuarios u, roles r
WHERE u.email = 'otro@pagatu.com' AND r.nombre = 'CLIENTE';
Ponlo en una migración nueva (V2__usuario_extra.sql, en la misma carpeta db/migration), no dentro de V1: Flyway guarda una firma de cada migración ya aplicada, y si editas V1 después de haber arrancado pagatu-auth-ms una vez, se niega a arrancar. Con el INSERT en V2, el usuario nuevo inicia sesión con cliente123 (o la contraseña que hayas usado en el paso 1). Si solo necesitas un usuario más con rol CLIENTE y no te importa que no tenga idCliente, el endpoint de registro de 3.15 hace este trabajo por ti, incluido el hash.
3.4 Conectar pagatu-auth-ms a pagatu-config y a pagatu-eureka¶
Producto del paso: pagatu-auth-ms externaliza su configuración y se registra como instancia descubrible.
Este paso y el siguiente van antes de escribir una sola clase: primero la base de datos (3.2), la migración (3.3) y la conexión a la infraestructura (3.4 y 3.5). Así, al terminar 3.5 puedes arrancar el servicio y ver a Flyway crear las tablas y a pagatu-auth-ms aparecer en Eureka, antes de que exista ninguna entidad, DTO o configuración de seguridad.
services/pagatu-auth-ms/src/main/resources/application.yml:
spring:
application:
name: pagatu-auth-ms
profiles:
active: dev
config:
import: "optional:configserver:${CONFIG_SERVER_URL:http://localhost:18888}"
Mismo patrón exacto que pagatu-orden-ms desde S6 — optional: evita que pagatu-auth-ms falle al arrancar si pagatu-config estuviera caído.
Las dos dependencias que hacen que esto funcione —spring-cloud-starter-config y spring-cloud-starter-netflix-eureka-client— ya quedaron en el pom.xml en 3.1, junto con la propiedad <spring-cloud.version> y el <dependencyManagement>: en este paso solo falta el application.yml. Sin ese import del Config Server, la dependencia de Config Client no tiene de dónde traer nada, y sin la sección eureka de 3.5 el servicio no se registra.
3.5 Configurar pagatu-auth-ms en config-repo¶
Producto del paso: los archivos de configuración DEV y PROD de pagatu-auth-ms, con los dos únicos datos propios del emisor de tokens: quién es (issuer) y cuánto duran sus tokens. Y el servicio arrancando en DEV, sin ninguna clase propia todavía.
infra/pagatu-config/config-repo/pagatu-auth-ms-dev.yml:
server:
port: 8085
spring:
datasource:
url: jdbc:postgresql://localhost:15431/pagatu_auth_db
username: pagatu
password: pagatu
driver-class-name: org.postgresql.Driver
flyway:
enabled: true
locations: classpath:db/migration
jpa:
hibernate:
ddl-auto: validate
show-sql: true
properties:
hibernate:
format_sql: true
devtools:
restart:
enabled: true
quiet-period: 2s
poll-interval: 3s
livereload:
enabled: true
springdoc:
swagger-ui:
path: /swagger-ui.html
logging:
level:
pe.edu.upeu.auth: DEBUG
management:
endpoints:
web:
exposure:
include: health,info,metrics,prometheus
endpoint:
health:
show-details: always
eureka:
instance:
hostname: localhost
instance-id: ${spring.application.name}:${server.port}
client:
service-url:
defaultZone: http://localhost:18761/eureka
jwt:
issuer: http://localhost:8085
expiracion-segundos: 3600
Mismo patrón exacto de pagatu-orden-ms-dev.yml (S6) — ddl-auto: validate porque el esquema real lo define Flyway (3.3), no Hibernate. jwt.issuer y jwt.expiracion-segundos no los lee nada todavía: los consume el servicio de JWT de 3.11. Se declaran ahora para dejar toda la configuración de pagatu-auth-ms en un solo archivo, de una vez. jwt.expiracion-segundos: 3600 es una hora, deliberadamente larga solo para no complicar las pruebas manuales de hoy (2.2, Error frecuente). No hay ningún secreto compartido en config-repo: ni el Gateway ni pagatu-orden-ms necesitan conocer nada que permita fabricar un token — solo saber de dónde descargar la clave pública (3.17, 3.21). Esa es la ventaja concreta de la firma asimétrica (2.5).
infra/pagatu-config/config-repo/pagatu-auth-ms-prod.yml:
server:
port: 8080
spring:
datasource:
url: jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_NAME}
username: ${DB_USER}
password: ${DB_PASS}
driver-class-name: org.postgresql.Driver
flyway:
enabled: true
locations: classpath:db/migration
jpa:
hibernate:
ddl-auto: validate
show-sql: false
properties:
hibernate:
format_sql: false
springdoc:
swagger-ui:
enabled: false
api-docs:
enabled: false
management:
endpoints:
web:
exposure:
include: health,info,metrics,prometheus
endpoint:
health:
show-details: never
eureka:
instance:
instance-id: ${spring.application.name}:${random.value}
client:
service-url:
defaultZone: http://pagatu-eureka:8761/eureka
jwt:
issuer: http://pagatu-auth-ms:8080
expiracion-segundos: 900
Mismo patrón que pagatu-orden-ms-prod.yml (S3, S6). Lo que cambia frente a DEV: el puerto interno del contenedor (8080), las credenciales de la base de datos por variables de entorno (nunca escritas en el repositorio), Swagger y el SQL (Structured Query Language) en el log apagados, el detalle de health oculto, un instance-id aleatorio por réplica, y la dirección de Eureka por el nombre del contenedor. Y dos valores propios de este servicio: jwt.issuer apunta al nombre del contenedor dentro de la red de Docker, y jwt.expiracion-segundos: 900 (15 minutos) es el valor corto que un sistema real necesita (2.2, Error frecuente) — la hora de DEV es solo para las pruebas manuales de hoy. Hoy pagatu-auth-ms no se levanta en PROD; el archivo queda listo, igual que los de los demás servicios.
Verifica que el Config Server sirve los dos archivos antes de continuar (dev y prod):
PowerShell:
Invoke-RestMethod -Method Get -Uri "http://localhost:18888/pagatu-auth-ms/dev"
Invoke-RestMethod -Method Get -Uri "http://localhost:18888/pagatu-auth-ms/prod"
bash macOS/Linux:
curl http://localhost:18888/pagatu-auth-ms/dev
curl http://localhost:18888/pagatu-auth-ms/prod
Si propertySources sale sin ningún jwt.issuer, no continúes. Confirma que el archivo se llama exactamente pagatu-auth-ms-dev.yml (o -prod.yml), está directamente en config-repo/ (no en una subcarpeta), y que pagatu-config lo recargó (reinicia pagatu-config si hace falta).
Arranca pagatu-auth-ms — todavía sin ninguna clase propia (las entidades llegan en 3.8). Con pagatu-config, pagatu-eureka y la base de datos de 3.2 corriendo:
PowerShell:
cd services/pagatu-auth-ms
.\mvnw.cmd spring-boot:run
bash macOS/Linux:
cd services/pagatu-auth-ms
./mvnw spring-boot:run
El log debe mostrar tres cosas: que la configuración viene del Config Server (Fetching config from server at : http://localhost:18888), que Flyway ejecutó V1__create_usuarios_roles.sql (Successfully applied 1 migration), y que la aplicación quedó arriba en el puerto 8085. Comprueba las tablas, ahora sí:
docker exec -it pagatu-postgres-auth-dev psql -U pagatu -d pagatu_auth_db -c "\dt"
Resultado esperado: roles, usuarios, usuario_roles y flyway_schema_history — frente al No relations found. de 3.2. Comprueba también los datos semilla de 3.3 (el mismo comando sirve en PowerShell y en bash):
docker exec -it pagatu-postgres-auth-dev psql -U pagatu -d pagatu_auth_db -c "SELECT id, email, habilitado, id_cliente FROM usuarios ORDER BY id;"
Resultado esperado — dos filas: admin@pagatu.com con id_cliente vacío, y cliente@pagatu.com con id_cliente 1, ambos con habilitado en t. Y en http://localhost:18761 (Eureka), PAGATU-AUTH-MS aparece registrada.
Dos líneas del log que no son errores: Using generated security password: ... (Spring Security todavía sin configurar; se resuelve en 3.13) y la ausencia de cualquier mensaje sobre entidades (Hibernate no tiene ninguna que validar todavía). Deja pagatu-auth-ms corriendo: en 3.6 lo alcanzas a través del Gateway.
No pruebes el login en el navegador todavía. Si abres http://localhost:8085 ves el formulario Please sign in de Spring Security: es el de por defecto, y solo acepta el usuario user con la contraseña generada que aparece en el log. admin@pagatu.com no funciona ahí porque los usuarios de la base de datos recién se conectan a Spring Security en 3.10, y el login real no es ese formulario sino un POST con JSON a /api/v1/auth/login (3.14).
3.6 Agregar la ruta de pagatu-auth-ms al Gateway¶
Producto del paso: el Gateway enruta /api/v1/auth/** hacia pagatu-auth-ms, y ya llegas a él por el punto único de acceso — antes de que exista una sola clase.
infra/pagatu-config/config-repo/pagatu-gateway-dev.yml — agrega esta ruta a la lista que ya existe desde S4 (no reemplaces las otras):
- id: pagatu-auth-login
uri: lb://pagatu-auth-ms
predicates:
- Path=/api/v1/auth/**
infra/pagatu-config/config-repo/pagatu-gateway-prod.yml — la misma ruta, en la misma lista:
- id: pagatu-auth-login
uri: lb://pagatu-auth-ms
predicates:
- Path=/api/v1/auth/**
Por esta ruta pasa solo el login. La descarga de claves públicas (/.well-known/jwks.json) no pasa por el Gateway: el Gateway (y pagatu-orden-ms, 3.21) la piden directo a pagatu-auth-ms, tal como quedará en jwk-set-uri (3.17).
Con pagatu-auth-ms corriendo (3.5), reinicia pagatu-gateway — lee sus rutas al arrancar — y llama a pagatu-auth-ms a través de él:
PowerShell:
curl.exe -i http://localhost:18080/api/v1/auth/login
bash macOS/Linux:
curl -i http://localhost:18080/api/v1/auth/login
Resultado esperado: una respuesta de Spring Security de pagatu-auth-ms, no del Gateway. Si abres la URL en el navegador, te redirige a http://localhost:8085/login (el formulario por defecto, 302); con curl verás un 302 hacia /login o un 401, según el Accept de la petición. El endpoint de login real es un POST (3.12), así que aquí solo compruebas que la ruta llega hasta pagatu-auth-ms; el login completo a través del Gateway lo pruebas en 3.14. Las tres respuestas prueban que la ruta funciona: la petición atravesó el Gateway y llegó hasta pagatu-auth-ms, cuya seguridad todavía está sin configurar (se resuelve en 3.13). Un 404 significa que el Gateway no encontró la ruta (revisa que la agregaste a la lista routes y reiniciaste el Gateway), y un 503, que no encontró ninguna instancia de pagatu-auth-ms en Eureka. Detén pagatu-auth-ms con Ctrl+C antes de seguir; el Gateway puede quedar corriendo. pagatu-auth-ms no se vuelve a levantar hasta 3.14, después de escribir todas sus clases.
3.7 Crear el manejador de errores y el filtro de trazabilidad¶
Producto del paso: pagatu-auth-ms con el mismo manejo de errores y la misma trazabilidad por petición que ya tienen pagatu-catalogo-ms (S1) y pagatu-orden-ms (S6).
Son clases compartidas: no dependen de ninguna entidad, y todo lo que se escriba después en pagatu-auth-ms las reutiliza. Por eso van antes de las entidades, en el mismo lugar del recorrido donde S6 las puso en pagatu-orden-ms. Son una copia de las de pagatu-orden-ms (exception/, filter/ y logback-spring.xml); lo único que cambia es el nombre del artefacto: el paquete pe.edu.upeu.orden pasa a pe.edu.upeu.auth y el archivo de log, de orden.log a auth.log.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/exception/ResourceNotFoundException.java:
package pe.edu.upeu.auth.exception;
public class ResourceNotFoundException extends RuntimeException {
public ResourceNotFoundException(String mensaje) {
super(mensaje);
}
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/exception/GlobalExceptionHandler.java:
package pe.edu.upeu.auth.exception;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.time.Instant;
import java.util.HashMap;
import java.util.Map;
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<Map<String, Object>> handleNotFound(ResourceNotFoundException ex) {
Map<String, Object> body = new HashMap<>();
body.put("timestamp", Instant.now().toString());
body.put("status", HttpStatus.NOT_FOUND.value());
body.put("error", "Not Found");
body.put("message", ex.getMessage());
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(body);
}
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<Map<String, Object>> handleValidation(MethodArgumentNotValidException ex) {
Map<String, Object> body = new HashMap<>();
body.put("timestamp", Instant.now().toString());
body.put("status", HttpStatus.BAD_REQUEST.value());
body.put("error", "Bad Request");
body.put("message", "Error de validación en los datos enviados");
return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(body);
}
}
El manejador de validación responde cuando @Valid rechaza un LoginRequest (email vacío o sin formato, 3.9). El de credenciales inválidas, propio de este servicio, se agrega en 3.12, donde se lanza esa excepción.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/filter/CorrelationIdFilter.java:
package pe.edu.upeu.auth.filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.util.UUID;
@Component
public class CorrelationIdFilter extends OncePerRequestFilter {
public static final String TRACE_ID_HEADER = "X-Trace-ID";
public static final String MDC_KEY = "traceId";
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
String traceId = request.getHeader(TRACE_ID_HEADER);
if (traceId == null || traceId.isBlank()) {
traceId = UUID.randomUUID().toString();
}
try {
MDC.put(MDC_KEY, traceId);
response.setHeader(TRACE_ID_HEADER, traceId);
filterChain.doFilter(request, response);
} finally {
MDC.remove(MDC_KEY);
}
}
}
Mismo filtro que S1 y S6: agrega un identificador de trazabilidad a cada petición con el header X-Trace-ID — si el cliente no lo envía, genera un UUID.
services/pagatu-auth-ms/src/main/resources/logback-spring.xml — salida por consola y por archivo en logs/auth.log:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<include resource="org/springframework/boot/logging/logback/defaults.xml"/>
<property name="LOG_PATTERN"
value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{traceId}] %-5level %logger{36} - %msg%n"/>
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>${LOG_PATTERN}</pattern>
</encoder>
</appender>
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>logs/auth.log</file>
<encoder>
<pattern>${LOG_PATTERN}</pattern>
</encoder>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>logs/auth-%d{yyyy-MM-dd}.log</fileNamePattern>
<maxHistory>7</maxHistory>
</rollingPolicy>
</appender>
<root level="INFO">
<appender-ref ref="CONSOLE"/>
<appender-ref ref="FILE"/>
</root>
</configuration>
El traceId identifica una petición dentro de pagatu-auth-ms; no viaja todavía entre servicios, igual que en S6.
3.8 Crear las entidades Usuario y Rol¶
Producto del paso: mapeo JPA de las tres tablas.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/entity/Rol.java:
package pe.edu.upeu.auth.entity;
import jakarta.persistence.*;
import lombok.*;
@Entity
@Table(name = "roles")
@Getter
@Setter
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Rol {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, unique = true, length = 50)
private String nombre;
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/entity/Usuario.java:
package pe.edu.upeu.auth.entity;
import jakarta.persistence.*;
import lombok.*;
import java.util.HashSet;
import java.util.Set;
@Entity
@Table(name = "usuarios")
@Getter
@Setter
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Usuario {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, unique = true, length = 150)
private String email;
@Column(nullable = false, length = 100)
private String password;
@Column(nullable = false)
@Builder.Default
private boolean habilitado = true;
@Column(name = "id_cliente")
private Long idCliente;
@ManyToMany(fetch = FetchType.EAGER)
@JoinTable(
name = "usuario_roles",
joinColumns = @JoinColumn(name = "usuario_id"),
inverseJoinColumns = @JoinColumn(name = "rol_id")
)
@Builder.Default
private Set<Rol> roles = new HashSet<>();
}
fetch = FetchType.EAGER porque los roles se necesitan siempre que se carga un usuario (para armar el JWT y las autoridades de Spring Security), y son pocos — es uno de los pocos casos donde traerlos de una vez es lo correcto. idCliente es null para un usuario ADMIN (no representa a ningún cliente) y tiene valor para un usuario CLIENTE — ese valor es el que viaja dentro del JWT y el que pagatu-orden-ms va a leer en la Parte C, en vez de confiar en el que el request declare.
3.9 Crear los DTO de login¶
Producto del paso: contrato de entrada/salida del endpoint de login.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/dto/LoginRequest.java:
package pe.edu.upeu.auth.dto;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import lombok.*;
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class LoginRequest {
@NotBlank
@Email
private String email;
@NotBlank
private String password;
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/dto/LoginResponse.java:
package pe.edu.upeu.auth.dto;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.*;
@Getter
@Builder
@AllArgsConstructor
public class LoginResponse {
@JsonProperty("access_token")
private String accessToken;
@JsonProperty("token_type")
private String tokenType;
@JsonProperty("expires_in")
private long expiresIn;
}
Los nombres access_token, token_type y expires_in (este último en segundos) no son casualidad: son los del estándar OAuth 2.0 (2.4), los mismos que devuelve el token endpoint de Keycloak. Un cliente que hoy lee esta respuesta no necesita cambiar cómo interpreta el token el día que llegue Keycloak. tokenType siempre vale "Bearer" (3.12) — así el cliente sabe exactamente cómo debe mandar el token de vuelta: Authorization: Bearer <token>.
3.10 Crear el repositorio y el servicio que carga usuarios en Spring Security¶
Producto del paso: Spring Security sabe buscar un usuario por su email y traducir sus roles a autoridades — la pieza que hace posible AuthenticationManager en 3.12.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/repository/UsuarioRepository.java:
package pe.edu.upeu.auth.repository;
import pe.edu.upeu.auth.entity.Usuario;
import org.springframework.data.jpa.repository.JpaRepository;
import java.util.Optional;
public interface UsuarioRepository extends JpaRepository<Usuario, Long> {
Optional<Usuario> findByEmail(String email);
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/service/UsuarioDetailsService.java:
package pe.edu.upeu.auth.service;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;
import pe.edu.upeu.auth.entity.Usuario;
import pe.edu.upeu.auth.repository.UsuarioRepository;
@Service
@RequiredArgsConstructor
public class UsuarioDetailsService implements UserDetailsService {
private final UsuarioRepository usuarioRepository;
@Override
public UserDetails loadUserByUsername(String email) throws UsernameNotFoundException {
Usuario usuario = usuarioRepository.findByEmail(email)
.orElseThrow(() -> new UsernameNotFoundException("Usuario no encontrado: " + email));
return User.builder()
.username(usuario.getEmail())
.password(usuario.getPassword())
.disabled(!usuario.isHabilitado())
.authorities(usuario.getRoles().stream()
.map(rol -> new SimpleGrantedAuthority("ROLE_" + rol.getNombre()))
.toList())
.build();
}
}
UserDetailsService es el contrato de Spring Security para "cómo se busca un usuario por su nombre de acceso" — aquí, el email. Al existir un único bean de este tipo, Spring Security arma solo el resto de la cadena: un proveedor de autenticación que llama a este método, compara la contraseña recibida contra el hash con el PasswordEncoder (3.13) y falla si no coinciden. Es la maquinaria estándar de Spring Security, no código propio de comparar contraseñas — y es la que el proyecto reemplaza por completo con Keycloak (Tabla 6). Aquí sí se agrega el prefijo ROLE_: es lo que espera hasRole(...) (3.18).
3.11 Generar las claves RSA y crear el servicio de JWT¶
Producto del paso: un par de claves RSA en memoria, y el servicio que firma un JWT con la clave privada.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/config/JwtKeyConfig.java:
package pe.edu.upeu.auth.config;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jose.jwk.source.ImmutableJWKSet;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;
import java.util.UUID;
@Configuration
public class JwtKeyConfig {
@Bean
public RSAKey rsaKey() throws Exception {
KeyPairGenerator generador = KeyPairGenerator.getInstance("RSA");
generador.initialize(2048);
KeyPair par = generador.generateKeyPair();
return new RSAKey.Builder((RSAPublicKey) par.getPublic())
.privateKey((RSAPrivateKey) par.getPrivate())
.keyID(UUID.randomUUID().toString())
.build();
}
@Bean
public JwtEncoder jwtEncoder(RSAKey rsaKey) {
return new NimbusJwtEncoder(new ImmutableJWKSet<>(new JWKSet(rsaKey)));
}
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/service/JwtService.java:
package pe.edu.upeu.auth.service;
import com.nimbusds.jose.jwk.RSAKey;
import lombok.Getter;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
import org.springframework.security.oauth2.jwt.JwsHeader;
import org.springframework.security.oauth2.jwt.JwtClaimsSet;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
import org.springframework.stereotype.Service;
import pe.edu.upeu.auth.entity.Rol;
import pe.edu.upeu.auth.entity.Usuario;
import java.time.Instant;
import java.util.List;
import java.util.Map;
@Service
@RequiredArgsConstructor
public class JwtService {
private final JwtEncoder jwtEncoder;
private final RSAKey rsaKey;
@Value("${jwt.issuer}")
private String issuer;
@Getter
@Value("${jwt.expiracion-segundos}")
private long expiracionSegundos;
public String generarToken(Usuario usuario) {
Instant ahora = Instant.now();
List<String> roles = usuario.getRoles().stream()
.map(Rol::getNombre)
.sorted()
.toList();
JwtClaimsSet.Builder claims = JwtClaimsSet.builder()
.issuer(issuer)
.subject(String.valueOf(usuario.getId()))
.issuedAt(ahora)
.expiresAt(ahora.plusSeconds(expiracionSegundos))
.claim("preferred_username", usuario.getEmail())
.claim("email", usuario.getEmail())
.claim("realm_access", Map.of("roles", roles));
if (usuario.getIdCliente() != null) {
claims.claim("idCliente", usuario.getIdCliente());
}
JwsHeader header = JwsHeader.with(SignatureAlgorithm.RS256)
.keyId(rsaKey.getKeyID())
.build();
return jwtEncoder.encode(JwtEncoderParameters.from(header, claims.build())).getTokenValue();
}
}
Los nombres de los claims no son arbitrarios: iss (emisor), sub (identificador del usuario), exp/iat (vigencia), preferred_username, email y realm_access.roles son los mismos que emite Keycloak (Tabla 6). Por eso el conversor de roles del Gateway (3.17) funcionará tal cual cuando el token lo emita Keycloak. idCliente es un claim propio del proyecto: solo se agrega cuando no es null (un ADMIN no lo necesita).
RS256 firma con la clave privada (rsaKey, que vive solo en este servicio); el encabezado del token lleva el kid para que quien lo reciba sepa con qué clave pública verificarlo (2.5). Esta clave se genera al arrancar el servicio: es suficiente para aprender, pero significa que cada vez que reinicies pagatu-auth-ms, los tokens emitidos antes dejan de verificar. Keycloak persiste y rota sus claves.
3.12 Crear el servicio de autenticación, el controlador y el endpoint de claves públicas¶
Producto del paso: POST /api/v1/auth/login funcional y GET /.well-known/jwks.json publicando la clave pública.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/service/AuthService.java:
package pe.edu.upeu.auth.service;
import pe.edu.upeu.auth.dto.LoginRequest;
import pe.edu.upeu.auth.dto.LoginResponse;
public interface AuthService {
LoginResponse login(LoginRequest request);
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/service/AuthServiceImpl.java:
package pe.edu.upeu.auth.service;
import lombok.RequiredArgsConstructor;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.stereotype.Service;
import pe.edu.upeu.auth.dto.LoginRequest;
import pe.edu.upeu.auth.dto.LoginResponse;
import pe.edu.upeu.auth.entity.Usuario;
import pe.edu.upeu.auth.repository.UsuarioRepository;
@Service
@RequiredArgsConstructor
public class AuthServiceImpl implements AuthService {
private final AuthenticationManager authenticationManager;
private final UsuarioRepository usuarioRepository;
private final JwtService jwtService;
@Override
public LoginResponse login(LoginRequest request) {
authenticationManager.authenticate(
new UsernamePasswordAuthenticationToken(request.getEmail(), request.getPassword()));
Usuario usuario = usuarioRepository.findByEmail(request.getEmail()).orElseThrow();
String token = jwtService.generarToken(usuario);
return LoginResponse.builder()
.accessToken(token)
.tokenType("Bearer")
.expiresIn(jwtService.getExpiracionSegundos())
.build();
}
}
authenticate(...) lanza una excepción si las credenciales no son válidas — nunca devuelve "falso". Si llega a la línea siguiente, el usuario ya está autenticado, y recién ahí se lo vuelve a cargar para armar el JWT con su id, sus roles y su idCliente. Spring Security ya responde igual (BadCredentialsException, mensaje "Bad credentials") tanto si el email no existe como si la contraseña no coincide: no filtra qué emails están registrados, sin que tengas que programarlo.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/exception/GlobalExceptionHandler.java — el manejador de 3.7 gana un tercer método, propio de este servicio, para las credenciales inválidas. Agrega el import de AuthenticationException y este método dentro de la clase:
import org.springframework.security.core.AuthenticationException;
@ExceptionHandler(AuthenticationException.class)
public ResponseEntity<Map<String, String>> handleAuthentication(AuthenticationException ex) {
return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
.body(Map.of("error", "Credenciales invalidas"));
}
El mensaje es fijo, sin importar la causa (contraseña incorrecta, usuario inexistente o cuenta deshabilitada): revelar cuál falló le regala información a quien intenta adivinar credenciales ajenas.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/controller/AuthController.java:
package pe.edu.upeu.auth.controller;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
import pe.edu.upeu.auth.dto.LoginRequest;
import pe.edu.upeu.auth.dto.LoginResponse;
import pe.edu.upeu.auth.service.AuthService;
@RestController
@RequestMapping("/api/v1/auth")
@RequiredArgsConstructor
public class AuthController {
private final AuthService authService;
@PostMapping("/login")
public LoginResponse login(@Valid @RequestBody LoginRequest request) {
return authService.login(request);
}
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/controller/JwksController.java:
package pe.edu.upeu.auth.controller;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
@RestController
@RequiredArgsConstructor
public class JwksController {
private final RSAKey rsaKey;
@GetMapping("/.well-known/jwks.json")
public Map<String, Object> jwks() {
return new JWKSet(rsaKey.toPublicJWK()).toJSONObject();
}
}
toPublicJWK() descarta la parte privada: este endpoint solo puede exponer la clave pública. Es el equivalente a /realms/{realm}/protocol/openid-connect/certs de Keycloak (Tabla 6) — la URL a la que el Gateway y pagatu-orden-ms van a ir a descargar la clave para verificar firmas.
No levantes el servicio todavía: AuthServiceImpl inyecta un AuthenticationManager que recién se declara como bean en 3.13, y sin él el arranque falla. Con 3.13 escrito, el servicio ya está completo y se prueba en 3.14.
3.13 Configurar Spring Security en pagatu-auth-ms¶
Producto del paso: /api/v1/auth/login y /.well-known/jwks.json accesibles sin autenticación previa (tiene sentido: nadie tiene un JWT todavía antes de hacer login, y la clave pública es pública por definición), y el PasswordEncoder y el AuthenticationManager disponibles para inyectar.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/config/SecurityConfig.java:
package pe.edu.upeu.auth.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
@Configuration
public class SecurityConfig {
@Bean
public PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder();
}
@Bean
public AuthenticationManager authenticationManager(AuthenticationConfiguration configuration) throws Exception {
return configuration.getAuthenticationManager();
}
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.csrf(csrf -> csrf.disable())
.sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.authorizeHttpRequests(auth -> auth.anyRequest().permitAll())
.httpBasic(basic -> basic.disable())
.formLogin(form -> form.disable());
return http.build();
}
}
SessionCreationPolicy.STATELESS le indica a Spring Security que no cree ninguna sesión HTTP: cada petición se valida por sí sola (2.2). csrf se desactiva porque esa protección existe para sesiones con cookies — sin cookies de sesión, no hay nada que proteger. pagatu-auth-ms solo expone endpoints públicos (login, claves, health), por eso permitAll().
Error frecuente: agregar spring-boot-starter-security al pom.xml y no declarar ningún SecurityFilterChain propio. Spring Security se autoconfigura por defecto en cuanto detecta la dependencia — bloquea todo con un formulario de login y una contraseña generada al azar (visible en el log de arranque), en vez de dejar pasar libremente /api/v1/auth/login. Este SecurityFilterChain explícito reemplaza esa configuración por defecto.
3.14 Levantar y probar pagatu-auth-ms de punta a punta¶
Producto del paso: login real, con un JWT firmado, y la clave pública publicada.
PowerShell:
cd services/pagatu-auth-ms
.\mvnw.cmd spring-boot:run
bash macOS/Linux:
cd services/pagatu-auth-ms
./mvnw spring-boot:run
Prueba con el usuario ADMIN semilla (3.3):
PowerShell:
Invoke-RestMethod -Method Post -Uri "http://localhost:8085/api/v1/auth/login" `
-ContentType "application/json" `
-Body '{"email": "admin@pagatu.com", "password": "admin123"}' | ConvertTo-Json
ConvertTo-Json hace que PowerShell muestre la respuesta completa: sin él, el token largo llena la tabla y token_type y expires_in no se ven.
bash macOS/Linux:
curl -X POST http://localhost:8085/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "admin@pagatu.com", "password": "admin123"}'
Resultado esperado — 200 OK:
{
"access_token": "eyJraWQiOiI0ZjJi...",
"token_type": "Bearer",
"expires_in": 3600
}
Prueba también con una contraseña incorrecta y confirma 401 Unauthorized con {"error": "Credenciales invalidas"} — el manejador de 3.12 en acción. Guarda el access_token del ADMIN y repite el login con cliente@pagatu.com / cliente123 — vas a necesitar ambos tokens en 3.19 y 3.23.
Desde el navegador, con Swagger UI. El login es un POST, y el navegador solo sabe hacer GET al escribir una URL; para probarlo sin comandos, abre http://localhost:8085/swagger-ui.html, despliega POST /api/v1/auth/login, pulsa Try it out, reemplaza los valores de ejemplo ("string") por admin@pagatu.com / admin123 y pulsa Execute. La respuesta debe ser el mismo 200 con el access_token.
Con Postman. Crea una petición POST a http://localhost:8085/api/v1/auth/login; en Body → raw → JSON pega {"email": "admin@pagatu.com", "password": "admin123"} y pulsa Send. Para no copiar el token a mano después, abre la pestaña Scripts → Post-response (en versiones anteriores de Postman, Tests) y guárdalo en una variable de colección:
pm.collectionVariables.set("tokenAdmin", pm.response.json().access_token);
Duplica la petición, cambia el cuerpo a cliente@pagatu.com / cliente123 y el script a pm.collectionVariables.set("tokenCliente", pm.response.json().access_token);. Las peticiones de 3.19 y 3.23 usan {{tokenAdmin}} y {{tokenCliente}} en la pestaña Authorization.
El mismo login, ahora a través del Gateway (la ruta de 3.6). Con pagatu-eureka y pagatu-gateway corriendo, repite el POST contra el puerto del Gateway — la respuesta debe ser idéntica, porque el Gateway solo reenvía la petición:
PowerShell:
Invoke-RestMethod -Method Post -Uri "http://localhost:18080/api/v1/auth/login" `
-ContentType "application/json" `
-Body '{"email": "admin@pagatu.com", "password": "admin123"}' | ConvertTo-Json
bash macOS/Linux:
curl -X POST http://localhost:18080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "admin@pagatu.com", "password": "admin123"}'
Ahora comprueba que la clave pública está publicada:
PowerShell:
Invoke-RestMethod -Method Get -Uri "http://localhost:8085/.well-known/jwks.json" | ConvertTo-Json -Depth 5
bash macOS/Linux:
curl http://localhost:8085/.well-known/jwks.json
Resultado esperado: un documento con una lista keys, y en ella una sola clave RSA con sus campos kty, e, n y kid — sin ningún campo privado (d, p, q).
Inspecciona el token en jwt.io. Copia el access_token completo del ADMIN, pégalo en jwt.io y comprueba dos cosas. En el encabezado: "alg": "RS256" y un kid igual al de /.well-known/jwks.json — así es como el receptor sabe con qué clave verificar. En el payload: los claims deben verse así para admin@pagatu.com (jwt.io los muestra en el orden en que el servidor los serializó, que puede variar; exp es iat más 3600 segundos):
{
"sub": "1",
"realm_access": { "roles": ["ADMIN"] },
"iss": "http://localhost:8085",
"preferred_username": "admin@pagatu.com",
"exp": 1790309565,
"iat": 1790305965,
"email": "admin@pagatu.com"
}
y, para cliente@pagatu.com, el mismo formato con "realm_access": { "roles": ["CLIENTE"] } más "idCliente": 1. Para comprobar también la firma, pega en el campo de clave pública de jwt.io la clave del endpoint de claves (el objeto que está dentro de keys, en formato JWK, JSON Web Key): debe aparecer Signature Verified. Es exactamente lo que harán el Gateway y pagatu-orden-ms. Si jwt.io muestra Unable to retrieve public key from issuer… Expected a valid HTTPS URL, es normal: intenta descargar la clave desde el iss, pero ese iss es http://localhost:8085 (no HTTPS, la versión segura de HTTP), por eso la clave se pega a mano. jwt.io solo lee los claims; nunca pegues ahí un token de un sistema real.
3.15 Agregar el registro de usuarios y probarlo con Swagger¶
Producto del paso: POST /api/v1/auth/registro crea un usuario nuevo con rol CLIENTE, y ese usuario ya puede iniciar sesión.
Hasta ahora pagatu-auth-ms solo tiene los dos usuarios semilla de 3.3, cuyos hashes venían calculados. Este endpoint muestra de dónde sale un hash BCrypt en un sistema real: lo genera el propio servicio con el PasswordEncoder (3.13) al guardar el usuario.
Decisión de diseño: el cuerpo del request trae solo email y password. El rol lo fija el servidor en CLIENTE y idCliente queda en null. Si el request pudiera declarar el rol o el idCliente, cualquiera se registraría como ADMIN o se haría pasar por el cliente 1 — el mismo problema de 1.6.1 que esta sesión viene a cerrar. El vínculo de un usuario con un cliente real llega con pagatu-cliente-ms (trabajo autónomo, al final de la guía).
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/dto/RegistroRequest.java:
package pe.edu.upeu.auth.dto;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import lombok.*;
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class RegistroRequest {
@NotBlank
@Email
@Size(max = 150)
private String email;
@NotBlank
@Size(min = 8, max = 72)
private String password;
}
max = 72 es el límite de BCrypt (72 bytes); max = 150 en el email coincide con la columna de 3.3.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/dto/RegistroResponse.java:
package pe.edu.upeu.auth.dto;
import lombok.*;
@Getter
@Builder
@AllArgsConstructor
public class RegistroResponse {
private Long id;
private String email;
}
La respuesta no devuelve la contraseña ni su hash.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/exception/EmailYaRegistradoException.java:
package pe.edu.upeu.auth.exception;
public class EmailYaRegistradoException extends RuntimeException {
public EmailYaRegistradoException(String email) {
super("El email ya está registrado: " + email);
}
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/repository/RolRepository.java:
package pe.edu.upeu.auth.repository;
import pe.edu.upeu.auth.entity.Rol;
import org.springframework.data.jpa.repository.JpaRepository;
import java.util.Optional;
public interface RolRepository extends JpaRepository<Rol, Long> {
Optional<Rol> findByNombre(String nombre);
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/service/AuthService.java — reemplaza el contenido de 3.12:
package pe.edu.upeu.auth.service;
import pe.edu.upeu.auth.dto.LoginRequest;
import pe.edu.upeu.auth.dto.LoginResponse;
import pe.edu.upeu.auth.dto.RegistroRequest;
import pe.edu.upeu.auth.dto.RegistroResponse;
public interface AuthService {
LoginResponse login(LoginRequest request);
RegistroResponse registrar(RegistroRequest request);
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/service/AuthServiceImpl.java — reemplaza el contenido de 3.12 (el método login no cambia; se agregan registrar y dos dependencias):
package pe.edu.upeu.auth.service;
import lombok.RequiredArgsConstructor;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import pe.edu.upeu.auth.dto.LoginRequest;
import pe.edu.upeu.auth.dto.LoginResponse;
import pe.edu.upeu.auth.dto.RegistroRequest;
import pe.edu.upeu.auth.dto.RegistroResponse;
import pe.edu.upeu.auth.entity.Rol;
import pe.edu.upeu.auth.entity.Usuario;
import pe.edu.upeu.auth.exception.EmailYaRegistradoException;
import pe.edu.upeu.auth.repository.RolRepository;
import pe.edu.upeu.auth.repository.UsuarioRepository;
import java.util.HashSet;
import java.util.Set;
@Service
@RequiredArgsConstructor
public class AuthServiceImpl implements AuthService {
private final AuthenticationManager authenticationManager;
private final UsuarioRepository usuarioRepository;
private final RolRepository rolRepository;
private final PasswordEncoder passwordEncoder;
private final JwtService jwtService;
@Override
public LoginResponse login(LoginRequest request) {
authenticationManager.authenticate(
new UsernamePasswordAuthenticationToken(request.getEmail(), request.getPassword()));
Usuario usuario = usuarioRepository.findByEmail(request.getEmail()).orElseThrow();
String token = jwtService.generarToken(usuario);
return LoginResponse.builder()
.accessToken(token)
.tokenType("Bearer")
.expiresIn(jwtService.getExpiracionSegundos())
.build();
}
@Override
@Transactional
public RegistroResponse registrar(RegistroRequest request) {
if (usuarioRepository.findByEmail(request.getEmail()).isPresent()) {
throw new EmailYaRegistradoException(request.getEmail());
}
Rol rolCliente = rolRepository.findByNombre("CLIENTE").orElseThrow();
Usuario usuario = usuarioRepository.save(Usuario.builder()
.email(request.getEmail())
.password(passwordEncoder.encode(request.getPassword()))
.roles(new HashSet<>(Set.of(rolCliente)))
.build());
return RegistroResponse.builder()
.id(usuario.getId())
.email(usuario.getEmail())
.build();
}
}
passwordEncoder.encode(...) es la única línea que toca la contraseña en texto plano: lo que se guarda es el hash. El rol CLIENTE se busca por nombre en la tabla roles de 3.3, nunca se toma del request. @Transactional hace que el usuario y su fila en usuario_roles se guarden juntos o no se guarde ninguno.
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/controller/AuthController.java — agrega estos tres import y el método dentro de la clase:
import org.springframework.http.HttpStatus;
import pe.edu.upeu.auth.dto.RegistroRequest;
import pe.edu.upeu.auth.dto.RegistroResponse;
@PostMapping("/registro")
@ResponseStatus(HttpStatus.CREATED)
public RegistroResponse registro(@Valid @RequestBody RegistroRequest request) {
return authService.registrar(request);
}
services/pagatu-auth-ms/src/main/java/pe/edu/upeu/auth/exception/GlobalExceptionHandler.java — agrega este método dentro de la clase (mismo formato que handleNotFound):
@ExceptionHandler(EmailYaRegistradoException.class)
public ResponseEntity<Map<String, Object>> handleEmailYaRegistrado(EmailYaRegistradoException ex) {
Map<String, Object> body = new HashMap<>();
body.put("timestamp", Instant.now().toString());
body.put("status", HttpStatus.CONFLICT.value());
body.put("error", "Conflict");
body.put("message", ex.getMessage());
return ResponseEntity.status(HttpStatus.CONFLICT).body(body);
}
/api/v1/auth/registro ya queda público sin tocar SecurityConfig (3.13): permitAll() cubre todo el servicio, y la regla del Gateway para /api/v1/auth/** (3.18) deja pasar el registro igual que el login.
Pruébalo con Swagger. Reinicia pagatu-auth-ms (Ctrl+C y de nuevo .\mvnw.cmd spring-boot:run, o ./mvnw spring-boot:run en macOS/Linux) y abre http://localhost:8085/swagger-ui.html:
- Despliega
POST /api/v1/auth/registro, pulsa Try it out, escribe{"email": "nuevo@pagatu.com", "password": "nuevo12345"}y pulsa Execute. Resultado esperado:201con{"id": 3, "email": "nuevo@pagatu.com"}. - Pulsa Execute otra vez con el mismo cuerpo:
409con el mensajeEl email ya está registrado: nuevo@pagatu.com. - Cambia la contraseña por
abcy ejecuta:400,Error de validación en los datos enviados. - Con
POST /api/v1/auth/loginy las credenciales denuevo@pagatu.com, obtén un200conaccess_token. Pega el token en jwt.io:"realm_access": { "roles": ["CLIENTE"] }y sin claimidCliente.
Y comprueba en la base de datos que se guardó el hash, no la contraseña (el mismo comando sirve en PowerShell y en bash):
docker exec -it pagatu-postgres-auth-dev psql -U pagatu -d pagatu_auth_db -c "SELECT id, email, LEFT(password, 7) AS prefijo_hash, id_cliente FROM usuarios ORDER BY id;"
Resultado esperado: tres filas; la de nuevo@pagatu.com tiene prefijo_hash $2a$10$ (el prefijo BCrypt de Spring, costo 10) y id_cliente vacío. Un usuario así no puede crear órdenes: pagatu-orden-ms exige un idCliente en el token (Parte C).
Antes de la Parte B: comprueba que hoy nada está protegido. pagatu-auth-ms ya emite tokens, pero ningún servicio los exige todavía. Con pagatu-orden-ms y pagatu-gateway corriendo, llama a las órdenes sin ninguna credencial, primero directo al puerto de pagatu-orden-ms y luego por el Gateway:
PowerShell:
Invoke-RestMethod -Method Get -Uri "http://localhost:8082/api/v1/ordenes"
Invoke-RestMethod -Method Get -Uri "http://localhost:18080/api/v1/ordenes"
bash macOS/Linux:
curl -i http://localhost:8082/api/v1/ordenes
curl -i http://localhost:18080/api/v1/ordenes
Resultado esperado: 200 OK en las dos, sin haber mandado ningún token — así de abierto está hoy el sistema (1.6.1). En 3.19 repites la llamada por el Gateway y, con la Parte B terminada, la misma petición sin token responde 401; en 3.24, el llamado directo al 8082 con un token alterado también responde 401, porque pagatu-orden-ms ya verifica la firma por su cuenta (Parte C).
Parte B — Proteger pagatu-gateway como Resource Server¶
3.16 Agregar la dependencia de OAuth2 Resource Server¶
Producto del paso: pagatu-gateway con capacidad de validar JWT.
infra/pagatu-gateway/pom.xml:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security-oauth2-resource-server</artifactId>
</dependency>
Sin versión explícita — la gestiona spring-boot-starter-parent. Esta dependencia sola ya trae todo lo necesario para descargar las claves públicas, decodificar y validar un JWT (no hace falta agregar spring-boot-starter-security aparte, viene incluida de forma transitiva). En Spring Boot 4 el nombre de este starter cambió: el de Boot 3 (spring-boot-starter-oauth2-resource-server) todavía existe, pero está marcado como obsoleto — usa el nombre nuevo.
3.17 Apuntar el Gateway a las claves públicas y configurar el conversor de roles¶
Producto del paso: pagatu-gateway capaz de verificar la firma de un JWT con la clave pública de pagatu-auth-ms, y de traducir el claim realm_access.roles a roles de Spring Security.
Primero, dile al Gateway dónde están las claves públicas. infra/pagatu-config/config-repo/pagatu-gateway-dev.yml — agrega esta propiedad dentro del bloque spring: que ya existe (no crees un segundo spring: en el mismo archivo — YAML no permite dos claves iguales en el mismo nivel):
spring:
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: http://localhost:8085/.well-known/jwks.json
infra/pagatu-config/config-repo/pagatu-gateway-prod.yml — la misma propiedad, en el mismo bloque spring:, con la dirección de pagatu-auth-ms dentro de la red de Docker (su nombre de contenedor y el puerto interno 8080):
spring:
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: http://pagatu-auth-ms:8080/.well-known/jwks.json
Con solo esa propiedad, Spring Boot arma el decodificador de JWT por su cuenta: descarga el JWKS la primera vez que llega un token, lo guarda en memoria, verifica la firma y la expiración de cada token que recibe. No hay ningún bean JwtDecoder que escribir, ni ningún secreto que configurar. Esta es, además, la única línea que cambia el día que llegue Keycloak (Tabla 6): jwk-set-uri se reemplaza por issuer-uri.
Ahora el conversor. infra/pagatu-gateway/src/main/java/pe/edu/upeu/gateway/config/SecurityConfig.java (primera mitad — el conversor de roles):
package pe.edu.upeu.gateway.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import java.util.Collection;
import java.util.List;
import java.util.Map;
@Configuration
public class SecurityConfig {
@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {
JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
converter.setJwtGrantedAuthoritiesConverter(jwt -> {
Map<String, Object> realmAccess = jwt.getClaimAsMap("realm_access");
Object roles = realmAccess == null ? null : realmAccess.get("roles");
if (!(roles instanceof Collection<?> lista)) {
return List.<GrantedAuthority>of();
}
return lista.stream()
.map(rol -> (GrantedAuthority) new SimpleGrantedAuthority("ROLE_" + rol))
.toList();
});
return converter;
}
// continúa en 3.18
}
El conversor traduce cada elemento de realm_access.roles ("ADMIN") al formato que Spring Security espera para autorizar por rol (ROLE_ADMIN) — sin este conversor, hasRole("ADMIN") (3.18) nunca encontraría ninguna autoridad que coincida, porque Spring Security por defecto busca el claim scope, no realm_access.roles. Como el formato del claim es el mismo que emite Keycloak, este bloque no se toca al migrar (Tabla 6); Keycloak agrega algunos roles propios (offline_access, default-roles-...) que el conversor simplemente traduce también, sin efecto en ninguna regla.
3.18 Proteger las rutas del Gateway por rol¶
Producto del paso: reglas de autorización reales — quién puede hacer qué, por ruta y por método HTTP.
Completa el mismo archivo de 3.17, agregando el SecurityFilterChain:
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http,
JwtAuthenticationConverter jwtAuthenticationConverter) throws Exception {
http
.csrf(csrf -> csrf.disable())
.authorizeHttpRequests(auth -> auth
.requestMatchers("/api/v1/auth/**").permitAll()
.requestMatchers("/actuator/**").permitAll()
.requestMatchers(HttpMethod.GET, "/api/v1/productos/**", "/api/v1/categorias/**").permitAll()
.requestMatchers(HttpMethod.POST, "/api/v1/productos/**", "/api/v1/categorias/**").hasRole("ADMIN")
.requestMatchers(HttpMethod.PUT, "/api/v1/productos/**", "/api/v1/categorias/**").hasRole("ADMIN")
.requestMatchers(HttpMethod.DELETE, "/api/v1/productos/**", "/api/v1/categorias/**").hasRole("ADMIN")
.requestMatchers("/api/v1/ordenes/**").hasAnyRole("CLIENTE", "ADMIN")
.anyRequest().authenticated()
)
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthenticationConverter))
);
return http.build();
}
}
Agrega los imports que faltan (HttpMethod, HttpSecurity, SecurityFilterChain) al inicio del archivo:
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
Lectura de las reglas, en orden (Spring Security aplica la primera que coincide): /api/v1/auth/** y /actuator/** quedan abiertas — nadie tiene JWT antes de hacer login, y el health check no debería depender de tener uno. Consultar el catálogo (GET) es público — cualquiera puede mirar productos sin autenticarse. Modificar el catálogo (POST/PUT/DELETE) exige ROLE_ADMIN. Crear o consultar órdenes exige estar autenticado como CLIENTE o ADMIN. Todo lo demás (anyRequest().authenticated()) exige, como mínimo, un JWT válido — nada queda abierto por accidente, ni siquiera una ruta que esta sesión no previó.
3.19 Probar accesos permitidos y denegados a través del Gateway¶
Producto del paso: evidencia real de los cuatro casos — sin token, con token alterado, con rol incorrecto, con rol correcto.
Reinicia pagatu-gateway (para que lea la propiedad nueva) y levántalo:
PowerShell:
cd infra/pagatu-gateway
.\mvnw.cmd spring-boot:run
bash macOS/Linux:
cd infra/pagatu-gateway
./mvnw spring-boot:run
Cómo probar estos casos. Usa PowerShell o curl como en los bloques de abajo, o Postman. El navegador no sirve aquí: al escribir una URL solo puede hacer un GET sin el encabezado Authorization, así que siempre verías el 401 del caso 1 y nunca podrías mandar un token ni probar un POST. Los casos en Postman están al final de esta sección, en una tabla.
Paso previo — obtén los dos tokens. Haz login con cada usuario semilla a través del Gateway (la ruta de 3.6) y guarda el access_token en una variable. Los casos de abajo y los de 3.23 y 3.24 usan estas variables, así que no copies ni pegues tokens a mano: mantén abierta la misma ventana de terminal (si la cierras, repite este bloque).
PowerShell:
$loginAdmin = Invoke-RestMethod -Method Post -Uri "http://localhost:18080/api/v1/auth/login" `
-ContentType "application/json" `
-Body '{"email": "admin@pagatu.com", "password": "admin123"}'
$tokenAdmin = $loginAdmin.access_token
$loginCliente = Invoke-RestMethod -Method Post -Uri "http://localhost:18080/api/v1/auth/login" `
-ContentType "application/json" `
-Body '{"email": "cliente@pagatu.com", "password": "cliente123"}'
$tokenCliente = $loginCliente.access_token
$tokenAdmin.Substring(0, 20)
bash macOS/Linux (requiere jq):
TOKEN_ADMIN=$(curl -s -X POST http://localhost:18080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "admin@pagatu.com", "password": "admin123"}' | jq -r '.access_token')
TOKEN_CLIENTE=$(curl -s -X POST http://localhost:18080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "cliente@pagatu.com", "password": "cliente123"}' | jq -r '.access_token')
echo "${TOKEN_ADMIN:0:20}"
Resultado esperado: los primeros 20 caracteres de un JWT, que siempre empiezan por eyJ. Si sale vacío, el login falló: revisa que pagatu-auth-ms, pagatu-eureka y pagatu-gateway estén corriendo.
En PowerShell, un 401 o 403 aparece como un error rojo de Invoke-RestMethod. Es la respuesta esperada, no una falla del comando; por eso los casos 1 a 3 usan try/catch y muestran solo el código HTTP.
Caso 1 — sin token, ruta protegida:
PowerShell:
try {
Invoke-RestMethod -Method Get -Uri "http://localhost:18080/api/v1/ordenes"
} catch {
$_.Exception.Response.StatusCode.value__
}
bash macOS/Linux:
curl -i http://localhost:18080/api/v1/ordenes
Resultado esperado: 401 (Unauthorized).
Caso 2 — token con la firma alterada: parte del token del ADMIN y cambia el primer carácter de la firma (la firma es la tercera parte del JWT, la que va después del segundo punto). Se altera ese carácter y no el último porque el último de una firma RS256 solo usa 2 de sus 6 bits, y cambiarlo a veces no modifica la firma.
PowerShell:
$partes = $tokenAdmin.Split('.')
$primera = if ($partes[2][0] -eq 'X') { 'Y' } else { 'X' }
$tokenAlterado = "$($partes[0]).$($partes[1]).$primera$($partes[2].Substring(1))"
try {
Invoke-RestMethod -Method Get -Uri "http://localhost:18080/api/v1/ordenes" `
-Headers @{ Authorization = "Bearer $tokenAlterado" }
} catch {
$_.Exception.Response.StatusCode.value__
}
bash macOS/Linux:
FIRMA="${TOKEN_ADMIN##*.}"
PRIMERA=$([ "${FIRMA:0:1}" = "X" ] && echo Y || echo X)
TOKEN_ALTERADO="${TOKEN_ADMIN%.*}.${PRIMERA}${FIRMA:1}"
curl -i http://localhost:18080/api/v1/ordenes \
-H "Authorization: Bearer $TOKEN_ALTERADO"
Resultado esperado: 401 — el Gateway descargó la clave pública, la firma no coincide con el contenido, y el token se rechaza. Es la prueba de que un JWT no se puede editar (por ejemplo, para cambiar "CLIENTE" por "ADMIN") sin invalidarlo.
Caso 3 — token de CLIENTE, intentando modificar el catálogo (rol incorrecto): el cuerpo lleva todos los campos obligatorios de ProductoRequest, para que el único motivo de rechazo sea el rol.
PowerShell:
try {
Invoke-RestMethod -Method Post -Uri "http://localhost:18080/api/v1/productos" `
-Headers @{ Authorization = "Bearer $tokenCliente" } `
-ContentType "application/json" `
-Body '{"nombre": "Producto de prueba", "descripcion": "Prueba de seguridad", "precio": 10.0, "activo": true, "stock": 5, "categoriaId": 1}'
} catch {
$_.Exception.Response.StatusCode.value__
}
bash macOS/Linux:
curl -i -X POST http://localhost:18080/api/v1/productos \
-H "Authorization: Bearer $TOKEN_CLIENTE" \
-H "Content-Type: application/json" \
-d '{"nombre": "Producto de prueba", "descripcion": "Prueba de seguridad", "precio": 10.0, "activo": true, "stock": 5, "categoriaId": 1}'
Resultado esperado: 403 (Forbidden) — el token es válido (pasó la firma), pero el rol CLIENTE no alcanza para hasRole("ADMIN"). Nota la diferencia con el caso 2: allá no se pudo confirmar quién eres (401); aquí sí, pero no tienes permiso (403, 2.3).
Caso 4 — token de ADMIN, mismo endpoint (rol correcto):
PowerShell:
Invoke-RestMethod -Method Post -Uri "http://localhost:18080/api/v1/productos" `
-Headers @{ Authorization = "Bearer $tokenAdmin" } `
-ContentType "application/json" `
-Body '{"nombre": "Producto de prueba", "descripcion": "Prueba de seguridad", "precio": 10.0, "activo": true, "stock": 5, "categoriaId": 1}'
bash macOS/Linux:
curl -i -X POST http://localhost:18080/api/v1/productos \
-H "Authorization: Bearer $TOKEN_ADMIN" \
-H "Content-Type: application/json" \
-d '{"nombre": "Producto de prueba", "descripcion": "Prueba de seguridad", "precio": 10.0, "activo": true, "stock": 5, "categoriaId": 1}'
Resultado esperado: 201 Created, con el producto creado en la respuesta. El mismo cuerpo que el CLIENTE no pudo enviar en el caso 3 ahora pasa: lo único que cambió es el token. Queda un producto "Producto de prueba" en el catálogo; puedes borrarlo con DELETE /api/v1/productos/{id} y el token del ADMIN.
Los mismos cuatro casos en Postman. Usa las variables tokenAdmin y tokenCliente que guardaste en 3.14 (o repite esos dos logins, esta vez contra http://localhost:18080/api/v1/auth/login). En cada petición, la pestaña Authorization va en tipo Bearer Token y el campo Token recibe la variable, con llaves dobles, sin comillas.
Tabla 8. Los cuatro casos en Postman
| Caso | Método y URL | Authorization | Body (raw → JSON) | Resultado esperado |
|---|---|---|---|---|
| 1 | GET http://localhost:18080/api/v1/ordenes |
No Auth | — | 401 |
| 2 | GET http://localhost:18080/api/v1/ordenes |
Bearer Token: {{tokenAlterado}} |
— | 401 |
| 3 | POST http://localhost:18080/api/v1/productos |
Bearer Token: {{tokenCliente}} |
el cuerpo completo del caso 3 | 403 |
| 4 | POST http://localhost:18080/api/v1/productos |
Bearer Token: {{tokenAdmin}} |
el mismo cuerpo | 201 |
Para el caso 2, en la pestaña Scripts → Pre-request de esa petición, arma el token alterado con el mismo criterio de los bloques de PowerShell y bash (cambiar el primer carácter de la firma):
const partes = pm.collectionVariables.get("tokenAdmin").split(".");
partes[2] = (partes[2][0] === "X" ? "Y" : "X") + partes[2].slice(1);
pm.collectionVariables.set("tokenAlterado", partes.join("."));
Postman muestra el código HTTP arriba a la derecha de la respuesta (Status), sin necesidad de try/catch.
Error frecuente: la variable del token quedó vacía porque el login falló (por ejemplo, pagatu-auth-ms apagado). El header queda como Bearer a secas, y Spring Security lo rechaza como si no hubiera token: un 401 que en realidad es un login que no funcionó. Imprime los primeros caracteres de la variable (paso previo) antes de culpar al Gateway.
Error frecuente: 401 en todas las rutas protegidas, aun con un token recién emitido. Revisa que pagatu-auth-ms esté corriendo (sin él, el Gateway no puede descargar la clave pública), que jwk-set-uri (3.17) tenga el puerto y la ruta exactos, y que no hayas reiniciado pagatu-auth-ms después de pedir el token — el par de claves se regenera al arrancar (3.11), y el token anterior ya no verifica: pide uno nuevo (3.14).
Parte C — pagatu-orden-ms valida el JWT y toma el idCliente de él¶
3.20 Quitar idCliente del DTO de entrada¶
Producto del paso: OrdenRequest ya no acepta idCliente — quien crea una orden ya no puede decidir a nombre de quién.
services/pagatu-orden-ms/src/main/java/pe/edu/upeu/orden/dto/OrdenRequest.java — quita el campo idCliente:
package pe.edu.upeu.orden.dto;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;
import lombok.*;
import java.util.List;
@Getter
@Setter
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class OrdenRequest {
@NotBlank
private String metodoPago;
@NotEmpty
@Valid
private List<DetalleOrdenRequest> detalles;
}
Este es exactamente el cambio que 1.6.1 pedía: idCliente ya no es un dato que el cliente declara sobre sí mismo — 3.22 lo reemplaza por un valor que viene del JWT, imposible de falsificar sin la clave privada de pagatu-auth-ms.
3.21 Convertir pagatu-orden-ms en Resource Server¶
Producto del paso: pagatu-orden-ms valida por su cuenta la firma de cada JWT que recibe, sin depender de que el Gateway ya lo haya hecho.
services/pagatu-orden-ms/pom.xml:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security-oauth2-resource-server</artifactId>
</dependency>
Es exactamente la misma dependencia de 3.16. infra/pagatu-config/config-repo/pagatu-orden-ms-dev.yml — agrega la misma propiedad de 3.17 dentro del bloque spring: existente:
spring:
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: http://localhost:8085/.well-known/jwks.json
infra/pagatu-config/config-repo/pagatu-orden-ms-prod.yml — la misma propiedad, con la dirección de pagatu-auth-ms dentro de la red de Docker:
spring:
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: http://pagatu-auth-ms:8080/.well-known/jwks.json
services/pagatu-orden-ms/src/main/java/pe/edu/upeu/orden/config/SecurityConfig.java:
package pe.edu.upeu.orden.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
@Configuration
public class SecurityConfig {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.csrf(csrf -> csrf.disable())
.authorizeHttpRequests(auth -> auth
.requestMatchers("/actuator/**", "/swagger-ui.html", "/swagger-ui/**", "/v3/api-docs/**").permitAll()
.anyRequest().authenticated()
)
.oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
return http.build();
}
}
pagatu-orden-ms no repite las reglas por rol del Gateway (3.18) — esas son de la primera línea, por ruta. Aquí basta con exigir un token válido: anyRequest().authenticated(). Lo que sí hace esta segunda línea es lo más importante: verificar la firma por sí misma (2.5). Si alguien llama directo a 8082, sin pasar por el Gateway, no obtiene ninguna ventaja (3.24).
/actuator/** queda abierto para que Eureka y las revisiones de health sigan funcionando, y Swagger UI para que la página cargue — pero llamar a POST /api/v1/ordenes desde Swagger ya no funciona sin un token: es exactamente el comportamiento buscado (el caso de 1.6.1). Las llamadas salientes de pagatu-orden-ms a pagatu-catalogo-ms (Feign, S6) no cambian: esta configuración solo protege lo que entra.
Un 401 de este filtro se responde antes de llegar al controlador, así que tu GlobalExceptionHandler de S1/S6 no interviene.
3.22 Actualizar el controlador y el servicio de pagatu-orden-ms¶
Producto del paso: crear() recibe idCliente desde el JWT ya validado, nunca del cuerpo del request.
services/pagatu-orden-ms/src/main/java/pe/edu/upeu/orden/controller/OrdenController.java — el método crear:
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public OrdenResponse crear(@Valid @RequestBody OrdenRequest request,
@AuthenticationPrincipal Jwt jwt) {
Number claimIdCliente = jwt.getClaim("idCliente");
if (claimIdCliente == null) {
throw new IllegalArgumentException("Token sin idCliente: solo un CLIENTE autenticado puede crear ordenes");
}
return ordenService.crear(request, claimIdCliente.longValue());
}
Agrega los imports:
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
@AuthenticationPrincipal Jwt jwt entrega el token ya verificado (3.21) — Spring Security lo dejó en el contexto de seguridad de la petición, así que no hay ningún filtro propio que escribir ni ninguna librería JWT que agregar. El claim se lee como Number (no como Long directo) porque el JSON no distingue entre enteros de distinto tamaño.
services/pagatu-orden-ms/src/main/java/pe/edu/upeu/orden/service/OrdenService.java — actualiza la firma:
OrdenResponse crear(OrdenRequest request, Long idCliente);
services/pagatu-orden-ms/src/main/java/pe/edu/upeu/orden/service/OrdenServiceImpl.java — el método crear, recibiendo idCliente aparte en vez de leerlo de request:
@Override
@Transactional
public OrdenResponse crear(OrdenRequest request, Long idCliente) {
Orden orden = Orden.builder()
.idCliente(idCliente)
.metodoPago(request.getMetodoPago())
.build();
// el resto del método sigue exactamente igual que en S6
Solo cambian la firma del método y esa primera línea del builder() — el resto de crear() (validación de productos vía Feign, cálculo del total, toResponse()) no tiene ninguna relación con idCliente y queda intacto.
El GlobalExceptionHandler que pagatu-orden-ms trae desde S6 solo cubre ResourceNotFoundException y los errores de validación: sin más cambios, la IllegalArgumentException del controlador terminaría en un 500. Agrega este método dentro de la clase en services/pagatu-orden-ms/src/main/java/pe/edu/upeu/orden/exception/GlobalExceptionHandler.java, con el mismo formato de los otros dos:
@ExceptionHandler(IllegalArgumentException.class)
public ResponseEntity<Map<String, Object>> handleIllegalArgument(IllegalArgumentException ex) {
Map<String, Object> body = new HashMap<>();
body.put("timestamp", Instant.now().toString());
body.put("status", HttpStatus.BAD_REQUEST.value());
body.put("error", "Bad Request");
body.put("message", ex.getMessage());
return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(body);
}
Así un token sin idCliente (el del ADMIN semilla) recibe un 400 con el mensaje, no un 500.
3.23 Probar de punta a punta, autenticado como CLIENTE¶
Producto del paso: una orden creada con idCliente tomado del JWT — nunca escrito a mano.
Reinicia pagatu-orden-ms (para que lea la configuración nueva). Con pagatu-config, pagatu-eureka, pagatu-gateway, pagatu-auth-ms, pagatu-catalogo-ms y pagatu-orden-ms corriendo, crea una orden a través del Gateway, con el token de cliente@pagatu.com que guardaste en 3.19 ($tokenCliente en PowerShell, TOKEN_CLIENTE en bash; si cerraste la terminal o reiniciaste pagatu-auth-ms, repite el paso previo de 3.19 para obtener uno nuevo):
PowerShell:
Invoke-RestMethod -Method Post -Uri "http://localhost:18080/api/v1/ordenes" `
-Headers @{ Authorization = "Bearer $tokenCliente" } `
-ContentType "application/json" `
-Body '{"metodoPago": "YAPE_PLIN", "detalles": [{"idProducto": 1, "cantidad": 2}]}'
bash macOS/Linux:
curl -X POST http://localhost:18080/api/v1/ordenes \
-H "Authorization: Bearer $TOKEN_CLIENTE" \
-H "Content-Type: application/json" \
-d '{"metodoPago": "YAPE_PLIN", "detalles": [{"idProducto": 1, "cantidad": 2}]}'
Resultado esperado — 201 Created, con "idCliente": 1 aunque el request nunca lo mencionó:
{
"id": 2,
"idCliente": 1,
"fechaCreacion": "2026-09-20T10:15:00",
"estado": "PENDIENTE_PAGO",
"total": 200.0,
"detalles": [
{ "idProducto": 1, "nombreProducto": "...", "cantidad": 2, "precioUnitario": 100.0, "subtotal": 200.0 }
]
}
Ese idCliente: 1 en la respuesta es la prueba de que hoy funcionó — vino del claim idCliente del JWT (3.3, el usuario semilla cliente@pagatu.com tiene id_cliente: 1), no de nada que el request haya escrito.
Repite el mismo request sin el header Authorization y confirma 401 (ya no llega ni a pagatu-orden-ms, el Gateway lo rechaza primero, 3.19). Repite con el token de admin@pagatu.com: también pasa el Gateway (la regla de 3.18 permite CLIENTE o ADMIN) y el token es válido en pagatu-orden-ms, pero no trae idCliente — el usuario ADMIN semilla no tiene id_cliente asignado (3.3), así que tu IllegalArgumentException (3.22) debería dispararse aquí y devolver 400. Si eso pasa, es el comportamiento esperado, no un bug — confirma que un ADMIN sin idCliente no puede crear una orden a nombre de nadie.
Con Postman. POST http://localhost:18080/api/v1/ordenes, pestaña Authorization en Bearer Token con {{tokenCliente}}, y en Body → raw → JSON el mismo cuerpo de arriba ({"metodoPago": "YAPE_PLIN", "detalles": [{"idProducto": 1, "cantidad": 2}]}). Resultado esperado: 201. Cambia Authorization a {{tokenAdmin}} para el 400 del ADMIN, y a No Auth para el 401.
Con Swagger UI de pagatu-orden-ms. Desde 3.21, GET y POST de http://localhost:8082/swagger-ui.html responden 401 porque Swagger no manda ningún token. Para inyectarlo, declara el esquema de seguridad Bearer en OpenAPI: services/pagatu-orden-ms/src/main/java/pe/edu/upeu/orden/config/OpenApiConfig.java:
package pe.edu.upeu.orden.config;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class OpenApiConfig {
private static final String ESQUEMA_JWT = "bearerAuth";
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
.components(new Components().addSecuritySchemes(ESQUEMA_JWT,
new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")))
.addSecurityItem(new SecurityRequirement().addList(ESQUEMA_JWT));
}
}
Reinicia pagatu-orden-ms. Swagger UI muestra ahora un botón Authorize arriba a la derecha (y un candado en cada endpoint): púlsalo, pega solo el access_token — sin la palabra Bearer, Swagger la agrega — y pulsa Authorize. Desde ahí, Try it out y Execute mandan el encabezado Authorization en cada petición: con el token del CLIENTE, POST /api/v1/ordenes devuelve 201; sin autorizar, 401. El token dura una hora (expiracion-segundos de 3.5): cuando expire, vuelve a hacer login y a pulsar Authorize.
Esto solo cambia la documentación: SecurityConfig (3.21) sigue siendo quien exige el token. Y solo sirve para pagatu-orden-ms en su puerto directo (8082): el Gateway no publica Swagger UI.
3.24 Probar el llamado directo a pagatu-orden-ms, sin pasar por el Gateway¶
Producto del paso: evidencia concreta de por qué pagatu-orden-ms valida el token por su cuenta, en vez de confiar en que "ya pasó por el Gateway".
Llama directo al puerto de pagatu-orden-ms (8082), sin el Gateway de por medio, con un token manipulado a mano:
PowerShell:
Invoke-RestMethod -Method Post -Uri "http://localhost:8082/api/v1/ordenes" `
-Headers @{ Authorization = "Bearer token.invalido.manipulado" } `
-ContentType "application/json" `
-Body '{"metodoPago": "YAPE_PLIN", "detalles": [{"idProducto": 1, "cantidad": 2}]}'
bash macOS/Linux:
curl -i -X POST http://localhost:8082/api/v1/ordenes \
-H "Authorization: Bearer token.invalido.manipulado" \
-H "Content-Type: application/json" \
-d '{"metodoPago": "YAPE_PLIN", "detalles": [{"idProducto": 1, "cantidad": 2}]}'
Resultado esperado: 401 Unauthorized, con un encabezado WWW-Authenticate: Bearer error="invalid_token" — pagatu-orden-ms verificó la firma por sí mismo, falló, y rechazó la petición sin llegar al controlador. Repite sin ningún header Authorization: también 401. Y repite con el token válido de cliente@pagatu.com: 201 Created — lo que autoriza la petición es el token, no el camino por el que llegó.
En DEV este escenario es alcanzable (8082 sigue expuesto al host, S6); en producción local (S4) esta ruta directa ni siquiera existe — pagatu-orden-ms no publica ningún puerto. Pero una defensa que solo funciona si nadie se salta la primera línea no es una defensa: por eso la segunda línea existe aunque hoy "no haga falta".
Contraste: pagatu-catalogo-ms llamado directo. El Gateway protege POST /api/v1/productos (caso 3 de 3.19: 403 para un CLIENTE), pero pagatu-catalogo-ms no es todavía un resource server (2.1): si lo llamas directo por su puerto (8080), sin token y sin pasar por el Gateway, la petición entra.
PowerShell:
Invoke-RestMethod -Method Post -Uri "http://localhost:8080/api/v1/productos" `
-ContentType "application/json" `
-Body '{"nombre": "Producto directo", "descripcion": "Sin pasar por el Gateway", "precio": 10.0, "activo": true, "stock": 5, "categoriaId": 1}'
bash macOS/Linux:
curl -i -X POST http://localhost:8080/api/v1/productos \
-H "Content-Type: application/json" \
-d '{"nombre": "Producto directo", "descripcion": "Sin pasar por el Gateway", "precio": 10.0, "activo": true, "stock": 5, "categoriaId": 1}'
Resultado esperado: 201 Created, sin ningún token — la misma petición que el Gateway rechazó con 403, y que pagatu-orden-ms rechaza con 401 en el llamado directo de arriba. Es la diferencia concreta entre un servicio protegido por su cuenta y uno que depende solo de la primera línea. En producción local (S4) esta ruta no existe porque pagatu-catalogo-ms no publica ningún puerto; proteger el catálogo por su cuenta es el mismo cambio de 3.21, y queda fuera de esta sesión. Borra el producto creado con DELETE /api/v1/productos/{id}, pasando por el Gateway con el token del ADMIN.
Truco de desarrollo: quitar la seguridad de una ruta de forma temporal. Mientras desarrollas, es cómodo mirar un GET en el navegador o en Swagger sin sacar un token cada vez. En vez de desactivar toda la seguridad, abre solo lo que necesitas, con una regla que va antes de la que protege esa ruta: Spring Security aplica la primera regla que coincide (3.18). En qué archivo va depende de por dónde entres, porque el Gateway y pagatu-orden-ms validan cada uno por su cuenta (2.5) y abrir uno no abre el otro:
- Llamas directo a
pagatu-orden-ms(8082): la regla va enSecurityConfigdepagatu-orden-ms. - Llamas a través del Gateway (
18080): la regla va enSecurityConfigdepagatu-gateway. - Quieres ambos caminos abiertos: la regla va en los dos archivos.
services/pagatu-orden-ms/src/main/java/pe/edu/upeu/orden/config/SecurityConfig.java — agrega el import y la línea marcada, antes de anyRequest():
import org.springframework.http.HttpMethod;
.authorizeHttpRequests(auth -> auth
.requestMatchers("/actuator/**", "/swagger-ui.html", "/swagger-ui/**", "/v3/api-docs/**").permitAll()
.requestMatchers(HttpMethod.GET, "/api/v1/ordenes/**").permitAll() // TEMPORAL: quitar antes de commitear
.anyRequest().authenticated()
)
infra/pagatu-gateway/src/main/java/pe/edu/upeu/gateway/config/SecurityConfig.java — la misma línea, antes de la regla hasAnyRole de las órdenes:
.requestMatchers(HttpMethod.GET, "/api/v1/ordenes/**").permitAll() // TEMPORAL: quitar antes de commitear
.requestMatchers("/api/v1/ordenes/**").hasAnyRole("CLIENTE", "ADMIN")
Reinicia el servicio que cambiaste y abre http://localhost:8082/api/v1/ordenes (o http://localhost:18080/api/v1/ordenes) directo en el navegador: responde 200 sin token. Un POST a la misma ruta sigue devolviendo 401, porque la regla abre solo el método GET.
Es una herramienta de trabajo, no parte del sistema: mientras esa línea esté, los resultados esperados de 3.19, 3.23 y 3.24 para los GET de órdenes dejan de cumplirse, y en un sistema real nunca debe llegar a producción ni a un commit. Bórrala apenas termines de mirar lo que necesitabas. Si solo quieres probar desde Swagger, no hace falta tocar código: el botón Authorize de 3.23 lo resuelve.
3.25 Documentar la matriz de roles y accesos¶
Producto del paso: contrato de seguridad documentado — igual que S6 documentó el contrato de un evento, esta sesión documenta el contrato de acceso.
Tabla 9. Matriz de roles y accesos verificada en 3.19 y 3.23
| Ruta | Método | Rol requerido | Sin token | Token ADMIN |
Token CLIENTE |
|---|---|---|---|---|---|
/api/v1/auth/login |
POST | público | 200 |
200 |
200 |
/api/v1/auth/registro |
POST | público | 201 |
201 |
201 |
/api/v1/productos |
GET | público | 200 |
200 |
200 |
/api/v1/productos |
POST | ADMIN |
401 |
201 |
403 |
/api/v1/ordenes |
POST | CLIENTE o ADMIN (idCliente requerido) |
401 |
400 (sin idCliente) |
201 |
/api/v1/ordenes |
GET | CLIENTE o ADMIN |
401 |
200 |
200 |
Parte D — Verificar y entender lo que viene¶
3.26 Revisar los accesos y revocar un rol¶
Producto del paso: una revisión de accesos (access review) hecha sobre el sistema real, la prueba de que quitar un rol revoca el acceso — pero solo en el siguiente login —, y la lista de verificación de errores comunes (2.3, 2.4) completada.
Revisión de accesos. Consulta quién tiene qué rol directamente en la base de datos de pagatu-auth-ms:
docker exec -it pagatu-postgres-auth-dev psql -U pagatu -d pagatu_auth_db -c "SELECT u.email, r.nombre AS rol FROM usuarios u JOIN usuario_roles ur ON ur.usuario_id = u.id JOIN roles r ON r.id = ur.rol_id ORDER BY u.email, r.nombre;"
Resultado esperado — dos filas, una por usuario semilla:
email | rol
--------------------+---------
admin@pagatu.com | ADMIN
cliente@pagatu.com | CLIENTE
(2 rows)
Esta consulta es una revisión de accesos mínima: en una sola mirada dice quién puede qué. En un sistema real se repite de forma periódica y se revoca lo que ya no corresponde.
Revocar un rol. Simula que cliente@pagatu.com deja de ser cliente. Ten a la mano el token de cliente@pagatu.com que guardaste en 3.19 ($tokenCliente en PowerShell, TOKEN_CLIENTE en bash), sin haber reiniciado pagatu-auth-ms desde entonces (3.11), y quítale el rol:
docker exec -it pagatu-postgres-auth-dev psql -U pagatu -d pagatu_auth_db -c "DELETE FROM usuario_roles WHERE usuario_id = (SELECT id FROM usuarios WHERE email = 'cliente@pagatu.com');"
Ahora comprueba dos cosas, ambas a través del Gateway (POST /api/v1/ordenes, como en 3.23):
- Con el token viejo (el de antes de revocar): sigue devolviendo
201 Created. El JWT es stateless (2.2): el token ya emitido lleva el rol adentro y sigue siendo válido hasta que expire — quitar el rol de la base de datos no lo invalida. - Pide un token nuevo (repite el login de
cliente@pagatu.comdel paso previo de 3.19) y pégalo en jwt.io: el claim ahora es"realm_access": { "roles": [] }. Con ese token,POST /api/v1/ordenesdevuelve403 Forbidden— autenticado, pero sin ningún rol que alcance.
Es exactamente la limitación de 2.2 (Error frecuente), vista con datos reales: revocar un rol es inmediato para logins nuevos, pero los tokens vigentes viven hasta su expiración. Por eso jwt.expiracion-segundos debe ser corto en un sistema real.
Deja el sistema como estaba antes de continuar:
docker exec -it pagatu-postgres-auth-dev psql -U pagatu -d pagatu_auth_db -c "INSERT INTO usuario_roles (usuario_id, rol_id) SELECT u.id, r.id FROM usuarios u, roles r WHERE u.email = 'cliente@pagatu.com' AND r.nombre = 'CLIENTE';"
Repite la consulta de revisión y confirma que vuelven a aparecer las dos filas.
Lista de verificación. Compara el sistema de hoy contra los errores comunes de 2.3 y 2.4:
Tabla 10. Lista de verificación de accesos: errores comunes frente al sistema de hoy
| Error común | Cómo se comprueba en pagatu |
Resultado esperado hoy |
|---|---|---|
| Permisos asignados directo a usuarios, en vez de a roles | Revisa usuario_roles (3.3) y las reglas de 3.18: nada se autoriza por usuario |
No ocurre: todo pasa por rol. |
| Roles demasiado amplios | Revisa la Tabla 9: ADMIN puede llamar a /api/v1/ordenes (3.18), aunque sin idCliente termina en 400 (3.23) |
Ocurre en parte: decide si esa ruta debería aceptar solo CLIENTE. |
| Sin revisión periódica de accesos | La consulta de esta sección | Se hace a mano, una vez; en un sistema real sería periódica. |
| Sin registro de auditoría de los rechazos | Log de pagatu-gateway con nivel de seguridad en DEBUG (2.6) |
Solo queda en consola; un audit log real iría a un almacén aparte. |
| Flujo Implicit | Ningún flujo de hoy usa redirects | No ocurre. |
state sin validar |
No hay redirects hoy | No aplica hoy; sí en S11. |
Tokens en localStorage |
El único client de hoy es PowerShell | No aplica hoy; es un riesgo real en S11. |
| Refresh token sin rotación | pagatu-auth-ms no emite refresh token |
No aplica hoy; Keycloak sí lo emite. |
| Authorization Code sin PKCE en cliente público | No hay clientes públicos hoy | No aplica hoy; en S11 se usa PKCE. |
| Usuario y contraseña enviados directo al servidor (Resource Owner Password) | El POST /api/v1/auth/login (3.12) |
Ocurre, a propósito: es la pieza temporal que Keycloak reemplaza (2.4). |
3.27 Ver PKCE en acción¶
Producto del paso: un code_verifier y su code_challenge generados por ti, y la comprobación de por qué interceptar el code no alcanza (2.4, Figura 6).
Este paso no toca ningún servicio: reproduce el cálculo que hará el cliente Angular en S11. Genera un code_verifier aleatorio, calcula su code_challenge (SHA-256, en Base64 apto para URL) y calcula el code_challenge de un valor casi igual — el mismo verificador con un carácter más.
PowerShell:
function Get-Pkce([string]$verifier) {
$hash = [System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::ASCII.GetBytes($verifier))
[Convert]::ToBase64String($hash).TrimEnd('=').Replace('+','-').Replace('/','_')
}
$bytes = New-Object byte[] 48
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$codeVerifier = [Convert]::ToBase64String($bytes).TrimEnd('=').Replace('+','-').Replace('/','_')
"code_verifier: $codeVerifier"
"code_challenge: $(Get-Pkce $codeVerifier)"
"challenge con un carácter más: $(Get-Pkce ($codeVerifier + 'x'))"
bash macOS/Linux:
pkce() { printf '%s' "$1" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '='; echo; }
CODE_VERIFIER=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64)
echo "code_verifier: $CODE_VERIFIER"
echo "code_challenge: $(pkce "$CODE_VERIFIER")"
echo "challenge con un carácter más: $(pkce "${CODE_VERIFIER}x")"
Resultado esperado: tres líneas. El code_challenge tiene 43 caracteres, y el challenge con un carácter más no se parece en nada al anterior — un solo carácter distinto cambia el hash completo.
Ahora conecta lo que ves con la Figura 6: en el paso 1, el cliente envía solo el code_challenge; en el paso 4, presenta el code_verifier original, y el servidor calcula el hash y comprueba que coincide. Quien intercepte el code en el paso 3 solo conoce el code_challenge — y como el hash no se puede invertir, no puede reconstruir el code_verifier que hace falta para canjear ese code. Por eso PKCE protege a los clientes que no pueden guardar un client_secret (RFC 7636).
Evidencia de aprendizaje:
pagatu-auth-msoperativo en DEV, con usuarios y roles en sus propias tablas, registrado enpagatu-eurekay con configuración externa desdepagatu-config.- Login exitoso devolviendo un
access_tokenfirmado (RS256), y login fallido devolviendo401. - Registro de un usuario nuevo con
POST /api/v1/auth/registro(201), y su contraseña guardada como hash BCrypt. GET /.well-known/jwks.jsonpublicando solo la clave pública.pagatu-gatewaycomo Resource Server, con los cuatro casos de 3.19: sin token (401), token alterado (401), rol incorrecto (403) y rol correcto (201/200).pagatu-orden-mscomo Resource Server: orden creada conidClientetomado del JWT, y llamado directo con token alterado rechazado con401.- Matriz de roles y accesos (Tabla 9) y lista de verificación (Tabla 10) completadas.
4. Crea: actividad autónoma¶
Tiempo: 4h fuera del aula.
4.1 Actividad¶
Protección de pagatu-cliente-ms (construido de forma autónoma desde S2) con el mismo patrón de roles aplicado hoy a pagatu-catalogo-ms y pagatu-orden-ms, documentada en evidencia individual.
Completa y evidencia estas tareas:
- Definir qué rutas de
pagatu-cliente-msnecesitan qué rol (por ejemplo: consultar el propio perfil exige estar autenticado; listar todos los clientes exigeADMIN) y agregarlas aSecurityConfigdepagatu-gateway(mismo patrón de 3.18). - Agregar la ruta de
pagatu-cliente-msal Gateway (mismo patrón de 3.6). - Convertir
pagatu-cliente-msen Resource Server, para que valide el JWT por su cuenta (mismo patrón de 3.21). - Probar el caso permitido y el caso denegado a través del Gateway, y un llamado directo al puerto de
pagatu-cliente-mscon un token alterado, con capturas de los códigos de respuesta (mismo patrón de 3.19 y 3.24). - Documentar la matriz de roles y accesos de
pagatu-cliente-ms, mismo formato de la Tabla 9 (3.25). - Registrar aporte individual.
4.2 Propósito¶
Que cada estudiante demuestre, de forma individual y fuera del aula, que puede extender el patrón de control de acceso centralizado a un tercer microservicio de negocio sin el acompañamiento del docente — la misma habilidad que el proyecto necesita para proteger cualquier microservicio nuevo que aparezca en U3.
Esta actividad autónoma se desarrolla sobre el proyecto de fin de curso del equipo. El producto de la unidad se construye por acumulación de los avances de cada sesión; por eso, la evidencia de esta sesión debe incorporarse a la documentación del proyecto y quedar trazable en GitHub.
4.3 Indicaciones¶
Entrega un PDF con el siguiente nombre:
S07_Equipo##_ApellidoNombre.pdf
Cada captura de pantalla del informe debe mostrar, sin recortar, el reloj del sistema (fecha y hora) y tu usuario o foto de perfil (Windows, VS Code o navegador) visibles en pantalla — es lo que permite verificar que la evidencia es tuya y que corresponde al momento real de tu trabajo.
4.3.1 Estructura del informe¶
Datos del estudiante
- Nombre:
- Equipo:
- Sesión: S07 - Seguridad distribuida y control de acceso
- Rol o aporte realizado:
- Link de GitHub:
Evidencia técnica
Incluye capturas o extractos con una breve explicación debajo de cada uno, organizados en los mismos 4 bloques de la rúbrica (4.6):
pagatu-auth-msconstruido- Captura del login exitoso devolviendo un JWT, del login fallido devolviendo
401, del registro de un usuario nuevo (201) y de las tablasusuarios,rolesyusuario_rolescon sus datos, incluido el hash BCrypt del usuario registrado (trabajo de clase).
- Captura del login exitoso devolviendo un JWT, del login fallido devolviendo
pagatu-gatewaycomo Resource Server- Captura de los cuatro casos de 3.19: sin token (
401), token alterado (401), rol incorrecto (403), rol correcto (201/200).
- Captura de los cuatro casos de 3.19: sin token (
pagatu-orden-msvalida el JWT y tomaidClientede él- Captura de la orden creada en 3.23, mostrando
idClienteen la respuesta sin que el request lo haya declarado, y del llamado directo de 3.24 rechazado con401.
- Captura de la orden creada en 3.23, mostrando
pagatu-cliente-msprotegido- Caso permitido y caso denegado a través del Gateway, llamado directo con token alterado rechazado, y la matriz de roles y accesos documentada (trabajo autónomo).
Error o hallazgo
Describe un error real: un jwk-set-uri con el puerto o la ruta incorrectos (401 en todo), un pagatu-auth-ms reiniciado después de pedir el token (la firma dejó de verificar), un JwtAuthenticationConverter que no leía realm_access.roles (ningún hasRole funcionaba), o un idCliente que llegaba null porque el header Authorization no se copió completo.
Reflexión técnica breve
Responde en 5 a 8 líneas:
Si mañana reemplazas pagatu-auth-ms por Keycloak, ¿qué parte del Gateway y
de pagatu-orden-ms sigue igual, cuál cambia, y por qué esa diferencia es la
razón de haber elegido una firma asimétrica (clave privada / clave pública)
en vez de un secreto compartido?
Anexo: Feedback de la sesión
Pega esta página como la última hoja del PDF, con tus respuestas.
- ¿Cuál es el aprendizaje más importante que te llevas de la clase de hoy?
- ¿Qué punto de la clase te resultó más confuso o te dejó con dudas?
- ¿Tienes alguna pregunta que te gustaría que sea respondida la siguiente clase?
- Sobre tu nivel de comprensión de la clase de hoy, marca una opción:
- ¡Entendido! - Lo domino y podría explicarlo.
- Más o menos. - Entendí la idea general, pero tengo dudas.
- Necesito ayuda. - Me siento perdido/a con este tema.
- ¿Cómo puedo ayudarte a comprender mejor el tema?
- Pensando en tu participación y esfuerzo en la clase de hoy, ¿cómo te autoevaluarías? Marca una opción:
- Muy Comprometido/a: Me esforcé al máximo.
- Comprometido/a: Sé que podría haberme esforzado un poco más.
- Poco Comprometido/a: Hoy no di mi mejor esfuerzo.
- Mi satisfacción con la clase fue... (califica del 1 al 10, donde 1 es insatisfecho y 10 es muy satisfecho).
4.4 Criterios mínimos de aceptación¶
- PDF con nombre correcto.
pagatu-auth-msevidenciado: login exitoso con JWT, login fallido con401, roles en su propia tabla.- Evidencia de los cuatro casos de acceso a través del Gateway (sin token, token alterado, rol incorrecto, rol correcto).
- Evidencia de
pagatu-orden-mscreando una orden conidClientetomado del JWT, no del request, y rechazando con401un llamado directo con token alterado. pagatu-cliente-msprotegido con el mismo patrón (Gateway y Resource Server propio), con matriz de roles y accesos documentada.- Aporte individual verificable.
4.5 Preguntas de defensa¶
- ¿Por qué el mensaje de error de un login fallido no distingue entre "el email no existe" y "la contraseña es incorrecta"?
- ¿Por qué el Gateway y
pagatu-orden-mspueden verificar un token sin guardar ningún secreto, y qué ganas con eso frente a un secreto compartido? - ¿Qué pasa si
pagatu-auth-msestá caído, o se reinició, cuando llega el primer token al Gateway? - ¿Qué diferencia hay entre que el Gateway rechace una petición por falta de token (
401) y que la rechace por rol incorrecto (403)? - Si
pagatu-orden-msse llama directo, sin pasar por el Gateway, ¿qué lo protege de un token inválido? - ¿Qué cambia y qué no cambia en el Gateway y en
pagatu-orden-msel día quepagatu-auth-msse reemplace por Keycloak? - ¿Qué problema resuelve PKCE que un
client_secretno puede resolver en una aplicación que corre en el navegador? - Si quitas un rol a un usuario en la base de datos, ¿por qué su token ya emitido sigue funcionando, y cómo se limita ese riesgo?
4.6 Rúbrica de evaluación¶
| Dimensión | Peso | 3 - Logro destacado | 2 - Logro | 1 - Proceso | 0 - Inicio | Puntuación obtenida |
|---|---|---|---|---|---|---|
1. pagatu-auth-ms construido |
2 | Login completo: JWT firmado, clave pública publicada, roles en tabla propia, error controlado con 401, usuarios semilla con BCrypt. |
Login funcional con partes menores incompletas. | Login parcial. | No evidencia pagatu-auth-ms funcionando. |
|
2. pagatu-gateway como Resource Server |
2 | Evidencia los cuatro casos (401 sin token, 401 token alterado, 403, éxito) con capturas claras. |
Evidencia funcional con algún caso incompleto. | Evidencia parcial o poco clara. | No evidencia protección del Gateway. | |
3. pagatu-orden-ms valida el JWT y toma idCliente de él |
2 | idCliente tomado del JWT ya verificado, llamado directo rechazado con 401, evidenciado y explicado. |
Funcional, evidencia parcial. | Cambio incompleto o inconsistente. | Sigue aceptando idCliente del request. |
|
4. pagatu-cliente-ms protegido |
1 | Roles definidos con criterio, Resource Server propio, casos permitido/denegado y llamado directo evidenciados, matriz documentada. | Protección funcional, matriz incompleta. | Protección parcial. | No evidencia protección de pagatu-cliente-ms. |
|
| 5. Matriz de roles y accesos | 1 | Matriz completa y verificada contra evidencia real. | Matriz completa, sin verificación clara. | Matriz incompleta. | No documenta la matriz. | |
| 6. Aporte individual | 1 | Aporte claro y verificable. | Aporte identificable. | Aporte general. | No se identifica aporte. | |
| 7. Orden y reflexión | 1 | PDF ordenado y reflexión técnica clara. | Evidencia suficiente. | Evidencia poco clara. | PDF insuficiente. |
Puntuación acumulada = suma de (Peso × Puntuación obtenida) = ____.
Nota final = (Puntuación acumulada / 30) × 20 = ____.
Para usar la rúbrica con IA, solicita:
Evalúa el PDF usando la rúbrica de la sesión.
Para cada dimensión selecciona la puntuación obtenida usando la escala Inicio=0, Proceso=1, Logro=2, Logro destacado=3.
Justifica brevemente cada puntuación.
Calcula la puntuación acumulada con la fórmula: suma de (Peso × Puntuación obtenida).
Calcula la nota final sobre 20 con la fórmula: (Puntuación acumulada / 30) × 20.
Indica 2 fortalezas y 2 recomendaciones.
5. Cierre¶
Tiempo: 5 min.
Resumen breve: hoy el sistema ganó su tercer microservicio (pagatu-auth-ms) y su primera capa de seguridad real: pagatu-auth-ms firma los tokens con una clave privada que nunca sale de él, pagatu-gateway pasó de ser solo un punto único de acceso a ser la primera línea de validación de identidad y rol, y pagatu-orden-ms dejó de confiar en un dato que cualquiera podía inventar (idCliente) para tomarlo de un JWT que verifica por su cuenta y que nadie puede falsificar sin la clave privada. Nada de eso depende de que pagatu-auth-ms sea quien emite el token: cuando llegue Keycloak, cambia una propiedad de configuración.
Dinámica participativa: en una ronda rápida, cada estudiante comparte en una frase qué código de respuesta obtuvo al intentar modificar el catálogo con un token de CLIENTE — y por qué ese código (403, no 401) es la respuesta correcta.
Metacognición: ¿qué parte de la sesión te costó más entender — que el JWT no depende de ningún estado guardado en el servidor (stateless), o que pagatu-orden-ms vuelve a verificar la firma aunque el Gateway ya la haya validado?
Proyección: S8 agrega mensajería asíncrona entre servicios desacoplados, con Kafka — pagatu-orden-ms, ya protegido hoy, publicará orden.creada con el idCliente real (tomado del JWT, no inventado) hacia un microservicio de pagos que todavía no existe, y consumirá el resultado del pago (pago.validado; en S9, pago.fallido para compensar). S11 conecta un cliente Angular real, que va a necesitar guardar este mismo JWT y mandarlo en cada petición — nada de lo construido hoy en el Gateway ni en pagatu-orden-ms queda obsoleto, es la base exacta que ese cliente real va a consumir. Lo único temporal es pagatu-auth-ms: cuando el proyecto integre Keycloak, el cliente dejará de escribir su contraseña en un formulario propio y pasará al flujo Authorization Code con PKCE (2.4), pero los resource servers de hoy seguirán validando el mismo tipo de token.
Bibliografía¶
- Denniss, W., & Bradley, J. (2019). OAuth 2.0 Device Authorization Grant (RFC 8628). IETF. https://datatracker.ietf.org/doc/html/rfc8628
- Hardt, D. (Ed.). (2012). The OAuth 2.0 Authorization Framework (RFC 6749). IETF. https://datatracker.ietf.org/doc/html/rfc6749
- Jones, M. (2015). JSON Web Key (JWK) (RFC 7517). IETF. https://datatracker.ietf.org/doc/html/rfc7517
- Jones, M., Bradley, J., & Sakimura, N. (2015). JSON Web Token (JWT) (RFC 7519). IETF. https://datatracker.ietf.org/doc/html/rfc7519
- JWT.io / Auth0. (2024). Introduction to JSON Web Tokens. https://jwt.io/introduction
- Keycloak. (2025). Keycloak Documentation. https://www.keycloak.org/documentation
- Lodderstedt, T., Bradley, J., Labunets, A., & Fett, D. (2025). Best Current Practice for OAuth 2.0 Security (RFC 9700). IETF. https://datatracker.ietf.org/doc/html/rfc9700
- Parecki, A. (s. f.). OAuth Grant Types. OAuth.net. https://oauth.net/2/grant-types/
- SACAViX. (s. f.-a). RBAC / Control de Acceso [Patrón de diseño]. System Design. https://systemdesign.sacavix.com/patterns
- SACAViX. (s. f.-b). OAuth2 / OpenID Connect [Patrón de diseño]. System Design. https://systemdesign.sacavix.com/patterns/oauth2-security
- Sakimura, N., Bradley, J., & Agarwal, N. (2015). Proof Key for Code Exchange by OAuth Public Clients (RFC 7636). IETF. https://datatracker.ietf.org/doc/html/rfc7636
- Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., & Mortimore, C. (2014). OpenID Connect Core 1.0. OpenID Foundation. https://openid.net/specs/openid-connect-core-1_0.html
- Spring Team. (2024). Spring Security Reference: OAuth2 Resource Server. https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html