api / documentation /M6_AUTH_SSO.md
juampisor's picture
SSO and auth fix
01e0bb5
|
Raw History Blame Contribute Delete
15.8 kB

Autenticación de M6: SSO del Core — guía para backend y frontend

Health Grid · Módulo 6 (Internación y Gestión de Camas)

Este documento explica cómo se loguea un usuario en M6 y cómo persiste su sesión, y sirve de guía de implementación para el equipo de frontend. Es específico de M6; el contrato genérico del SSO del Core está en M10_SSO_INTEGRATION_GUIDE.md. El detalle de la integración vive en M6_DISEÑO.md §11 y el mapeo de roles en roles.md §6.


1. Resumen

M6 no tiene login propio. No hay pantalla de usuario/contraseña contra este backend. El usuario se loguea en el Core (M10) — ya sea directamente o porque llega logueado desde otro módulo — y M6 lo recibe ya autenticado vía SSO: canjea un ticket de un solo uso por los datos del usuario, y a partir de ahí emite su propia sesión, independiente del Core.

M6 implementa el SSO en ambos sentidos:

  • Entrante (§2 a §6): un usuario llega a M6 desde otro módulo o desde el Core, con un ticket. M6 lo canjea y emite su propia sesión.
  • Saliente (§9): un usuario ya logueado en M6 navega hacia otro módulo sin loguearse de nuevo. M6 le pide un ticket al Core en su nombre.

Dos tokens distintos entran en juego y no hay que confundirlos:

Token Quién lo emite Algoritmo Vigencia Dónde se usa
Token del Core M10 RS256 24 h Se usa dentro del canje entrante (sso-exchange) para resolver el rol, y además queda embebido como claim (core_token) dentro del JWT de M6, para poder pedir tickets salientes después (§9) — no se descarta del todo.
Token de M6 M6 (create_access_token) HS256 JWT_EXPIRE_MINUTES (hoy 60 min) Es la sesión real: el frontend lo guarda y lo manda como Authorization: Bearer en cada request a M6.

Nota de seguridad sobre el core_token embebido: un JWT está firmado, no cifrado — su payload es base64, legible por cualquiera que tenga el token, incluido el propio frontend/browser (decodificarlo no requiere romper la firma). Esto significa que el JWT del Core embebido es técnicamente visible para quien tenga el JWT de M6. Es un trade-off consciente: la alternativa (guardar el token del Core en un store server-side en vez de en el JWT) reintroduce estado en un backend que es deliberadamente stateless (§4), y no se tomó acá. En la práctica, si se filtra un JWT de M6 ya es grave por sí solo (acceso a datos médicos vía la API); esto extiende el radio de impacto también al Core por hasta 24 h, sin que M6 pueda revocarlo.


2. Flujo completo

sequenceDiagram
    participant U as Usuario (navegador)
    participant Core as Core API (M10)
    participant F as Frontend M6
    participant M6 as Backend M6

    U->>Core: 1) Login (u otro módulo ya logueado)
    F->>Core: 2) POST /auth/sso-ticket (Bearer del Core)
    Core-->>F: { ticket, expires_in }
    Note over U,F: 3) Redirect a /auth/sso?ticket=…&redirect=/mapa
    F->>M6: 4) POST /api/v1/auth/sso-exchange { ticket }
    M6->>Core: 5) POST /auth/sso-exchange { ticket }
    Core-->>M6: { user (con roles[]), token (RS256, descartado) }
    M6-->>F: { token (HS256 propio), user, rol }
    Note over F: 6) Guarda el token, navega a redirect
    F->>M6: 7) GET /api/v1/camas  (Authorization: Bearer <token M6>)
  1. El usuario ya está autenticado en el Core (o en otro módulo que comparte el Core).
  2. Alguien pide un ticket de un solo uso: POST /auth/sso-ticket en el Core (vida ~60 s, ver M10_SSO_INTEGRATION_GUIDE.md).
  3. El navegador llega al frontend de M6 con ?ticket=…&redirect=….
  4. El frontend de M6 canjea ese ticket contra el backend de M6 — no contra el Core directamente. Esto es lo que distingue a M6 de la guía genérica del Core: M6 actúa de proxy del canje.
  5. El backend de M6 hace el canje real contra el Core, server-to-server.
  6. El backend de M6 resuelve el rol y emite su propio JWT.
  7. El frontend guarda ese JWT y lo usa en todas las llamadas siguientes.

