Modulo-6 / documentation /integrations /M10_SSO_INTEGRATION_GUIDE.md
juampisor's picture
Organizacion de documentacion
3ac37aa
|
Raw History Blame Contribute Delete
14 kB

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/sso es la convención común. Los ejemplos usan healthgrid.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

  1. Una ruta de callback /auth/sso que reciba el redirect con un ticket.
  2. 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).
  3. Tu propia sesión en tu dominio (cookie / localStorage) con ese JWT.
  4. 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
  1. El navegador llega a tu app con una URL tipo: https://healthgrid.cantero.ar/auth/sso?ticket=<opaco>&redirect=/dashboard
  2. Tu backend toma el ticket y lo canjea contra el core (paso servidor-a-servidor; el ticket no se vuelve a exponer al navegador).
  3. Recibís { user, token }. Guardás el token en tu propia sesión y redirigís al usuario a redirect.

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): localStorage y mandarlo como Authorization: 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:

  1. Descargá y cacheá el JWKS (respetá rotación de claves vía el kid del header del token).
  2. Verificá la firma con la clave pública correspondiente (algoritmo RS256, y solo RS256).
  3. Validá exp (expiración).
  4. 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 ticket es 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 ticket de 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 ticket de 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+Secure recomendado).
  • Validar el redirect para evitar open redirect (permití solo rutas internas / una allowlist).
  • Cachear el JWKS y validar firma RS256 + exp en cada request.
  • Manejar 401 del 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).