Download documentation/integrations/M10_SSO_INTEGRATION_GUIDE.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 14 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/integrations/M10_SSO_INTEGRATION_GUIDE.md
- Command line
-
hf download hf://spaces/Modulo-6/api/documentation/integrations/M10_SSO_INTEGRATION_GUIDE.md
-
curl -L -o M10_SSO_INTEGRATION_GUIDE.md https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/integrations/M10_SSO_INTEGRATION_GUIDE.md
Guía de integración SSO — para módulos de Health Grid
Esta guía es para los equipos que implementan otros módulos de Health Grid y necesitan que un usuario que ya está logueado en otro módulo (o en el core) llegue ya autenticado a su aplicación, aunque estén en dominios distintos (no comparten cookies).
Sos el módulo destino: recibís al usuario por un redirect y tenés que dejarlo logueado en tu app. Esta guía cubre solo tu parte.
API del core:
https://api.healthcare.cantero.ar— emite y valida los JWT. Ruta de callback del módulo:/auth/sso— el usuario aterriza ahí con el ticket, p. ej.https://healthgrid.cantero.ar/auth/sso?ticket=…. Cada módulo se sirve en su propio host; el path/auth/ssoes la convención común. Los ejemplos usanhealthgrid.cantero.ar.
Qué te da el core
- Un JWT firmado con RS256 (válido 24 h) que identifica al usuario y trae sus permisos.
- La clave pública para validar ese JWT, publicada en
https://api.healthcare.cantero.ar/.well-known/jwks.json(JWKS). No necesitás ninguna clave secreta compartida.
Qué tenés que construir
- Una ruta de callback
/auth/ssoque reciba el redirect con unticket. - Una llamada al core para canjear ese ticket por un JWT (servidor-a-servidor si tenés backend; desde el navegador si sos una SPA — ver Variante SPA).
- Tu propia sesión en tu dominio (cookie /
localStorage) con ese JWT. - Validación del JWT en cada request siguiente, usando el JWKS.
El flujo, de tu lado
sequenceDiagram
participant U as Usuario (navegador)
participant B as Tu backend (módulo)
participant C as Core API<br/>(api.healthcare.cantero.ar)
U->>B: 1) redirect a /auth/sso?ticket=…&redirect=/x
B->>C: 2) POST /auth/sso-exchange<br/>{ "ticket": "…" }
C-->>B: { user, token } (JWT)
B-->>U: 3) set cookie de sesión + redirect
Note over U: ya logueado en tu módulo
- El navegador llega a tu app con una URL tipo:
https://healthgrid.cantero.ar/auth/sso?ticket=<opaco>&redirect=/dashboard - Tu backend toma el
tickety lo canjea contra el core (paso servidor-a-servidor; el ticket no se vuelve a exponer al navegador). - Recibís
{ user, token }. Guardás eltokenen tu propia sesión y redirigís al usuario aredirect.
Importante: el ticket es de un solo uso y expira en ~60 segundos. Canjealo apenas lo recibís, desde el backend. No lo guardes ni lo reenvíes al frontend.
Paso a paso
1) Endpoint de callback + canje del ticket
POST https://api.healthcare.cantero.ar/auth/sso-exchange
Request:
{ "ticket": "9f2c1b7a…e04" }
Respuesta 200:
{
"user": {
"id": 42,
"first_name": "Ana",
"last_name": "Pérez",
"email": "ana@example.com"
},
"token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ij…"
}
Errores:
| Código | Significado | Qué hacer |
|---|---|---|
400 |
Falta el ticket en el body |
Revisar tu request |
401 |
Ticket inválido, ya usado o expirado | Redirigir al login; el usuario reintenta desde el origen |
2) Establecer tu propia sesión
El token es el JWT del core. Guardalo en tu dominio — el core no maneja tu sesión:
- Recomendado: cookie propia
HttpOnly+Secure+SameSite=Lax, con el dominio de tu módulo. - Alternativa (SPA):
localStoragey mandarlo comoAuthorization: Bearer <token>en tus llamadas.
Ese JWT dura 24 h. Cuando vence, el usuario tiene que volver a pasar por el SSO (o, si tu módulo también habla con el core, podés usar POST /auth/refresh mientras siga vigente).
3) Validar el JWT en cada request
En cada request protegido de tu módulo, validá el JWT localmente contra el JWKS del core. No hace falta llamar al core en cada request.
Endpoint del JWKS: GET https://api.healthcare.cantero.ar/.well-known/jwks.json
Pasos:
- Descargá y cacheá el JWKS (respetá rotación de claves vía el
kiddel header del token). - Verificá la firma con la clave pública correspondiente (algoritmo RS256, y solo RS256).
- Validá
exp(expiración). - Leé los claims de negocio (
user_id,permissions).
Detalle completo y ejemplos en JWKS_VALIDATION.md.
Estructura del JWT que vas a recibir
Header:
{ "alg": "RS256", "typ": "JWT", "kid": "a1b2c3d4e5f6a7b8" }
Claims (payload):
{
"user_id": 42,
"permissions": ["users:read", "locations:read", "…"],
"iat": 1751846400,
"exp": 1751932800
}
user_id— id del usuario en el core.permissions— lista plana de permisos (recurso:accion). Usala para tu autorización.exp— expiración (24 h desde la emisión). Validala siempre.
Nota: hoy el token no trae
iss/aud. Validá firma +exp+ los claims de negocio.
Ejemplos de código
Node.js / Express (canje + validación con JWKS)
import express from "express";
import fetch from "node-fetch";
import { createRemoteJWKSet, jwtVerify } from "jose";
const CORE = "https://api.healthcare.cantero.ar";
const JWKS = createRemoteJWKSet(new URL(`${CORE}/.well-known/jwks.json`)); // cachea solo
const app = express();
// 1) Callback: recibe el ticket y lo canjea
app.get("/auth/sso", async (req, res) => {
const { ticket, redirect = "/" } = req.query;
try {
const r = await fetch(`${CORE}/auth/sso-exchange`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ ticket }),
});
if (!r.ok) return res.redirect("/login");
const { token } = await r.json();
// 2) Sesión propia, en tu dominio
res.cookie("session", token, {
httpOnly: true,
secure: true,
sameSite: "lax",
maxAge: 24 * 3600 * 1000,
});
res.redirect(redirect);
} catch {
res.redirect("/login");
}
});
// 3) Middleware: valida el JWT del core en cada request
async function requireAuth(req, res, next) {
const token = req.cookies.session;
if (!token) return res.status(401).json({ error: "no session" });
try {
const { payload } = await jwtVerify(token, JWKS, { algorithms: ["RS256"] });
req.user = { id: payload.user_id, permissions: payload.permissions || [] };
next();
} catch {
res.status(401).json({ error: "invalid token" });
}
}
Go / Gin (canje del ticket)
// GET /auth/sso?ticket=…&redirect=…
const coreBaseURL = "https://api.healthcare.cantero.ar"
func SSOCallbackHandler(c *gin.Context) {
ticket := c.Query("ticket")
redirect := c.DefaultQuery("redirect", "/")
body, _ := json.Marshal(map[string]string{"ticket": ticket})
client := &http.Client{Timeout: 5 * time.Second}
resp, err := client.Post(coreBaseURL+"/auth/sso-exchange",
"application/json", bytes.NewReader(body))
if err != nil || resp.StatusCode != http.StatusOK {
c.Redirect(http.StatusFound, "/login")
return
}
defer resp.Body.Close()
var out struct{ Token string `json:"token"` }
json.NewDecoder(resp.Body).Decode(&out)
// Cookie de sesión en TU dominio.
c.SetCookie("session", out.Token, 86400, "/", "healthgrid.cantero.ar", true, true)
c.Redirect(http.StatusFound, redirect)
}
Para la validación del JWT en Go, ver el ejemplo con github.com/MicahParks/keyfunc en
JWKS_VALIDATION.md.
Prueba rápida con curl
# Canje del ticket (lo que hace tu backend)
curl -sS -X POST https://api.healthcare.cantero.ar/auth/sso-exchange \
-H 'Content-Type: application/json' \
-d '{"ticket":"PEGA_ACA_EL_TICKET"}'
# → { "user": {...}, "token": "eyJ…" }
# El JWKS que usás para validar los JWT
curl -sS https://api.healthcare.cantero.ar/.well-known/jwks.json
Variante: módulo SPA sin backend (Angular / React)
Si tu módulo es una SPA sin backend propio (Angular, React, etc.), no tenés un
servidor donde hacer el canje back-channel. En ese caso el canje se hace desde el
navegador, directo contra el endpoint público POST /auth/sso-exchange.
Es un patrón aceptable para SPAs porque:
- El
ticketes de un solo uso y expira en ~60 s: aunque quede un instante en la URL, es de bajo valor y no se puede reusar. - Se canjea de inmediato sobre HTTPS por el JWT, que se guarda en tu propio almacenamiento (igual que harías tras un login normal).
- Después de canjear, limpiás el
ticketde la URL (replaceState/replaceUrl) para que no quede en el historial.
Si tu módulo sí tiene backend, preferí el canje servidor-a-servidor de las secciones anteriores: el ticket nunca llega a exponerse al navegador.
El flujo, para una SPA
sequenceDiagram
participant O as Otro módulo
participant S as Tu SPA (navegador)
participant C as Core API<br/>(api.healthcare.cantero.ar)
O->>S: 1) redirect a /auth/sso?ticket=…&redirect=/x
S->>C: 2) POST /auth/sso-exchange<br/>{ "ticket": "…" }
C-->>S: { user, token } (JWT)
Note over S: 3) guarda el JWT, limpia la URL<br/>y navega a /x
La ruta de callback es una ruta del router de tu SPA (/auth/sso), no un endpoint de
servidor. El usuario llega ahí con ?ticket=…&redirect=/ruta-interna.
Ejemplo: Angular
Ruta pública en tu app.routes.ts:
{
path: 'auth/sso',
loadComponent: () =>
import('./features/auth/sso/sso.component').then((m) => m.SsoComponent),
},
Servicio: canje del código por una sesión (reutiliza tu misma lógica de login):
// AuthService
establishSessionFromTicket(ticket: string): Observable<SessionUser> {
return this.http
.post<ApiAuthResponse>(`${this.baseUrl}/sso-exchange`, { ticket })
.pipe(
map((res) => this.persistSession(res)), // guarda el JWT (localStorage/cookie)
catchError((err) => throwError(() => toError(err))),
);
}
Componente de callback: lee el ticket, lo canjea y navega:
ngOnInit(): void {
// Acepta el ticket en query (?ticket=) o en fragment (#ticket=), y un redirect interno.
const snap = this.route.snapshot;
const frag = snap.fragment ? new URLSearchParams(snap.fragment) : null;
const ticket = frag?.get('ticket') ?? snap.queryParamMap.get('ticket');
const redirect = frag?.get('redirect') ?? snap.queryParamMap.get('redirect');
if (!ticket) {
this.error.set('El enlace de acceso no incluye un ticket SSO.');
return;
}
this.auth.establishSessionFromTicket(ticket).subscribe({
next: () => {
const target = this.safeRedirect(redirect) ?? '/';
// replaceUrl: el código no queda en el historial de navegación.
void this.router.navigateByUrl(target, { replaceUrl: true });
},
error: (err: Error) => this.error.set(err.message),
});
}
/** Sólo rutas internas absolutas; descarta URLs externas (open redirect). */
private safeRedirect(path: string | null): string | null {
if (!path) return null;
if (!path.startsWith('/') || path.startsWith('//') || path.startsWith('/\\')) return null;
return path;
}
El mismo esquema aplica a React: una ruta /auth/sso que, al montarse, lee el ticket, hace
el POST /auth/sso-exchange, guarda el JWT y hace navigate(redirect, { replace: true }).
Consideraciones de seguridad para SPAs
- Canjeá apenas montás la ruta y limpiá el
ticketde la URL (replaceUrl/replaceState). - Validá el
redirect: sólo rutas internas absolutas (/algo), nunca URLs externas ni//host(open redirect). - El JWT queda en el navegador (localStorage o cookie). Es el mismo modelo de riesgo que tu login normal; no lo empeora respecto de lo que ya hacés hoy.
- Serví tu SPA siempre por HTTPS.
Checklist de implementación
- Ruta de callback (
/auth/sso?ticket=…&redirect=…) en tu módulo. - Canje del ticket desde el backend si tenés uno (server-to-server); si sos una SPA sin backend, canjealo desde el navegador (ver Variante SPA).
- Canjear apenas llega (el ticket expira en ~60 s y es de un solo uso).
- Guardar el JWT en tu propia sesión (cookie
HttpOnly+Securerecomendado). - Validar el
redirectpara evitar open redirect (permití solo rutas internas / una allowlist). - Cachear el JWKS y validar firma RS256 +
expen cada request. - Manejar
401del canje redirigiendo al login. - Usar HTTPS en tu callback (el JWT viaja en la respuesta del canje).
Preguntas frecuentes
¿Necesito una clave secreta del core? No. Validás los JWT con la clave pública del JWKS. Nada secreto se comparte.
¿Qué pasa si el ticket expiró o ya se usó?
El canje devuelve 401. Mandá al usuario al login; reinicia el flujo desde el módulo origen y obtiene un ticket nuevo.
¿Puedo canjear el ticket desde el frontend (SPA sin backend)? Sí. Si tu módulo es una SPA sin backend (Angular, React, etc.), el canje se hace desde el navegador contra el endpoint público. Es un patrón válido porque el ticket es de un solo uso y de vida corta. Seguí la sección Variante: módulo SPA sin backend. Si tenés backend, preferí el canje servidor-a-servidor.
El JWT vence a las 24 h. ¿Cómo lo renuevo?
Si tu módulo se comunica con el core, podés usar POST /auth/refresh con el token todavía vigente. Si no, el usuario vuelve a pasar por el SSO.
¿Cómo autorizo acciones?
Con el claim permissions del JWT (formato recurso:accion, ej. users:read).