Download documentation/M6_AUTH_SSO.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 15.8 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/M6_AUTH_SSO.md
- Command line
-
hf download hf://spaces/Modulo-6/api/documentation/M6_AUTH_SSO.md
-
curl -L -o M6_AUTH_SSO.md https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/M6_AUTH_SSO.md
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 enM6_DISEÑO.md§11 y el mapeo de roles enroles.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>)
- El usuario ya está autenticado en el Core (o en otro módulo que comparte el Core).
- Alguien pide un ticket de un solo uso:
POST /auth/sso-ticketen el Core (vida ~60 s, verM10_SSO_INTEGRATION_GUIDE.md). - El navegador llega al frontend de M6 con
?ticket=…&redirect=…. - 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.
- El backend de M6 hace el canje real contra el Core, server-to-server.
- El backend de M6 resuelve el rol y emite su propio JWT.
- 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 deADMINISTRATIVO|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
localStorageo una cookie propia del frontend, a criterio de ese equipo (igual que recomiendaM10_SSO_INTEGRATION_GUIDE.mdpara SPAs). - Cómo se valida cada request:
get_current_user(app/dependencies.py) hacedecode_token— verifica la firma HS256 contrajwt_secrety leesub+roldirecto 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
401de 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 subirJWT_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. -
redirectvalidado 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: Beareren toda llamada a M6. - Manejo de
401/403/404/502de la respuesta del canje. - Interceptor de
401en 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
- 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).
- M6 saca el
core_tokenembebido en la sesión del usuario (ver §1) y hacePOST /auth/sso-ticketal Core en su nombre. - El frontend recibe el ticket y redirige el browser al callback del otro módulo, igual que documenta
M10_SSO_INTEGRATION_GUIDE.mdpara 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(schemasSSOExchangeRequest/SSOExchangeResponse/SSOTicketResponse).