Nuevos scopes SMART onFHIR v2

En v2026.1 hemos introducido soporte para una autorización más robusta y realista para vuestros endpoints FHIR.

Esto se consigue utilizando scopes detallados de SMART on FHIR v2.

Enfoque: no en SMART en general, sino en los scopes detallados; ejemplo práctico sencillo

He profundizado en el tema de SMART on FHIR en el pasado; por ejemplo, podéis ver este artículo que escribí (con una aplicación Open Exchange asociada y una serie de vídeos relacionada).

Otros también han tratado este tema; por ejemplo, @Luis Angel Pérez Ramos en su serie de artículos Developing SMART on FHIR Applications with Auth0 and InterSystems IRIS FHIR Server, @Nicole Sun en su artículo SMART on FHIR EHR Launch with IRIS for Health, y @Kate Lau en su serie de dos partes Using Postman for testing the OAuth 2.0 of the InterSystems FHIR repository.

Además, este vídeo de Learning Services — Configuring OAuth for InterSystems FHIR Server — lo explica muy bien e incluso muestra parte del filtrado de resultados basado en los últimos ámbitos SMART que vamos a tratar aquí.

Sin embargo, en los artículos y ejemplos mencionados anteriormente utilizamos InterSystems IRIS como servidor OAuth o un servidor OAuth en la nube de terceros (como Auth0 de Okta). En este artículo y ejemplo, en cambio, queremos hacer algunas cosas de forma diferente:

1. Queremos utilizar un servidor OAuth de terceros, pero no uno para el que tengáis que registraros (y quizá pagar). Este será Keycloak.

2. Queremos encargarnos de toda la configuración por vosotros en un ejemplo dockerizado -

• InterSystems IRIS for Health en funcionamiento con un endpoint FHIR definido, incluyendo un cliente OAuth configurado y algunos recursos en el repositorio.
• Keycloak en funcionamiento con un cliente correspondiente al cliente OAuth de IRIS.
• Una colección de Postman que os permita realizar pruebas y demostraciones rápidamente.

3.Queremos centrarnos en los ámbitos SMART detallados, relativamente más recientes, y no en los básicos. Este es realmente el núcleo del asunto aquí. Los otros dos puntos anteriores son facilitadores que nos permiten centrarnos únicamente en este aspecto.

Scopes SMART: la versión detallada y granular

Arriba he generado (gracias a NotebookLM) una bonita infografía que resume la sintaxis general y el uso de los ámbitos SMART.

En particular, queremos centrarnos en la parte de filtros, es decir, la parte de los ámbitos que aparece a partir del signo de interrogación (?).

Aquí podéis utilizar la sintaxis estándar de búsqueda de FHIR, con los parámetros de búsqueda estándar de FHIR.

Tomemos este ejemplo:

En lugar de permitir simplemente el acceso (lectura y búsqueda, en este caso) a todas las categorías de Observations, aquí solo estamos permitiendo acceso a los resultados de laboratorio (category=laboratory).

Así, para ilustrarlo, en lugar de obtener acceso a un conjunto como este:

Podemos limitar el acceso a un conjunto como este:

Esto permite un enfoque de control de acceso basado en atributos (ABAC, Attribute-Based Access Control) para acceder a datos FHIR (podéis consultar más sobre este tema en la documentación de FHIR).

Algunas normativas nacionales exigen aplicar este tipo de control de acceso, incluyendo por ejemplo el uso de etiquetas de seguridad para limitar el acceso a los datos.

Un ejemplo es la certificación ONC en Estados Unidos, pero otros países tienen requisitos similares.

Por tanto, dar soporte a esto no solo es importante para asegurar vuestros datos, sino que también es un requisito legal obligatorio en un número creciente de lugares.

El poder de filtrar (o no hacerlo)

Podéis controlar si, cuando la petición FHIR no se ajusta exactamente a los ámbitos, se filtran los datos no autorizados y se devuelve únicamente lo permitido, o si se rechaza la petición y se devuelve un código de estado HTTP 403.

Este ajuste se encuentra en la configuración de autorización del endpoint FHIR:

Ten en cuenta que esto no solo es relevante para los ámbitos detallados, sino también cuando no se utiliza el filtro “?”. Por ejemplo, si utilizáis _include o la operación $everything, esto podría filtrar “tipos de recurso completos” del conjunto de resultados.

Aquí tenéis un ejemplo para ilustrarlo:

Ejemplo de búsqueda de Observations

Supongamos que ejecutamos una búsqueda de Observations utilizando autenticación básica, por lo que no se aplican ámbitos SMART.

Podéis ver aquí que estamos obteniendo 793 recursos.

Si miramos un poco más de cerca, podemos ver que, por ejemplo, el primero tiene una categoría de vital-signs:

Y, en comparación, si utilizo autenticación OAuth 2 y tengo un ámbito user/Observation.rs?category=laboratory, obtenemos solo 385 recursos (frente a los 793 anteriores):

Y el primero (en lugar de vital-signs) es, como era de esperar, de la categoría laboratory:

Una comparación similar puede verse con la operación $everything -

Ejemplo de $everything

Con autenticación básica (sin ámbitos):

Obtenemos, por supuesto, el propio recurso Patient, pero también recursos relacionados (según el ejemplo anterior): Encounter, Practitioner, Organization, Condition, Claim, ExplanationOfBenefit, Observation (de varios tipos), MedicationRequest, Immunization y DiagnosticReport.

Con OAuth (y ámbitos que incluyen únicamente: user/Patient.rs and user/Observation.rs?category=laboratory):

Aquí, aparte del propio recurso Patient, solo obtenemos Observations (de tipo laboratorio), y ningún otro recurso relacionado.

Es decir, 171 recursos frente a 35 después del filtrado.

Algunas notas técnicas

• Como se ha mencionado, necesitáis estar al menos en la versión v2026.1 para disponer de esta funcionalidad.
• La mayoría de las interacciones FHIR están soportadas para este tipo de ámbitos (Create, Read, Update, Delete y Search), aunque algunas todavía no lo están (History, VRead).
• Tal y como se ha indicado, en la cadena de filtro de búsqueda podéis utilizar la sintaxis estándar de búsqueda de FHIR, pero algunos parámetros simplemente no tendrán sentido en este contexto (como _include), por lo que algunos pueden provocar el rechazo de la petición y otros pueden ser simplemente ignorados; consultad la documentación de referencia para más detalles.
• También hay notas específicas sobre $everything y $lastn; de nuevo, consultad la documentación para más información.

Depuración

Al usar OAuth en general, y especialmente con ámbitos SMART, no todo funcionará siempre como se espera al principio.

Los mejores recursos para depurar vuestra situación serán el log del servidor FHIR (FSLOG) y el log de peticiones HTTP (ISCLOG); podéis ver más detalles en la documentación aquí.

Para ilustrarlo, aquí tenéis un ejemplo:

Supongamos que esta vez hemos desactivado la opción de filtrado de resultados y estamos intentando realizar una búsqueda de todas las Observations, mientras que nuestro ámbito solo permite las de laboratorio.

Obtendremos un estado HTTP 403 Forbidden:

Y si activamos el log del servidor FHIR, podemos ver algo como esto:

Demostración de ejemplo

Abordar un tema de forma práctica siempre ayuda y profundiza la comprensión, así que os animo a probar la aplicación de Open Exchange relacionada. Es un ejemplo muy sencillo de “click & go”, donde un docker compose construirá e iniciará todo lo que necesitáis, e incluye una colección de Postman de ejemplo para que podáis hacer pruebas fácilmente.