Metadata

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

Integration — SSO Federated App Template

Autenticación

Debido a que este servicio abstrae la comunicación con el Identity Provider, el consumo de las APIs expuestas por este template asume el flujo mediante Cookies HTTP Only. Esto implica que el cliente del frontend debe incluir el envío de credenciales (withCredentials: true en axios, o el equivalente).

# Ejemplo de verificar tu propia sesión
curl -X GET http://localhost:4300/api/auth/session \
  -H "Cookie: bigso_app_session=ey..."

Endpoints

Autenticación y Sesiones

POST /api/auth/exchange

Recibe un Authorization Code directamente desde el flujo web y gestiona internamente la emisión de la cookie de sesión correspondiente, enviando la validación del intercambio con el portal central.

Request:

{
  "code": "auth-code-1234abcd"
}

Response (200):

{
  "success": true,
  "user": {
    "userId": "uuid-123",
    "email": "lead@bigso.co",
    "firstName": "John",
    "lastName": "Doe"
  },
  "tenant": {
    "tenantId": "uuid-tenant",
    "name": "BigSo Corp",
    "slug": "bigso-corp",
    "role": "admin"
  },
  "expiresAt": "2026-02-22T00:00:00Z"
}

Errores:

Código	Significado
400	No se proveyó el código de autorización temporal
401	Exchange fallido o código de SSO expirado / inválido / usado

GET /api/auth/session

Valida si la cookie actual contiene un token JWT legal y si éste subyace una sesión activa en el SSO Backend principal. En caso afirmativo devuelve los recursos adjuntados a dicho usuario.

Response (200):

{
    "success": true,
    "user": {
        "userId": "uuid-123",
        "email": "lead@bigso.co"
    },
    ...
}

Errores:

Código	Significado
401	Sesión expirada o token vacío. La cookie fue depurada

POST /api/auth/logout

Limpieza agresiva del cliente HTTP y revocación de trust local a nivel de navegador. Transmite el pedido de cierre de app-session con SSO_BACKEND_URL.

Response (200):

{
    "success": true,
    "message": "Logged out from my_new_federated_app"
}

Sincronización de Componentes

GET /api/sso/resources

Endpoint de tipo pull model consumido exclusivamente por Super Admins de BigSo. Permite auto-descubrir los componentes y configuraciones RBAC configuradas arbitrariamente en src/routes/ssoSync.routes.js.

Response (200):

{
  "success": true,
  "resources": [
    {
      "resource": "orders",
      "action": "read",
      "description": "View orders list"
    }
  ],
  "meta": {
    "appId": "my_new_federated_app",
    "count": 1,
    "timestamp": "2026-02-21T00:00:00.000Z"
  }
}

Errores:

Código	Significado
403	Origen de red bloqueado o carencia explícita de cifrado TLS
500	Errores de validación durante la resolución de registros de DNS para verificar autenticidad.

SDKs y Librerías Cliente

El sistema subyacente interactúa por HTTP crudo. Si usted precisa la herramienta transitoria de BigSo de clientes (opcionalmente) puede consumir @bigsoco/sso-sdk que ya se encuentra en desuso para la arquitectura de federación plana pero sobrevive en esquemas nativos:

npm install @bigsoco/sso-sdk

Rate Limits

Endpoint	Límite	Ventana
/api/auth/*	100 requests	1 minuto
/api/sso/resources	50 requests	1 minuto

Errores Comunes de Integración

Problema	Causa	Solución
Bloqueo completo por CORS de Preflight	Las requests están saliendo desde un frontend cuyo HOST local no es conocido por el API de este template.	Asegurar que FRONTEND_URL empareje textualmente hasta en los puertos y sin slashes posteriores.
Inutilidad para adjuntar headers Set-Cookie en Postman / Insomnia	La red o el proxy local de tu entorno desecha las cookies del browser debido al atributo sameSite: "lax"	Emular explícitamente la inserción de cookies o configurar las variables temporales del cliente HTTP.