3. Contrato: POST /api/v1/auth/sso-exchange

Implementado en app/routers/auth.py. Habilitado solo si SSO_ENABLED=true en el backend.

Request

{ "ticket": "9f2c1b7a3e045e6f7a8b9c0d1e2f3a4b" }

ticket: string no vacío. Es el mismo ticket recibido en la query del callback.

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 42,
    "first_name": "Ana",
    "last_name": "Pérez",
    "email": "ana@example.com"
  },
  "rol": "ADMINISTRATIVO"
}
  • token: JWT HS256 de M6 (no el del Core). Es lo único que el frontend necesita guardar y reenviar.
  • user: subconjunto de datos del usuario, para mostrar en la UI (no hace falta pedir nada más al Core).
  • rol: uno de ADMINISTRATIVO | MEDICO | LIMPIEZA — el rol interno de M6 ya resuelto (ver §5).

Errores

Código Cuándo Qué hacer en el frontend
401 Ticket inválido, ya usado o expirado (NO_AUTENTICADO) Volver a iniciar el flujo desde el módulo de origen (pedir un ticket nuevo)
403 El usuario no tiene ningún rol de Core mapeado a M6 (NO_AUTORIZADO) Mostrar "sin acceso a este módulo"; no reintentar
404 SSO deshabilitado en este backend (SSO_ENABLED=false) Error de configuración/entorno, no del usuario
502 El Core no respondió al canje (SERVICIO_EXTERNO_NO_DISPONIBLE) Reintentar más tarde / mostrar error de servicio

El body de error va anidado bajo detail (comportamiento por defecto de FastAPI ante un HTTPException):

{ "detail": { "codigo": "NO_AUTENTICADO", "mensaje": "Ticket inválido, ya usado o expirado" } }

4. Cómo persiste la sesión

M6 es completamente stateless. No hay tabla de sesiones, no hay store en memoria ni en base de datos, no hay cookie que el backend administre. La "sesión" es, literalmente, el JWT que tiene el cliente.

  • Dónde vive: en el cliente. El backend no lo sabe ni le importa — puede ser localStorage o una cookie propia del frontend, a criterio de ese equipo (igual que recomienda M10_SSO_INTEGRATION_GUIDE.md para SPAs).
  • Cómo se valida cada request: get_current_user (app/dependencies.py) hace decode_token — verifica la firma HS256 contra jwt_secret y lee sub + rol directo del payload. Cero llamadas al Core, cero lookups, cero estado compartido. Por eso el rol tiene que viajar embebido en el token (ver §5): si hubiera que resolverlo aparte, dejaría de ser stateless.
  • Vigencia: JWT_EXPIRE_MINUTES (hoy 60 min en .env). Ojo: el token del Core dura 24 h, pero eso es irrelevante una vez canjeado — la sesión de M6 dura lo que este valor diga.
  • Al vencer: no hay endpoint de refresh en M6 hoy. El frontend debe manejar el 401 de un request cualquiera repitiendo el flujo SSO desde cero (nuevo ticket → nuevo canje). Si se necesita sesión más larga, es cuestión de subir JWT_EXPIRE_MINUTES; un refresh sin volver a pasar por SSO sería trabajo nuevo (no implementado).

5. De dónde sale el rol

El JWT del Core no trae el nombre del rol — sus claims son {user_id, permissions[], iat, exp}, y esos permissions[] son de recursos propios del Core, no de M6.

El rol se resuelve una sola vez, en el canje, a partir de user.roles[] de la respuesta de /auth/sso-exchange del Core (cada rol con su name) — cuando el Core lo puebla. En la práctica el Core desplegado no siempre lo trae, así que app/routers/auth.py::sso_exchange cae a un fallback: core_auth.resolve_user_roles(user_id), que arma un índice user_id → roles desde GET /roles del Core, autenticado con la cuenta de servicio de M6 (get_service_token). Es el único endpoint de roles que esa cuenta puede leer — GET /users/{id} exige el permiso users:read, que no tiene. app/integrations/core_auth.py::map_core_roles_to_internal traduce el resultado (venga de una vía o de la otra) con esta tabla:

