RFC-002 — Identidad derivada solo del token (JWT-only)¶
Proyecto: {{PROJECT_NAME}} · Clase SaMD: {{SAMD_CLASS}} · Versión: v1.1 · Fecha: 2026-11-07
RFC del SaMD Starter Kit. Ejemplo didáctico de una decisión de diseño de la capa de API/seguridad. Documenta cómo el backend determina "quién es el usuario" en cada request.
Metadatos¶
| Campo | Valor |
|---|---|
| ID | RFC-002 |
| Estado | Implementado |
| Autor | Equipo de Backend |
| Revisores | Responsable de Seguridad, Responsable de Gestión de Riesgo (ISO 14971) |
| Fecha de propuesta | 2026-01-16 |
| Fecha de decisión | 2026-01-22 |
| Capa afectada | API / seguridad |
| Clase de seguridad del ítem | B |
1. Contexto¶
El backend {{BACKEND_STACK}} expone endpoints que leen y mutan PHI de un sujeto concreto (p. ej. GET /records/me, POST /scales/{id}/answers). Cada request autenticado llega con un token (JWT) emitido por el proveedor de identidad, que el backend verifica y decodifica en una dependencia de autenticación (en el kit, app/core/security.py::get_current_user_id).
El riesgo aparece cuando un endpoint, por conveniencia, acepta además un identificador de usuario desde el cuerpo, el query string o un header (?user_id=..., {"user_id": ...}). En ese momento el cliente puede declarar ser cualquiera.
2. Problema¶
Si cualquier endpoint deriva la identidad del sujeto desde un dato controlado por el cliente, un usuario autenticado puede sustituir el identificador por el de otro paciente y leer o mutar PHI ajena (escalada horizontal / IDOR). Un solo endpoint que confíe en un user_id de entrada rompe el aislamiento de todos los pacientes.
3. Alternativas consideradas¶
| # | Alternativa | Pros | Contras | Riesgo SaMD |
|---|---|---|---|---|
| A | Confiar en el user_id que envía el cliente |
Trivial de implementar; flexible para herramientas internas | El cliente declara su propia identidad → IDOR directo; imposible de auditar con confianza; un único endpoint descuidado compromete todo | INACEPTABLE: acceso a PHI ajena por manipulación trivial del request |
| B | Identidad solo del token (JWT-only) (elegida) | El sujeto sale exclusivamente del token verificado (en el kit: firma + exp + sub; aud/iss, ver §4); el cliente no puede declarar ser otro; superficie de IDOR cerrada por construcción |
Requiere disciplina: ningún endpoint debe aceptar user_id de entrada; obliga a lookup de sujeto server-side |
Aceptable: la identidad es no-falsificable sin la clave del emisor |
| C | mTLS (identidad por certificado de cliente) | Identidad criptográfica fuerte a nivel de transporte | Sobrecarga operativa enorme para clientes móviles/web públicos; gestión y rotación de certificados por usuario inviable a escala; no resuelve la autorización fina, solo autentica el canal | Desproporcionado para el modelo de cliente; no cierra IDOR por sí solo |
| D | No hacer nada / mezclar criterios por endpoint | — | Inconsistencia: algunos endpoints seguros, otros no; el auditor no puede garantizar la propiedad globalmente | INACEPTABLE |
4. Decisión¶
Se adopta la Alternativa B: JWT-only. La identidad del sujeto se deriva exclusivamente del token decodificado y verificado, nunca de body, query ni header.
Detalles de construcción:
- Verificación del token en el kit (app/core/security.py::get_current_user_id): firma válida (HS256 contra SECRET_KEY) y claims exp y sub obligatorios; un token vencido, mal formado o sin sub → 401 (sin filtrar el motivo técnico). El kit NO valida aud ni iss: validarlos (audience e issuer esperados del proveedor de identidad) es responsabilidad del proyecto derivado, que debe agregarlos al decode y cubrirlos con su propio test.
- Regla dura: ninguna firma de endpoint ni schema de entrada acepta user_id/subject_id. El identificador que cuenta es el del claim del token. En el kit, app/routers/notes.py obtiene el dueño solo de get_current_user_id, y tests/test_hard_rules.py::test_identity_comes_from_token_not_from_body verifica que un user_id enviado en el body se ignora. Un test de contrato global que falle si cualquier router lo expone NO existe hoy (deuda abajo).
- Autorización por recurso: para acceder a un recurso, el owner_id del recurso debe coincidir con el sujeto del token; si no, 404/403 (preferentemente 404 para no filtrar existencia).
- Multi-sujeto (cuando aplica, p. ej. roles distintos): la resolución del tipo de sujeto también parte del token + lookup server-side, nunca de un campo declarado por el cliente.
5. Consecuencias¶
- Positivas: la superficie de IDOR por suplantación de identidad queda cerrada por construcción; los logs de auditoría reflejan al sujeto real; la propiedad es verificable globalmente con un test de contrato.
- Negativas / costo: cada endpoint que necesite operar sobre "otro" sujeto legítimamente (p. ej. un profesional sobre su paciente vinculado) debe pasar por una verificación de vínculo explícita server-side, no por un
user_idde entrada. - Impacto en consumidores (§5.6): cualquier handler que hoy lea
user_iddel request debe migrar al claim del token; búsqueda global deuser_iden routers y schemas obligatoria. - Fail-safe: token ausente/inválido/expirado → 401 con mensaje empático; recurso de otro sujeto → 404/403 sin traceback ni metadatos internos.
- Deuda técnica generada (a abrir en el proyecto derivado; el kit no la lleva en su índice de deuda):
D-SEC-IDOR-CONTRACT-TEST-01— test de contrato que falle si cualquier endpoint reintroduceuser_idde entrada; y la validación deaud/issdescrita en §4.
6. Trazabilidad¶
| Vínculo | Referencia |
|---|---|
| Requisito(s) | REQ-SEC-02 — Identidad solo del token (JWT-only) |
| Riesgo(s) ISO 14971 | R002 — Escalada horizontal: otro usuario accede a PHI ajena por suplantación de identidad (Sev. Crítica × Prob. Remota → INACEPTABLE → residual Aceptable) |
| Código | app/core/security.py::get_current_user_id; regla "sin user_id de entrada" aplicada en app/routers/notes.py::create_note |
| Test(s) de verificación | tests/test_hard_rules.py::test_identity_comes_from_token_not_from_body, tests/test_hard_rules.py::test_owner_isolation_between_users, tests/test_hard_rules.py::test_token_missing_sub_claim, tests/test_hard_rules.py::test_expired_token_is_rejected |
| Entrada en Master Map | v1.0 (trazabilidad corregida en v1.1 de esta RFC) |
7. Historial¶
| Versión | Fecha | Autor | Cambio |
|---|---|---|---|
| v0.1 | 2026-01-16 | Equipo de Backend | Propuesta inicial |
| v1.0 | 2026-01-22 | Equipo de Backend | Aceptada e implementada; auditoría de routers + test de contrato anti-IDOR |
| v1.1 | 2026-11-07 | Equipo de Plataforma | Se corrige la trazabilidad al código real del kit (app/core/security.py::get_current_user_id) y a tests que existen hoy; la cita anterior (app/dependencies.py, tests/test_identity_jwt_only.py) apuntaba a archivos que el kit no tiene. Se aclara que el kit verifica firma + exp + sub y NO aud/iss (responsabilidad del derivado). La decisión (JWT-only) no cambia |
Navegación: Índice del DHF · Master Map