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`).