Rol en el Core Rol interno de M6
admin_internacion ADMINISTRATIVO
Medico MEDICO
limpieza LIMPIEZA
admin (super-admin del Core) ADMINISTRATIVO
cualquier otro / ninguno sin acceso → 403 en el canje

Una vez resuelto, el rol queda embebido en el JWT de M6 (create_access_token(sub, rol)) y no se vuelve a consultar. require_roles(*roles) (app/dependencies.py) es lo que cada endpoint usa para autorizar, comparando ese campo — ver matriz completa en roles.md.


6. Guía de implementación para el frontend

Lo que el equipo de frontend tiene que construir, en orden:

6.1 Ruta de callback /auth/sso

Una ruta pública del router del SPA (no protegida) que reciba ticket y redirect por query string:

https://<host-frontend-m6>/auth/sso?ticket=<opaco>&redirect=/mapa-camas

6.2 Validar el redirect (anti-open-redirect)

Antes de navegar ahí, aceptar solo rutas internas absolutas. Mismo criterio que M10_SSO_INTEGRATION_GUIDE.md:

function safeRedirect(path: string | null): string | null {
  if (!path) return null;
  if (!path.startsWith('/') || path.startsWith('//') || path.startsWith('/\\')) return null;
  return path;
}

6.3 Canjear el ticket contra M6, no contra el Core

Esta es la diferencia clave frente a la guía genérica: el canje va al backend de M6, que a su vez habla con el Core.

async function exchangeSSOTicket(ticket: string) {
  const res = await fetch(`${M6_API_BASE}/api/v1/auth/sso-exchange`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ticket }),
  });

  if (!res.ok) {
    if (res.status === 401) throw new Error('Ticket inválido o expirado — reiniciar el login');
    if (res.status === 403) throw new Error('El usuario no tiene acceso a este módulo');
    throw new Error('No se pudo iniciar sesión en M6');
  }

  return res.json(); // { token, user, rol }
}

6.4 Guardar la sesión y limpiar la URL

const { token, user, rol } = await exchangeSSOTicket(ticket);
saveSession({ token, user, rol }); // localStorage o cookie propia
history.replaceState(null, '', location.pathname); // el ticket no debe quedar en el historial
navigate(safeRedirect(redirect) ?? '/');

6.5 Mandar el token en cada request a M6

fetch(`${M6_API_BASE}/api/v1/camas`, {
  headers: { Authorization: `Bearer ${getSessionToken()}` },
});

6.6 Manejar el vencimiento

Un interceptor de respuesta que, ante cualquier 401 de M6, limpie la sesión local y redirija a iniciar el flujo SSO de nuevo (no hay refresh):

if (response.status === 401) {
  clearSession();
  redirectToLogin(); // vuelve a pedir ticket desde el origen
}

6.7 Checklist

  • Ruta /auth/sso?ticket=&redirect= en el router del SPA.
  • redirect validado como ruta interna antes de navegar.
  • Canje contra POST {M6_API_BASE}/api/v1/auth/sso-exchange (no contra el Core).
  • Ticket limpiado de la URL después del canje (replaceState/replaceUrl).
  • Token guardado y enviado como Authorization: Bearer en toda llamada a M6.
  • Manejo de 401/403/404/502 de la respuesta del canje.
  • Interceptor de 401 en requests posteriores → reinicia SSO.

7. Desarrollo local sin el Core real

Para no depender de que el Core esté arriba, M6 expone GET /api/v1/auth/token?usuario=&password= (habilitado solo con ENVIRONMENT=development), que devuelve un JWT de M6 del mismo formato que emite el canje SSO — mismo decode_token, misma validación. usuario es en realidad el rol deseado (ADMINISTRATIVO | MEDICO | LIMPIEZA); password no se valida. Útil para levantar y probar el frontend contra M6 sin tocar el Core.

