Compartir vía

Introducción a SMART en FHIR

  • Artículo

Importante

Azure API for FHIR se retirará el 30 de septiembre de 2026. Siga las estrategias de migración para realizar la transición a servicio FHIR® de Azure Health Data Services en esa fecha. Debido a la retirada de Azure API for FHIR, no se permitirán nuevas implementaciones a partir del 1 de abril de 2025. El servicio FHIR de Azure Health Data Services es la versión evolucionada de la API de Azure para FHIR que permite a los clientes administrar FHIR, DICOM y los servicios de tecnologías médicas con integraciones en otros servicios de Azure.

Substitutable Medical Applications and Reusable Technologies (SMART on FHIR) es un estándar sanitario mediante el cual las aplicaciones pueden acceder a la información clínica a través de un almacén de datos. Agrega una capa de seguridad basada en estándares abiertos, como OAuth2 y OpenID Connect, a interfaces de FHIR para permitir la integración con sistemas EHR. El uso de SMART on FHIR proporciona ventajas importantes, entre las que se incluyen:

  • Las aplicaciones tienen un método conocido para obtener autenticación o autorización en un repositorio de FHIR.
  • Los usuarios que acceden a un repositorio de FHIR con SMART on FHIR solo pueden acceder a los recursos asociados al usuario, en lugar de a todos los datos del repositorio.
  • Los usuarios tienen la capacidad de conceder a las aplicaciones acceso a un nuevo conjunto limitado de sus datos mediante el uso de ámbitos clínicos SMART.

Los tutoriales siguientes se proporcionan los pasos para habilitar las aplicaciones SMART on FHIR con el servicio FHIR.

Requisitos previos

SMART en FHIR usa ejemplos de software de código abierto (SMART en FHIR [mejorado])

Paso 1: Configurar el rol de usuario de SMART on FHIR

Siga los pasos que aparecen en la sección Administrar usuarios: Asignación de usuarios a roles. Todos los usuarios que se hayan agregado al rol "Usuario de FHIR SMART" podrán acceder al servicio de FHIR si sus solicitudes cumplen lo que se establece en guía de implementación de SMART en FHIR, como que la solicitud tenga un token de acceso, lo que incluye una notificación de fhirUser y una notificación de ámbitos clínicos. El acceso concedido a los usuarios de este rol estará limitado por los recursos asociados a su compartimiento fhirUser y las restricciones de los ámbitos clínicos.

Paso 2: Integrar el servidor FHIR con ejemplos

Siga los pasos descritos en el software de código de los ejemplos de Datos e IA de Azure Health. Esto permitirá que el servidor FHIR se integre con otros servicios de Azure (como APIM, Azure Functions, etc).

Nota:

Los ejemplos son código fuente abierto y debe revisar la información y los términos de licencia de GitHub antes de usarlos. No forman parte de Azure Health Data Services y no reciben soporte técnico de Microsoft. Estos ejemplos se pueden usar para mostrar cómo se pueden usar conjuntamente Azure Health Data Services y otras herramientas de código abierto para demostrar el cumplimiento de ONC (g)(10) y el uso de Microsoft Entra ID como flujo de trabajo del proveedor de identidades.

Proxy de SMART on FHIR

Hacer clic para expandir

Nota:

Esta es otra ruta de acceso a SMART on FHIR (mejorado) como se mencionó. La opción de proxy de SMART en FHIR solo habilita la secuencia de inicio de EHR.

Para usar SMART on FHIR, primero debe autenticar y autorizar la aplicación. La primera vez que use SMART on FHIR, también debe obtener el consentimiento administrativo para permitir que la aplicación acceda a los recursos de FHIR.

Si no tiene un rol de propiedad en la aplicación, póngase en contacto con el propietario de la aplicación y pídale que conceda el consentimiento de administrador en su nombre en la aplicación.

Si tiene privilegios administrativos, complete los pasos siguientes para conceder el consentimiento del administrador directamente. (También puede conceder el consentimiento del administrador a sí mismo más adelante cuando se le solicite en la aplicación) Puede completar los mismos pasos para agregar otros usuarios como propietarios, para que puedan ver y editar este registro de aplicación.

