Desarrollando aplicaciones SMART On FHIR con Auth0 e InterSystems IRIS FHIR Server - Configuración

En el pasado artículo presentamos la arquitectura de nuestro proyecto de SMART On FHIR, así que es hora de meternos en harina y empezar a configurar todos los elementos que vamos a necesitar.

Primeramente comenzaremos con Auth0.

Configuración de AUTH0

Comenzaremos creando una cuenta de Auth0 con un correo válido, una vez dados de alta deberemos crear nuestra primera aplicación, y lo haremos desde el menú de la izquieda:

En nuestro ejemplo la aplicación será del tipo Single Page Web Application al tratarse una aplicación desarrollada en Angular 16. Seleccionamos dicha opción y pulsamos "Create".

En la siguiente pantalla deberemos definir los siguientes campos:

• Allowed Callback URLs: https://localhost
• Allowed Logout URLs: https://localhost
• Allowed Web Origins: https://localhost
• Allow Cross-Origin Authentication: Checked
• Allowed Origins (CORS): https://localhost

¡ATENCIÓN! Las URLs deben ser todas HTTPS, es uno de los requisitos para las conexiones de OAuth2.

Con ello hemos configurado las URL que Auth0 requiere para redireccionar al usuario tras el proceso de autenticación y autorización. Si véis las URL no tienen definido ningún puerto, esto es debido a que con el despliegue del proyecto de Angular en Docker mediante NGINX hemos indicado que este será accesible por el puerto HTTPS por defecto, el 443. Podéis poner el nombre que más rabia os dé.

De cara a la posterior configuración de nuestro proyecto de Angular anotad los valores que encontramos tanto en Domain como en Client ID.

Con nuestra aplicación configurada es el momento de definir la API que recibirá las peticiones de nuestra aplicación Angular y nuevamente lo haremos desde el menú izquierdo:

Esta opción os mostrará una nueva pantalla para introducir todos los datos necesarios:

Deberéis definir un identificador para la API que posteriormente será utilizado desde la aplicación de Angular como "environment" para conectarse apropiadamente. Como véis recomiendan que se introduzca una URL, pero no es necesario que esta URL sea funcional, ya que sólo se usará como identificador, en nuestro caso podemos definir:

https://localhost/smart/fhir/r5

 Finalmente configuramos el algorirmo de firma a RS256 y pasamos a la pestaña de Permissions, donde definiremos el contexto o "scope" de FHIR para los usuarios conectados:

Si queréis profundizar en el tema de los contextos de FHIR podéis consultar la URL de la página oficial pulsando aquí. Para nuestro ejemplo hemos definido el contexto user/*.* que permite al usuario validado las operaciones CRUD sobre todos los recursos del servidor FHIR.

¡Perfecto! Ya hemos configurado nuestra cuenta de Auth0 para funcionar como servidor de OAuth2.

Configuración de la aplicación de Angular

Me habría gustado desarrollar la aplicación en Angular 17 que introduce bastantes cambios, pero desafortunadamente la documentación asociada de Auth0 y sus librerías están únicamente para Angular 16, por lo que para no complicarme la vida lo he hecho en la versión 16.

Para configurar nuestro proyecto de Angular únicamente tendremos que abrir la página app.module.ts y buscar el siguiente fragmento de código:

Veamos que significa cada parámetro a configurar:

• domain: correspondiente al valor Domain que se generó cuando creamos nuestra aplicación en Auth0.
• clientId: igual que el anterior, pero con el valor Client ID generado.
• audience: correspondiente a la URL que hemos configurado como identificador de nuestra API.
• uri: con este valor indicamos a la librería de TypeScript de Auth0 que intercepte todas las llamadas que hagamos a URLs que contengan esa URI y les incluya el Access_token que nos devolverá Auth0 cuando nos validemos (añadiendo en la cabecera de la llamada el parámetro Authorization: Bearer....).

Una vez modificados dichos valores ya tendríamos configurada nuestra aplicación Angular para trabajar con Auth0. En el próximo artículo veremos con más detalle cómo invocaremos a Auth0 desde nuestra interfaz de usuario.

Configuración de InterSystems IRIS for Health

Este proyecto está configurado para que instale automáticamente el servidor FHIR durante el proceso de despliegue, esto nos ahorrará un paso. En nuestro caso hemos definido como endpoint de nuestro servidor FHIR la URI /smart/fhir/r5, para los que no estéis familiarizados con la terminología de FHIR ese r5 hace referencia a la última versión de FHIR, disponible desde hace meses en IRIS.

Para configurar nuestra instancia de IRIS deberemos arrancar primeramente nuestro Docker y desplegar los 3 contenedores disponibles en el proyecto. Sólo necesitaremos ejecutar en el terminal desde la raíz del proyecto el siguiente comando:

docker-compose up -d --build

Esto nos va a construir y levantar los contenedores presentes en el proyecto. Para los usuarios de Windows si usáis Docker Desktop deberéis ver una pantalla tal que así:

Aquí tenemos nuestros 3 contenedores:

• iris: con la instancia de IRIS en la que se encuentra nuestro servidor FHIR.
• smart-ui: con el código de nuestra aplicación web desplegado desde NGINX configurado a su vez para que todas las conexiones sean vía SSL con sus certificados asociados.
• webgateway: con su servidor Apache asociado (recordad que desde la versión oficial 2023.1 se ha eliminado el Private Web Server, aunque siga disponible en las versiones Community).

Web Gateway

Como vengo repitiendo, para hacer uso de OAuth2 con nuestro servidor FHIR es obligatorio que todas las conexiones se realicen mediante HTTPS, por lo que el servidor de Apache deberá estar configurado para únicamente aceptar llamadas de ese tipo, si echáis un ojo al fichero /webgateway/shared/CSP.conf podréis ver la siguiente sección encargada de configurar el servidor Apache:

# SSL SECTION #
# Enable SSL/TLS (https://) on the Apache web server.
# The user is responsible for providing valid SSL certificates.
LoadModule ssl_module /usr/lib/apache2/modules/mod_ssl.so
LoadModule headers_module /usr/lib/apache2/modules/mod_headers.so
<VirtualHost *:443>
SSLEngine on
SSLCertificateFile "/webgateway-shared/apache_webgateway.cer"
SSLCertificateKeyFile "/webgateway-shared/apache_webgateway.key"
Header add ACCESS-CONTROL-ALLOW-ORIGIN "*"
</VirtualHost>

Podéis observar como está configurado para que las llamadas vengan por el puerto 443, es decir, la URL de nuestro webgateway será https://webgateway y todas las llamadas que lancemos desde nuestra aplicación web a nuestro servidor FHIR se deberán redirigir a esa URL (webgateway es la máscara dada al contenedor de Docker la red creada por este).

Todas las llamadas al servidor desde Angular vendrán con la URL https://localhost/smart/fhir/r5 y será NGINX el encargado de redirigir ese localhost a webgateway. Si abrís el fichero /smart-ui/nginx.conf podréis ver la siguiente configuración:

 

En esta configuración vemos que nuestra aplicación web va a escuchar en el puerto 443 y que todas las llamadas que lleven en la URL el valor / serán gestionadas por la aplicación de Angular, mientras las que incluyan /smart/ se van a redirigir a https://webgateway.

Atención con proxy_set_header que va a ser el valor que nos evite dolores de cabeza con el CORS. Para evitar que nuestro Web Gateway rechace las llamadas de otros servidores debemos modificar el valor de la cabecera Host para configurarlo con la dirección del Web Gateway.

InterSystems IRIS

Ahora deberemos configurar nuestra instancia de IRIS para que pueda trabajar con Auth0, para ello deberemos configurarlo como un cliente de OAuth2. Para ello sólo tendremos que acceder al Portal de Gestión con las credenciales superuser/SYS y acceder a la opción System Administration > Security > OAuth 2.0 > Client, a continuación pulsar sobre Create Server Description y rellenar el Issuer endpoint con el valor del Domain que obtuvimos en el momento de crear la aplicación a Auth0 (https://[MY_DOMAIN]/) ¡ojo! la URL debe terminar con la "/".  Finalmente seleccionamos la configuración SSL/TLS y pulsamos en Discover and Save: 

Automáticamente nuestra instancia de IRIS recuperará la información que necesita de Auth0.

Únicamente nos queda añadir un cliente al servidor que acabamos de configurar, pulsando el Client Configuration accederemos a una nueva pantalla donde definiremos el nombre de la aplicación y del cliente. Este nombre del cliente será el que posteriormente usemos para configurar nuestro servidor FHIR.

Servidor FHIR

El último paso que nos queda para terminar de configurar nuestro proyecto es indicarle a nuestro servidor de FHIR cual va a ser el cliente de OAuth2 que se utilizará para la conexión. Para acceder a la configuración abriremos el Portal de Gestión y seleccionaremos Health > FHIR > FHIR Configuration > Server Configuration y abriremos el endpoint que se nos muestra en pantalla, iremos al final de la misma y pulsaremos en Edit. Finalmente añadimos en el campo OAuth Client Name el nombre con el que hemos creado la configuración del cliente.

Conclusión

Pues ya tenemos configurado nuestro proyecto, en el próximo artículo veremos como interopera nuestra aplicación de Angular con cada uno de los actores.

¡Gracias por vuestra atención!