SMART App Launch explicado: ámbitos, lanzamiento, PKCE

Respuesta corta: SMART App Launch (SMART on FHIR) es la especificación de HL7 sobre cómo una aplicación obtiene acceso autorizado a un servidor FHIR en nombre de un usuario. Es OAuth 2.0 y OpenID Connect con convenciones específicas de FHIR: un documento de descubrimiento en .well-known/smart-configuration; dos modos de lanzamiento (lanzamiento desde EHR, donde el EHR abre la aplicación en el contexto del paciente actual, y lanzamiento independiente, donde el usuario abre la aplicación y elige un paciente); scopes en una sintaxis compatible con FHIR (patient/Observation.rs significa leer y buscar Observaciones del paciente en contexto); contexto de lanzamiento devuelto con el token (qué paciente, qué encuentro); y servicios de backend para acceso de sistema a sistema con autenticación de cliente JWT firmada. SMART v2 (a partir de 2021) hizo que PKCE fuera obligatorio, añadió scopes granulares y autenticación de cliente asimétrica, y es la versión que requieren los programas nacionales.

Paso 1: descubrimiento

El descubrimiento de SMART App Launch comienza cuando la aplicación obtiene el documento .well-known/smart-configuration del servidor FHIR, que enumera los puntos de conexión de autorización y tokens, las capacidades admitidas (lanzamiento de EHR, lanzamiento independiente, clientes públicos y confidenciales, OpenID Connect, permisos de paciente y usuario), los ámbitos admitidos, los métodos de desafío de código PKCE y los tipos de concesión, para que la aplicación sepa a dónde enviar al usuario.

GET https://fhir.example-hospital.org/.well-known/smart-configuration

