Compartir vía

SMART on FHIR

  • Artículo

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 al menos tres ventajas importantes:

  • 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 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 on FHIR con ejemplos de Azure Health Data Services [SMART on 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. Cualquier usuario agregado a este rol podrá acceder al servicio FHIR, siempre que sus solicitudes cumplan con la guía de implementación de SMART on FHIR. 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.

Nota:

La guía de implementación de Smart on FHIR define el acceso a los tipos de recursos de FHIR con ámbitos. Estos ámbitos afectan al acceso que una aplicación puede tener a los recursos de FHIR. Un usuario con el rol de usuario SMART tiene acceso para realizar interacciones de lectura con la API en el servicio FHIR. El rol de usuario SMART no concede acceso de escritura al servicio FHIR.

Paso 2: Integrar el servidor FHIR con ejemplos

Haga clic en este vínculo para ir a la solución de código abierto Azure Health Data and AI Samples. Estos pasos que aparecen en el documento permiten la integración del servidor FHIR 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 usan para mostrar cómo Azure Health Data Services (AHDS) y otras herramientas de código abierto se pueden usar conjuntamente para demostrar el cumplimiento del criterio §170.315(g)(10) Standardized API for patient and population services, mediante Microsoft Entra ID como flujo de trabajo del proveedor de identidades.

Proxy de SMART on FHIR

Hacer clic para expandir

Nota:

Esta es otra opción para SMART on FHIR (mejorado) mediante los ejemplos de AHDS mencionados anteriormente. Le sugerimos que adopte SMART on FHIR (mejorado). La opción de proxy de Smart on FHIR es una opción heredada. SMART on FHIR (mejorado) proporciona funcionalidades agregadas al proxy de Smart on FHIR. SMART on FHIR (mejorado) cumple 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.

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 usar estos mismos pasos para agregar otros usuarios como propietarios, para que puedan ver y editar el 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 del servicio FHIR usa un valor Audience de https://fhir.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.fhir.azurehealthcareapis.com). Esto es necesario cuando se trabaja con el proxy de SMART on FHIR.

Para habilitar el proxy de SMART on FHIR en la configuración de Autenticación de la instancia de FHIR, seleccione la casilla Proxy de SMART on 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.fhir.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.

Paso 3: Obtener un paciente de prueba

Para probar el servicio FHIR y el proxy de SMART on FHIR, debe tener al menos un paciente en la base de datos. Si aún no ha usado 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 aplicaciones 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.fhir.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.fhir.azurehealthcareapis.com
dotnet user-secrets set ClientId <APP-ID>

Use el siguiente 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 lo siguiente:

Recorte de pantalla que muestra el iniciador de aplicaciones SMART on 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 el servicio 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 Launch (Lanzamiento) para iniciar la aplicación de ejemplo. Acto seguido debería ver algo similar a lo siguiente.

Recorte de pantalla que muestra la aplicación SMART on FHIR.

Inspeccione la respuesta del token para ver cómo se pasan los campos de contexto de inicio a la aplicación.

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.