Tutorial: Proxy de Azure Active Directory SMART on FHIR

SMART on FHIR es un conjunto de especificaciones abiertas para integrar aplicaciones de socio con servidores FHIR y sistemas de historiales médicos electrónicos que tienen interfaces FHIR. Uno de los objetivos principales de las especificaciones es describir cómo una aplicación debe detectar los puntos de conexión de autenticación para un servidor FHIR e iniciar una secuencia de autenticación.

La autenticación se basa en OAuth2. No obstante, dado que SMART on FHIR usa convenciones de nomenclatura de parámetros que no son compatibles de forma inmediata con Azure Active Directory (Azure AD), Azure API for FHIR tiene un proxy integrado de Azure AD SMART on FHIR que habilita un subconjunto de las secuencias de inicio de SMART on FHIR. En concreto, el proxy habilita la secuencia de inicio de EHR.

En este tutorial se describe cómo usar el proxy para habilitar las aplicaciones SMART on FHIR con Azure API for FHIR.

Requisitos previos

• Una instancia de Azure API for FHIR
• .NET Core 2.2

Configuración de registros de Azure AD

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.

También necesitará un registro de una aplicación cliente. La mayoría de las aplicaciones SMART on FHIR son aplicaciones JavaScript de una sola página. Por lo tanto, debe seguir las instrucciones para configurar una aplicación cliente pública en Azure AD.

Una vez completados estos pasos, debe tener:

• Un servidor de FHIR con la audiencia establecida en https://MYFHIRAPI.azurehealthcareapis.com , donde es el nombre de la Azure API for FHIR MYFHIRAPI instancia.
• Un registro de una aplicación cliente público. Anote el identificador de esta aplicación cliente.

Establecer el consentimiento del administrador para la aplicación

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 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 le conceda el consentimiento del administrador 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 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 a usted mismo o a otro usuario como propietario de una aplicación:

1. En Azure Portal, vaya a Azure Active Directory.
2. En el menú de la izquierda, seleccione Registro de aplicaciones.
3. Busque el registro de la aplicación que creó y selecciónelo.
4. En el menú de la izquierda, en Administrar, seleccione Propietarios.
5. Seleccione Agregar propietarios y, a continuación, agregue usted mismo o el usuario al que desea tener el consentimiento del administrador.
6. Seleccione Guardar.

Habilitación del proxy de SMART on FHIR

Habilite el proxy de SMART on FHIR proxy en la configuración de Autenticación para la instancia de Azure API for FHIR; para ello, seleccione la casilla SMART on FHIR proxy (Proxy de SMART on FHIR):

Habilitación de CORS

Dado que la mayoría de las aplicaciones SMART on FHIR son aplicaciones de JavaScript de una sola página, tiene que habilitar el uso compartido de recursos entre orígenes (CORS) para Azure API for FHIR:

Configuración de la dirección URL de respuesta

El proxy de SMART on FHIR actúa como intermediario entre la aplicación SMART on FHIR y Azure AD. 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) para su aplicación cliente de Azure AD 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 este formato:

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

En esa 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 este:

$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 Azure AD:

Obtención de 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.

Descarga del 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 estos 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

Prueba del 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:

Cuando escribe la información de los campos Patient (Paciente), Encounter (Encuentro) o Practitioner (Personal sanitario), notará 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 Launch (Lanzamiento) para iniciar la aplicación de ejemplo. Acto seguido debería ver algo similar a este ejemplo:

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

Pasos siguientes

En este tutorial, ha configurado el proxy de Azure Active Directory SMART on FHIR. Para explorar el uso de SMART on FHIR con Azure API for FHIR y FHIR Server para Azure de código abierto, vaya al repositorio de ejemplos de servidor de FHIR en GitHub: