SSO y Token Handler Pattern

Arquitectura de Flujos SSO y Gestión de Tokens (Token Handler Pattern)

Este documento detalla la estrategia de seguridad y el flujo de los mecanismos de autenticación y autorización para el Alcampo Brand Portal.

La solución se apoya fuertemente en el Token Handler Pattern implementado a través de un componente Backend For Frontend (BFF). El objetivo principal de este patrón es mitigar riesgos críticos (como exposición de JWT a posibles vulnerabilidades XSS en el cliente) trasladando la responsabilidad de manipular, almacenar y refrescar los correspondientes Access Tokens y Refresh Tokens hacia una capa de servidor controlada.

Tres secuencias principales gobiernan este ecosistema de identidad.

---

1. Visión Arquitectónica de Alto Nivel

El diagrama de alto nivel ilustra el rol del BFF como mediador central en todas las transacciones de identidad entre la Single Page Application (SPA), el proveedor de identidad de Salesforce (IdP) y las APIS y microservicios subyacentes.

Para la elección tecnológica del BFF (Quarkus + JAX-RS) véase Decisiones Tecnológicas.
Los patrones de implementación concretos (filtros, código Java) están en Patrones de Implementación BFF.

Puntos Clave del Patrón:

• Confidencialidad en el Cliente: La SPA que corre en el navegador web nunca recibe ni almacena un token OAuth 2.0 nativo.
• Cookie Exchange: La sesión del usuario se gestiona exclusivamente a través de un identificador de sesión opaco (session_id), distribuido como una cookie restrictiva configurada con directivas de seguridad fuertes (HttpOnly, Secure y SameSite=Lax).
• Session Store Seguro: El BFF custodia una caché o base de datos de clave-valor. Esta relaciona los identificadores de sesiones con los tokens reales encriptados, administrando internamente el ciclo de vida o Time To Live (TTL).

---

2. Flujo de Autenticación (SSO Handshake)

Cuando un navegador intenta consumir un recurso del Brand Portal sin poseer una sesión válida, el sistema activa automáticamente un flujo Authorization Code + PKCE hacia el IDP corporativo de Salesforce. Toda la negociación se rige por procesos Server-to-Server, excepto las redirecciones puras al usuario y el consentimiento.

Referencia estándar: RFC 6749 — The OAuth 2.0 Authorization Framework · RFC 7636 — PKCE.

Desglose del Proceso:

1. Delegación de Autenticación (HTTP 302): El BFF detecta ausencia de autenticación y redirige de inmediato el flujo de red al /authorize de Salesforce, externalizando la pantalla de ingreso y el procesamiento de las credenciales.
2. Intercambio del Código de Autorización: La redirección callback aporta un code temporal. El módulo OAuth2 Agent del BFF lo captura mediante el endpoint interno (/bff/auth/callback). Véase el código del controlador JAX-RS.
3. Persistencia Cifrada: Usando el secreto precompartido, el BFF contacta al IdP para cambiar el code por el Token Bundle. Inmediatamente después de cifrar estos tokens (algoritmo AES-GCM), los archiva en el Session Store y genera un ID de sesión puramente aleatorio.
4. Instanciación de la Sesión: La redirección de retorno a la página SPA inyecta estrictamente la cabecera Set-Cookie: session_id=.... De esta forma, el token sensible jamás llega al espectro JavaScript del Frontend.

---

3. Resolución de Peticiones y Token Exchange

Una vez atada la identidad al equipo de red local del usuario mediante la cookie HttpOnly, las llamadas de consumo estándar dirigidas al dominio exigen una “traducción” antes de tocar las APIs finales de backend (Resource Server).

Fase Operativa:

1. Transporte Transparente: Al emitir cualquier request contra la API en la ruta /bff/* o /api/*, el Fetch nativo adjunta la cookie si posee el flag credentials: 'include' (equivalente al withCredentials: true de Axios).
2. Hidratación en el Proxy: El BFF lee y desencapsula el payload de la sesión interactuando contra el Session Store. La implementación Java concreta está en SessionDecryptionFilter.
3. Conmutación: Intercepta el JWT subyacente y formula una re-petición autenticada contra el Resource Server, inyectando de forma legal la cabecera estándar Authorization: Bearer <jwt>.
4. Respuesta Esterilizada: Finalizada la carga transaccional, el BFF limpia trazas internas (tokens caducados, variables puramente defensivas) y retorna una entidad JSON filtrada y consumible al Front-end React.

Este ecosistema permite blindar la seguridad del SPA — véase la integración CORS y withCredentials en Arquitectura Frontend — a expensas de centralizar y abstraer la lógica en un solo punto (El BFF), estandarizando las validaciones antes del cruce al anillo interno de la red.