Ojo: las sesiones creadas por este endpoint no tienen core_token embebido (no pasaron por un SSO real) — no pueden usar el SSO saliente de §9. Para probar ese flujo localmente hace falta un token real del Core (login real + sso-exchange real).


9. Navegar hacia otro módulo desde M6 (SSO saliente)

El camino inverso de §2: un usuario ya logueado en M6 quiere ir a otro módulo (por ejemplo, un link en el menú) y llegar ahí ya autenticado, sin loguearse de nuevo.

sequenceDiagram
    participant F as Frontend M6
    participant M6 as Backend M6
    participant Core as Core API (M10)
    participant O as Otro módulo

    F->>M6: 1) POST /api/v1/auth/sso-ticket (Bearer: JWT de M6)
    M6->>Core: 2) POST /auth/sso-ticket (Bearer: core_token embebido)
    Core-->>M6: { ticket, expires_in }
    M6-->>F: { ticket, expires_in }
    Note over F: 3) window.location.href a /auth/sso?ticket=…&redirect=… del otro módulo
  1. El frontend pide un ticket saliente a su propio backend (M6) — no al Core directamente, porque el frontend nunca tuvo el JWT del Core (solo el de M6).
  2. M6 saca el core_token embebido en la sesión del usuario (ver §1) y hace POST /auth/sso-ticket al Core en su nombre.
  3. El frontend recibe el ticket y redirige el browser al callback del otro módulo, igual que documenta M10_SSO_INTEGRATION_GUIDE.md para el módulo de origen.

9.1 Contrato: POST /api/v1/auth/sso-ticket

Implementado en app/routers/auth.py. Requiere sesión de M6 vigente (Authorization: Bearer <JWT de M6>) — es la propia sesión del usuario la que autoriza el pedido, no un secreto aparte.

Request: sin body.

Response 200

{ "ticket": "9f2c1b7a3e045e6f7a8b9c0d1e2f3a4b", "expires_in": 60 }

Mismo shape que devuelve el Core (models.SSOTicketResponse) — sin envoltorio adicional.

Errores

Código codigo Cuándo Qué hacer en el frontend
401 SIN_SESION_CORE La sesión no tiene core_token embebido — no vino de un SSO real (p.ej. sesión de desarrollo, §7) No se puede navegar a otro módulo desde esta sesión; no reintentar
401 NO_AUTENTICADO El Core rechazó el core_token (venció o es inválido) Reiniciar el flujo de login/SSO desde cero
404 — SSO deshabilitado (SSO_ENABLED=false) Error de configuración/entorno
502 SERVICIO_EXTERNO_NO_DISPONIBLE El Core no respondió al pedido de ticket Reintentar más tarde

9.2 Frontend: usar el ticket

async function requestOutboundTicket(): Promise<{ ticket: string; expires_in: number }> {
  const res = await fetch(`${M6_API_BASE}/api/v1/auth/sso-ticket`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${getSessionToken()}` },
  });
  if (!res.ok) throw new Error('No se pudo obtener el ticket SSO saliente');
  return res.json();
}

async function navigateToModule(otherModuleHost: string, internalPath: string) {
  const { ticket } = await requestOutboundTicket();
  const redirect = encodeURIComponent(internalPath);
  window.location.href = `https://${otherModuleHost}/auth/sso?ticket=${ticket}&redirect=${redirect}`;
}

El ticket es de un solo uso y expira en expires_in segundos (~60 s, como documenta M10_SSO_INTEGRATION_GUIDE.md) — pedirlo justo antes de navegar, no guardarlo.


10. Referencias

  • M10_SSO_INTEGRATION_GUIDE.md — contrato genérico del SSO del Core (ticket, JWKS, ejemplos Angular/React/Go/Node).
  • M6_DISEÑO.md §11 — detalle técnico de la integración de auth en M6.
  • roles.md §6 — mapeo de roles del Core a roles internos de M6 y matriz de permisos por endpoint.
  • M6_openapi.json — contrato exacto de /auth/sso-exchange//auth/sso-ticket (schemas SSOExchangeRequest/SSOExchangeResponse/SSOTicketResponse).