Metadata

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

Onboarding — SSO Federated App Template

¿Qué es SSO Federated App Template?

El SSO Federated App Template es un repositorio base escalable diseñado para crear aplicaciones backend que federan de manera directa la autenticación con el sistema central de SSO de BigSo (versiones 2.5.0 en adelante). Su principal objetivo es abstraer y encapsular todos los flujos manuales y repetitivos asociados con el intercambio de códigos OAuth2, la validación de sesiones activas, la revocación de tokens de acceso al momento de hacer logout y la sincronización automática de recursos hacia el portal central de la organización.

Está construido para que los desarrolladores de la organización no tengan que preocuparse por las minucias de la seguridad y puedan enfocarse exclusivamente en implementar la lógica de negocio de sus aplicaciones, aprovechando middlewares limpios y servicios seguros que ya incluyen el manejo de validaciones IP y DNS para garantizar que la comunicación interna sea confiable y autorizada dentro de la red corporativa.

Prerequisitos

• Node.js ≥ 20.0.0
• npm ≥ 9.0.0
• Acceso a la red interna de BigSo para alcanzar el backend central en el puerto 3000.

Setup Local

1. Clonar el repositorio

git clone https://github.com/cmontesvergara/sso-federated-app-template.git
cd sso-federated-app-template

2. Instalar dependencias

npm install

3. Configurar variables de entorno

cp .env.example .env

Debes asegurarte de editar el archivo .env con los valores que corresponden a tu registro en el portal de BigSo:

• PORT: El puerto local donde correrás la aplicación.
• FRONTEND_URL: La URL exacta permitida en los CORS para el cliente.
• SSO_BACKEND_URL: La ruta al Identity Provider de BigSo (ej. http://localhost:3000).
• APP_ID: El identificador único que te asignó el portal al crear la aplicación.
• COOKIE_NAME: El nombre de la cookie que usará la sesión (bigso_app_session).

4. Ejecutar

npm run dev

El servicio estará disponible en http://localhost:4300 (o el puerto que hayas definido en la configuración).

Verificar que funciona

Para saber si la inicialización fue exitosa, simplemente puedes hacer una petición a la ruta de healthcheck:

curl http://localhost:4300/health

Si todo está en orden, deberías recibir una respuesta en formato JSON con el estado ok y el timestamp actual de la aplicación.

Problemas Comunes

Problema	Causa	Solución
Cannot find module 'express'	No ejecutaste la instalación de las dependencias antes del inicio.	Debes detener el proceso y ejecutar npm install en la raíz del proyecto.
Las peticiones al endpoint de sync fallan con 403 HTTP	Estás intentando llamar localmente a los recursos de sincronización sin usar IPs de red local válidas.	El middleware de guardado de sincronización bloquea accesos externos por diseño. Usa 127.0.0.1 en desarrollo o desactiva la capa de seguridad en modo dev.

Canales de Soporte

Canal	Propósito
#core-team	Soporte general sobre integraciones SSO, reportes de bugs en el template y consultas de arquitectura.
#dev-ops-sso	Consultas relacionadas a despliegue del portal central o fallas en el ambiente de producción de la federación.