File size: 15,838 Bytes
624c7c9 15c2525 624c7c9 15c2525 624c7c9 15c2525 624c7c9 01e0bb5 624c7c9 15c2525 624c7c9 15c2525 624c7c9 15c2525 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 | # 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`](M10_SSO_INTEGRATION_GUIDE.md). El detalle de la integración vive en [`M6_DISEÑO.md`](M6_DISEÑO.md) §11 y el mapeo de roles en [`roles.md`](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
```mermaid
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**
```json
{ "ticket": "9f2c1b7a3e045e6f7a8b9c0d1e2f3a4b" }
```
`ticket`: string no vacío. Es el mismo ticket recibido en la query del callback.
**Response `200`**
```json
{
"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`):
```json
{ "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`:
```ts
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.
```ts
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
```ts
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
```ts
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):
```ts
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.
```mermaid
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`**
```json
{ "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
```ts
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`](M10_SSO_INTEGRATION_GUIDE.md) — contrato genérico del SSO del Core (ticket, JWKS, ejemplos Angular/React/Go/Node).
- [`M6_DISEÑO.md`](M6_DISEÑO.md) §11 — detalle técnico de la integración de auth en M6.
- [`roles.md`](roles.md) §6 — mapeo de roles del Core a roles internos de M6 y matriz de permisos por endpoint.
- [`M6_openapi.json`](M6_openapi.json) — contrato exacto de `/auth/sso-exchange`/`/auth/sso-ticket` (schemas `SSOExchangeRequest`/`SSOExchangeResponse`/`SSOTicketResponse`).
|