Para agregarse usted mismo u otro usuario como propietario de una aplicación:

  1. En el Azure Portal, vaya a Microsoft Entra ID.
  2. En el menú de la izquierda, seleccione Registro de la aplicación.
  3. Busque el registro de la aplicación que creó anteriormente y selecciónelo.
  4. En el menú de la izquierda, en Administrar, seleccione Propietarios.
  5. Seleccione Agregar propietarios y, a continuación, agréguese usted mismo o al usuario que desea que tenga consentimiento del administrador.
  6. Seleccione Guardar.

Paso 2: Habilitar el proxy de SMART on FHIR

SMART on FHIR requiere que Audience tenga un URI de identificador igual al URI del servicio FHIR. La configuración estándar de Azure API for FHIR usa un valor Audience de https://azurehealthcareapis.com. De todas formas, también puede establecer un valor que coincida con la dirección URL específica de su servicio de FHIR (por ejemplo https://MYFHIRAPI.azurehealthcareapis.com). Esto es necesario cuando se trabaja con el proxy de SMART on FHIR.

Para habilitar el proxy de SMART en FHIR en la configuración de Autenticación para la instancia de Azure API for FHIR; para ello, seleccione la casilla Proxy de SMART en FHIR.

Captura de pantalla que muestra cómo habilitar el proxy de SMART en FHIR.

El proxy de SMART on FHIR actúa como intermediario entre la aplicación SMART on FHIR y Microsoft Entra ID. La respuesta de autenticación (el código de autenticación) tiene que ir al proxy de SMART on FHIR en lugar de a la propia aplicación. Después, el proxy reenvía la respuesta a la aplicación.

Debido a esta retransmisión en dos pasos del código de autenticación, tiene que establecer la dirección URL de respuesta (devolución de llamada) de su aplicación cliente de Microsoft Entra en una dirección URL que es una combinación de la dirección URL de respuesta para el proxy de SMART on FHIR y la dirección URL de respuesta de la aplicación SMART on FHIR. La dirección URL de respuesta combinada tiene el siguiente formato.

https://MYFHIRAPI.azurehealthcareapis.com/AadSmartOnFhirProxy/callback/aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA

En la respuesta, aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA es una versión codificada en Base64 y segura para direcciones URL de la dirección URL de respuesta para la aplicación SMART on FHIR. En el iniciador de aplicaciones SMART on FHIR, cuando la aplicación se ejecuta localmente, la dirección URL de respuesta es https://localhost:5001/sampleapp/index.html.

Puede generar la dirección URL de respuesta combinada mediante un script como el siguiente.

$replyUrl = "https://localhost:5001/sampleapp/index.html"
$fhirServerUrl = "https://MYFHIRAPI.azurewebsites.net"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($ReplyUrl)
$encodedText = [Convert]::ToBase64String($bytes)
$encodedText = $encodedText.TrimEnd('=');
$encodedText = $encodedText.Replace('/','_');
$encodedText = $encodedText.Replace('+','-');

$newReplyUrl = $FhirServerUrl.TrimEnd('/') + "/AadSmartOnFhirProxy/callback/" + $encodedText

Agregue la dirección URL de respuesta a la aplicación cliente pública que creó anteriormente para Microsoft Entra ID.

Captura de pantalla que muestra cómo configurar la dirección URL de respuesta para el cliente público.

Paso 3: Obtener un paciente de prueba

Para probar Azure API for FHIR y el proxy de SMART on FHIR, tiene que tener al menos un paciente en la base de datos. Si aún no ha interactuado con la API y no tiene datos en la base de datos, consulte Acceso al servicio FHIR mediante Postman para cargar un paciente. Anote el identificador de un paciente específico.

Paso 4: Descargar el iniciador de aplicaciones SMART on FHIR

El repositorio de FHIR Server para Azure incluye un sencillo iniciador de aplicaciones SMART on FHIR y un ejemplo de aplicación SMART on FHIR. En este tutorial, use este iniciador de SMART on FHIR de forma local para probar la instalación.

Puede clonar el repositorio de GitHub e ir a la aplicación mediante los siguientes comandos.

git clone https://github.com/Microsoft/fhir-server
cd fhir-server/samples/apps/SmartLauncher

La aplicación necesita algunos valores de configuración, que se pueden establecer en appsettings.json:

