Metadata

Owner: core-team · Lifecycle: active · Last Reviewed: 2026-02-21 · Support: #core-team

Architecture — SSO Federated App Template

Visión General

El proyecto funciona como un middleware y facade para integrar cualquier aplicación cliente con la infraestructura corporativa de BigSo. Expone de manera transparente un conjunto de configuraciones unificadas mediante ExpressJS. Actúa absorbiendo la lógica pesada de comunicarse con el BigSo SSO a través de HTTP directo.

En esencia, consta de una capa de enrutamiento que intercepta y distribuye el tráfico, una capa robusta de middlewares (ssoAuthMiddleware, ssoSyncGuardMiddleware) encargada únicamente de realizar verificaciones de estado y seguridad perimetral a nivel IP/DNS, y una capa de servicio (sso.service.js) encargada de efectuar las peticiones asíncronas hacia el proveedor central de identidades para el intercambio y manejo del ciclo de vida de los tokens.

Componentes Principales

Auth Middleware

• Responsabilidad: Protege las rutas declaradas de la aplicación validando la sesión extraída en formato de cookie y adhiriendo la información decodificada (usuario y tenant) en el objeto general de cada petición para el desarrollador de negocio.
• Tecnología: Funciones async en Node.js integradas con Express.
• Puerto/URL: Expuesto internamente como un interceptor en Node.js.

SSO Service

• Responsabilidad: Abstrae toda la comunicación de red axios. Posee la firma completa de consumo remoto para validación de tokens o intercambio de códigos OAuth. Aísla las integraciones del middleware.
• Tecnología: Cliente HTTP usando la biblioteca axios.
• Puerto/URL: Se comunica con SSO_BACKEND_URL desde la instancia Node de la aplicación.

Sync Guard Middleware

• Responsabilidad: Bloquea cualquier petición entrante no autorizada a las rutas internas de sincronización. Ejecuta procedimientos estrictos de cruce entre las IPs reportadas de origen y la validación DNS corporativa, validando si las peticiones entrantes pertenecen lógicamente a las redes internas o la URL del componente proveedor de identidades central.
• Tecnología: Node.js native dns module promises.

Flujos Críticos

Intercambio de Authentication Code

Decisiones Técnicas

Decisión	Alternativas Evaluadas	Razón
Clientes HTTP planos (axios) en vez del SDK	Usar la librería oficial @bigsoco/sso-sdk	Para garantizar control microscópico sobre el control de las sesiones y la flexibilidad para adaptaciones custom que los templates necesitan. Mantiene la paridad fiel con el legacy admin-backend como base de la verdad.
Inyección de datos en objeto Express	Devolver callbacks asíncronos complejos o context stores globales.	Adherir el req.user y req.tenant aprovecha eficientemente el estándar asíncrono sobre el que todo el ecosistema y librerías de comunidad en Express están acostumbradas.

Dependencias Externas

Servicio	Propósito	SLA/Criticidad
Central SSO Backend	Resolución de usuarios, sesiones y tenants corporativos de BigSo.	Muy crítico (Tier 1). Si este servicio se cae la federación de usuarios, login y sincronización colapsan globalmente.