Developing SMART On FHIR Applications with Auth0 and InterSystems IRIS FHIR Server - Configuration

In the last article we presented the architecture of our SMART On FHIR project, so it's time to get down to business and start configuring all the elements that we are going to need.

We will first start with Auth0.

AUTH0 configuration

We will start by creating an Auth0 account with a valid email, once registered we will have to create our first application, and we will do it from the menu on the left:

In our example, the application will be of the Single Page Web Application type as it is an application developed in Angular 16. We select this option and click Create.

On the next screen we must define the following fields:

• 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

ATTENTION! URLs must all be HTTPS, it is one of the requirements for OAuth2 connections.

With this we have configured the URLs that Auth0 requires to redirect the user after the authentication and authorization process. If you see the URLs, they do not have any port defined, this is because with the deployment of the Angular project in Docker through NGINX we have indicated that it will be accessible through the default HTTPS port, 443. You can put the name that you like best.

For the subsequent configuration of our Angular project, write down the values that we find in both Domain and Client ID.

With our application configured, it is time to define the API that will receive the requests from our Angular application and again we will do it from the left menu:

This option will show us a new screen to enter all the necessary data:

You will need to define an identifier for the API that will later be used by the Angular application as "environment" to connect properly. As you can see, they recommend that you enter a URL, but it is not necessary for this URL to be functional, since it will only be used as an identifier. In our case we can define:

https://localhost/smart/fhir/r5

Finally we configure the signature algorithm to RS256 and go to the Permissions tab, where we will define the scope of FHIR for connected users:

If you want to go deeper into the topic of FHIR contexts, you can consult the URL of the official page by clicking here. For our example we have defined the user/*.* scope that allows the validated user to perform CRUD operations on all FHIR server resources.

Perfect! We have already configured our Auth0 account to function as an OAuth2 server.

Angular app configuration

I would have liked to develop the application in Angular 17, which introduces quite a few changes, but unfortunately the associated documentation for Auth0 and its libraries are only for Angular 16, so I decided to follow the easy path and I have developed it in version 16.

To configure our Angular project we will only have to open the app.module.ts page and look for the following code fragment:

Let's see what each parameter to configure means:

• domain: corresponding to the Domain value that was generated when we created our application in Auth0.
• clientId: same as above, but with the Client ID value generated.
• audience: corresponding to the URL that we have configured as the identifier of our API.
• uri: with this value we tell the Auth0 TypeScript library to intercept all the calls we make to URLs that contain that URI and include the Access_token that Auth0 will return when we validate (adding the Authorization parameter to the header of the call: Bearer....).

Once these values have been modified, we would have our Angular application configured to work with Auth0. In the next article we will see in more detail how we will invoke Auth0 from our user interface.

InterSystems IRIS for Health configuration

This project is configured to automatically install the FHIR server during the deployment process, this will save us a step. In our case we have defined the URI /smart/fhir/r5 as the endpoint of our FHIR server. For those of you who are not familiar with FHIR terminology, r5 refers to the latest version of FHIR, available for months on IRIS.

To configure our IRIS instance we must first start our Docker and deploy the 3 containers available in the project. We will only need to execute the following command in the terminal from the root of the project:

docker-compose up -d --build

This will allow us to build and run the containers present in the project. For Windows users, if you use Docker Desktop you should see a screen like this:

Here we have our 3 containers:

• iris: with the IRIS instance where our FHIR server is located.
• smart-ui: with the code of our web application deployed from NGINX configured in turn so that all connections are via SSL with their associated certificates.
• webgateway: with its associated Apache server (remember that since the official version 2023.1, the Private Web Server has been eliminated, although it is still available in the Community versions).

Web Gateway

As I have been repeating, to use OAuth2 with our FHIR server it is mandatory that all connections be made through HTTPS, so the Apache server must be configured to only accept calls of that type, if you take a look at the /webgateway/shared/CSP.conf file you can see the following section responsible for configuring the Apache server:

# 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>

You can see how it is configured so that the calls come through port 443, that is, the URL of our webgateway will be https://webgateway and all the calls that we launch from our web application to our FHIR server must be redirected to that URL (webgateway is the mask given to the Docker container's network created by it).

All calls to the server from Angular will come with the URL https://localhost/smart/fhir/r5 and NGINX will be in charge of redirecting that localhost to the webgateway. If you open the file /smart-ui/nginx.conf you will be able to see the following configuration:

In this configuration we see that our web application will listen on port 443 and that all calls that have the value / in the URL will be managed by the Angular application, while those that include /smart/ will be redirected to https://webgateway.

Be careful with proxy_set_header, which will be the value that avoids headaches with CORS. To prevent our Web Gateway from rejecting calls from other servers, we must modify the value of the Host header to configure it with the address of the Web Gateway.

InterSystems IRIS

Now we will have to configure our IRIS to work with Auth0, to do this we will have to configure it as an OAuth2 client. To do this we will only have to access the Management Portal with the superuser/SYS credentials and access the option System Administration > Security > OAuth 2.0 > Client, then click on Create Server Description and fill in the Issuer endpoint with the Domain value that we obtained at the time of creating the application to Auth0 (https://[MY_DOMAIN]/). Be careful! The URL must end with "/". Finally we select the SSL/TLS configuration and click on Discover and Save:

Automatically our IRIS instance will retrieve the information it needs from Auth0.

We only have to add a client to the server that we have just configured. By pressing Client Configuration we will access a new screen where we will define the name of the application and the client. This client name will be the one we later use to configure our FHIR server.

FHIR Server

The last step to finish the configuration of our project is to tell our FHIR server which OAuth2 client will be used for the connection. To access the configuration we will open the Management Portal and select Health > FHIR > FHIR Configuration > Server Configuration and we will open the endpoint that is shown on the screen, we will go to the end of it and click on Edit. Finally we add in the OAuth Client Name field the name with which we have created the client configuration.

Conclusion

Well, we already have our project configured, in the next article we will see how our Angular application interoperates with each of the actors.

Thank you for your attention!