{
    "FhirServerUrl": "https://MYFHIRAPI.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

Se recomienda utilizar la característica dotnet user-secrets.

dotnet user-secrets set FhirServerUrl https://MYFHIRAPI.azurehealthcareapis.com
dotnet user-secrets set ClientId <APP-ID>

Use este comando para ejecutar la aplicación.

dotnet run

Paso 5: Probar el proxy de SMART on FHIR

Después de iniciar el iniciador de aplicaciones de SMART on FHIR, puede dirigir el explorador a https://localhost:5001, donde debería ver la siguiente pantalla.

Captura de pantalla dl iniciador de aplicaciones SMART en FHIR.

Cuando escribe la información de los campos Patient (Paciente), Encounter (Encuentro) o Practitioner (Personal sanitario), puede ver que Launch context (Contexto de inicio) se actualiza. Cuando se usa Azure API for FHIR, el contexto de inicio es simplemente un documento JSON que contiene información sobre el paciente, el personal sanitario, etc. Este contexto de inicio está codificado en Base64 y se pasa a la aplicación SMART on FHIR como parámetro de consulta launch. Según la especificación de SMART on FHIR, esta variable es opaca para la aplicación SMART on FHIR, y se pasa al proveedor de identidades.

El proxy de SMART on FHIR usa esta información para rellenar los campos en la respuesta del token. La aplicación SMART on FHIR puede usar estos campos para controlar de qué paciente solicita los datos y cómo representa la aplicación en la pantalla. El proxy de SMART on FHIR admite los siguientes campos.

  • patient
  • encounter
  • practitioner
  • need_patient_banner
  • smart_style_url

Estos campos están diseñados para proporcionar orientación a la aplicación, pero no proporcionan ninguna información de seguridad. Una aplicación SMART on FHIR puede omitirlos.

Observe que el iniciador de aplicaciones de SMART on FHIR actualiza la información del campo Launch URL (Dirección URL de inicio) al final de la página.

Seleccione Iniciar para iniciar la aplicación de ejemplo.

Migración desde el proxy de SMART on FHIR a SMART on FHIR (mejorado)

Importante

El proxy de SMART on FHIR se retira en septiembre de 2026, pasando a SMART on FHIR (mejorado) a partir de esa fecha. A partir de septiembre de 2026, las aplicaciones que dependen del proxy de SMART on FHIR notificarán errores al acceder al servicio FHIR.

SMART on FHIR (mejorado) proporciona más funcionalidades en comparación con Smart on FHIR. SMART on FHIR (mejorado) puede ser la opción idónea para cumplir los requisitos de la Guía de implementación de SMART on FHIR (v 1.0.0) y del criterio §170.315(g)(10) Standardized API for patient and population services. En la tabla siguiente se muestra la diferencia entre el proxy de Smart on FHIR y SMART on FHIR (mejorado).

Funcionalidad SMART on FHIR (mejorado) Proxy de SMART on FHIR
Admite el inicio independiente Sí No
Admite el inicio de EHR Sí Sí
Admite restricciones de ámbito Sí No
Se basa en productos propios de Azure Sí, es necesario integrar productos de Azure como Azure API Management (APIM) No
Ayuda y soporte técnico de Microsoft Compatible con el servicio FHIR. La compatibilidad del ejemplo de código abierto debe notificarse y supervisarse a través de GitHub Compatible con el servicio FHIR

Pasos de migración

  • Paso 1: Configurar el rol de usuario de SMART on FHIR. Siga los pasos que aparecen en la sección Administrar usuarios: Asignación de usuarios a roles. Cualquier usuario agregado al rol de usuario de SMART podría acceder al servicio FHIR, siempre que sus solicitudes cumplan con la guía de implementación de SMART on FHIR.
  • Paso 2: Implementar un ejemplo de SMART on FHIR en ejemplos de software de código abierto de Datos e IA en Azure Health
  • Paso 3: Actualizar el punto de conexión de la dirección URL del servicio FHIR a "{{BASEURL_FROM_APIM}}/smart."
  • Paso 4: Desactivar la configuración del proxy de SMART on FHIR en la hoja Autenticación del servicio FHIR.

Si tiene alguna duda, consulte a los expertos de la comunidad en Microsoft Q&A. Para obtener soporte técnico, también puede crear una solicitud de soporte técnico.

Pasos siguientes

Ahora que ha aprendido los conceptos básicos para habilitar la funcionalidad de SMART on FHIR, consulte la página de ejemplos de búsqueda para obtener más información sobre cómo realizar búsquedas con diferentes parámetros de búsqueda, modificadores y otros métodos de búsqueda de FHIR.

Ejemplos de búsqueda de FHIR

Nota:

FHIR® es una marca registrada de HL7 y se usa con su permiso.