Building a Secure SMART on FHIR Foundation Tutorial

Tutorial Topic

End-to-End Setup of InterSystems IRIS as a SMART on FHIR Repository with OAuth2 and HTTPS

Learning Objectives

By the end of this tutorial, the learner will be able to:

• Orchestrate a Secure Docker Environment: Configure a docker-compose.yml that includes a Web Gateway (Apache/Nginx) with automated SSL certificate generation using OpenSSL.

• Bridge the Web Gateway: Correctly map the Web Gateway configuration files to enable HTTPS traffic to reach the IRIS instance.

• Configure IRIS as an Identity Provider: Set up the IRIS OAuth2 Authorization Server, including scopes, signing algorithms, and SSL/TLS configurations within the Management Portal.

• Deploy a FHIR R4 Server: Enable the FHIR Interoperability adapter with Mandatory OAuth2 authentication.

• Validate via Postman: Execute the OAuth2 "Authorization Code" flow to retrieve an Access Token and perform CRUD operations on FHIR resources.

• Launch a SMART App: Successfully connect an external "Patient Summary Viewer" app to the IRIS FHIR endpoint using the SMART launch sequence.

Target Audience

• HealthTech Developers: Those familiar with FHIR but new to InterSystems infrastructure.

• System Integrators: Who need to move beyond "unauthenticated" lab environments into production-ready secure setups.

• Intermediate IRIS Users: Who understand FHIR basics but struggle with the complexity of OAuth2 and Web Gateway networking in Docker.

Value of this Tutorial

Currently, most IRIS Docker samples use plain HTTP for simplicity. However, SMART on FHIR strictly requires HTTPS and modern browsers block OAuth2 flows over insecure connections. This tutorial fills a critical "knowledge gap" by:

1. Providing a repeatable template for a secure Web Gateway setup—the most common stumbling block.

2. Eliminating the "it works on my machine" problem by using a scripted bash approach for certificate generation.

3. Providing a "Single Source of Truth" for the IRIS Management Portal settings, which are often scattered across multiple documentation pages.

Related Materials or References

• InterSystems Documentation: FHIR Server OAuth2 Authentication

• Community Reference: SMART on FHIR EHR Launch on IRIS

• Technical Foundation: InterSystems Web Gateway Container Volume Mapping