{
  "issuer": "https://auth.example-hospital.org",
  "authorization_endpoint": "https://auth.example-hospital.org/authorize",
  "token_endpoint": "https://auth.example-hospital.org/token",
  "introspection_endpoint": "https://auth.example-hospital.org/introspect",
  "capabilities": ["launch-ehr", "launch-standalone", "client-public", "client-confidential-asymmetric", "sso-openid-connect", "context-ehr-patient", "context-standalone-patient", "permission-patient", "permission-user", "permission-v2", "permission-offline"],
  "scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "patient/*.rs", "user/*.rs", "offline_access"],
  "code_challenge_methods_supported": ["S256"],
  "grant_types_supported": ["authorization_code", "client_credentials"]
}

La aplicación aprende a dónde enviar al usuario y qué soporta el servidor.

Paso 2: lanzamiento

SMART App Launch tiene dos modos de lanzamiento. En un lanzamiento de EHR, el médico abre la aplicación dentro del EHR, que pasa un parámetro iss (el servidor FHIR) y un token de lanzamiento opaco que codifica el paciente y el encuentro actuales. En un lanzamiento independiente, el usuario abre la aplicación directamente y el servidor de autorización le pide que elija o confirme un paciente.

Lanzamiento desde EHR. El médico hace clic en la aplicación dentro del EHR; el EHR abre la URL de lanzamiento de la aplicación con dos parámetros: iss (el servidor FHIR) y launch (un token opaco que codifica el paciente y el encuentro actuales). La aplicación debe repetir launch en su solicitud de autorización con el scope launch.

Lanzamiento independiente. El usuario abre la aplicación directamente; la aplicación conoce el servidor FHIR (elegido o configurado) y solicita contexto con launch/patient; el servidor de autorización pide al usuario que elija o confirme un paciente.

Paso 3: código de autorización con PKCE

El paso de autorización de SMART es el flujo de código de autorización OAuth 2.0 con PKCE: la aplicación envía al usuario al punto de conexión de autorización con sus ámbitos, el aud del servidor FHIR y un desafío de código; el usuario se autentica y aprueba; la aplicación intercambia el código devuelto y el verificador de código por un token de acceso que llega junto con el contexto de lanzamiento.

GET https://auth.example-hospital.org/authorize?
  response_type=code&client_id=my-app&redirect_uri=https://app.example.org/cb
  &scope=openid%20fhirUser%20launch%20patient/Observation.rs%20patient/Condition.rs%20offline_access
  &state=af0ifjsldkj&aud=https://fhir.example-hospital.org
  &launch=xyz123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

El usuario se autentica (con el proveedor de identidad del hospital) y aprueba los scopes; el servidor redirige de vuelta con un code; la aplicación lo intercambia:

POST https://auth.example-hospital.org/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=https://app.example.org/cb&client_id=my-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid fhirUser launch patient/Observation.rs patient/Condition.rs offline_access",
  "refresh_token": "a8c3...",
  "id_token": "eyJhbGciOi...",
  "patient": "Patient/123",
  "encounter": "Encounter/456",
  "fhirUser": "Practitioner/42",
  "need_patient_banner": true,
  "smart_style_url": "https://ehr.example.org/styles/smart.json"
}

El contexto de lanzamiento (patient, encounter, fhirUser) llega junto con el token. Los clientes públicos (aplicaciones móviles y de navegador) utilizan PKCE y no tienen secreto de cliente; los clientes confidenciales se autentican con un secreto o, preferiblemente, con un JWT firmado (private_key_jwt) bajo el método asimétrico.

Scopes

Los ámbitos de SMART on FHIR v2 utilizan la sintaxis contexto/recurso.permisos, donde el contexto es patient, user o system y los permisos combinan c, r, u, d y s para crear, leer, actualizar, eliminar y buscar, como en patient/Observation.rs. Los ámbitos granulares añaden un filtro, openid y fhirUser proporcionan la identidad del usuario, los ámbitos de lanzamiento solicitan contexto y offline_access solicita un token de actualización.

Sintaxis SMART v2: <contexto>/<recurso>.<permisos> donde el contexto es patient (el paciente en contexto), user (lo que el usuario pueda ver) o system (backend), y los permisos son cualquiera de c crear, r leer, u actualizar, d eliminar, s buscar, en ese orden: patient/Observation.rs, user/Patient.rs, system/*.cruds. Los scopes granulares añaden un filtro: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser proporcionan un ID token y la identidad FHIR del usuario; launch, launch/patient, launch/encounter solicitan contexto; offline_access un token de actualización para usar cuando el usuario está ausente, online_access uno válido solo durante la sesión. La sintaxis v1 (patient/Observation.read) todavía es aceptada por muchos servidores.

Servicios de backend

Para un sistema que actúa sin un usuario (una exportación nocturna, un motor de integración), SMART Backend Services utiliza client_credentials con una aserción JWT firmada (las claves públicas del cliente publicadas en una URL JWKS) y scopes system/. Sin usuario, sin contexto de lanzamiento, registro estricto.

Ejecución segura

Ejecutar SMART App Launch de forma segura significa registrar URIs de redireccionamiento exactas, nunca usar el flujo implícito, almacenar y rotar tokens de actualización de forma segura, validar el estado y el aud de los tokens de ID, verificar tokens en cada llamada a la API, aplicar tanto los ámbitos como el contexto del paciente en la capa de datos para que un token para un paciente nunca lea otro, y registrar cada acceso.

Registre URIs de redirección exactas; nunca use el flujo implícito; almacene los tokens de actualización de forma segura y rótelos; valide state; verifique el aud de los ID tokens; verifique los tokens en cada llamada a la API (introspección o validación JWT) y aplique los scopes y el contexto del paciente en la capa de datos, porque un token para Patient/123 nunca debe leer Patient/124; registre cada acceso (Seguridad e identidad: el mapa). SMART también define Patient Access Brands, una forma para que las aplicaciones muestren a los usuarios a qué organizaciones pueden conectarse, e interopera con SMART Health Links para el intercambio iniciado por el paciente.

Dónde se requiere

Las reglas de acceso del paciente de EE. UU. requieren que los EHR certificados soporten SMART App Launch y Backend Services; los programas nacionales en Europa lo adoptan para el acceso a aplicaciones (MedMij de los Países Bajos utiliza OAuth 2.0 con convenciones equivalentes); el IPS y muchas guías de implementación lo asumen. Consulte TEFCA y Registros de salud electrónicos nacionales.

En Anpheros

Anpheros Platform utiliza OAuth 2.0 con PKCE para aplicaciones y autenticación de cliente JWT firmada para backends, con scopes derivados del consentimiento de la persona y el contexto del paciente aplicado en cada solicitud. El sitio para desarrolladores documenta la autenticación y el patrón de backend SMART on FHIR para construir sobre él.

Páginas relacionadas

Fuentes

Preguntas frecuentes

¿Es SMART on FHIR lo mismo que OAuth 2.0?

Es OAuth 2.0 y OpenID Connect con adiciones específicas de FHIR: descubrimiento, contexto de lanzamiento, la sintaxis de scope y los servicios de backend. Cualquier biblioteca OAuth funciona; las convenciones SMART son lo que hace que una aplicación sea portable entre servidores FHIR.

¿Necesito PKCE para una aplicación del lado del servidor?

En SMART v2, sí, para todos los clientes que utilizan el flujo de código de autorización. Los clientes confidenciales añaden autenticación de cliente (un secreto o un JWT firmado) encima.

¿Cuál es la diferencia entre los scopes patient/ y user/?

patient/ limita el acceso al único paciente en el contexto de lanzamiento; user/ otorga lo que el usuario autenticado tenga permitido ver, a través de pacientes. Las aplicaciones orientadas al paciente utilizan patient/; las aplicaciones para médicos a menudo utilizan user/ con contexto.

¿Puede una aplicación SMART escribir en el registro?

Si se le otorgan permisos de creación o actualización (c, u) en sus scopes y el servidor lo permite. Muchas implementaciones otorgan a las aplicaciones de pacientes solo lectura y búsqueda, y enrutan las escrituras a través de recursos específicos como QuestionnaireResponse.

Anpheros Platform

Pruébalo gratis en el sandbox

Tu primera llamada FHIR en 5 minutos. Una API HL7 FHIR R4 con el consentimiento del paciente integrado: pruébala en el sandbox y luego conecta tu propia app o sistema de clínica.

Crear un sandbox gratis Abrir la app de ejemplo →Código inicial (Python) →Colección de Postman →Leer las guías para desarrolladores →

Gratis · 30 pacientes sintéticos · sin tarjeta

Esta guía es informativa y no sustituye la consulta médica. Para decisiones sobre tu salud, habla con tu médico. En una emergencia, llama al número de emergencias local (112 en Europa).

Escrito por

El equipo de Anpheros

Anpheros crea un historial médico que el paciente controla y puede compartir con cualquier clínica, en una plataforma HL7 FHIR R4, con sede en la UE. Estas guías te ayudan a entender y organizar tu salud; no reemplazan a tu médico.

Sobre Anpheros →