Introduction

What is SMART on FHIR?

SMART on FHIR (Substitutable Medical Applications, Reusable Technologies) is an open standard that defines how healthcare apps connect to Electronic Health Record systems. It layers OAuth 2.0 and OpenID Connect on top of HL7 FHIR R4 to answer three questions:

Which EHR is the app talking to? — resolved via the iss parameter and dynamic discovery of /.well-known/smart-configuration
Who is the patient and clinician in context? — carried in the launch token and returned as extras in the OAuth2 token response
What data can the app access? — governed by SMART scopes (patient/Patient.rs, patient/Condition.rs, etc.) granted during the OAuth2 flow

The result is a single app that can launch inside any SMART-compliant EHR — Epic, Cerner, and others — without being hard-coded to any one vendor's proprietary API.

What this client provides

This project is a production-ready SMART on FHIR EHR launch client targeting Epic, built on Spring Boot 3 and Java 21. It implements the complete launch handshake and exposes the retrieved FHIR data through a Thymeleaf UI and a REST API.

Epic EHR  ──launch──▶  Your App  ──FHIR API──▶  Epic FHIR R4
              SMART           HAPI client
           handshake        + bearer token

What is handled automatically

Once the SMART handshake completes, the app gives you:

SmartLaunchContext — a typed session object holding the access token, patient ID, encounter ID, needPatientBanner flag, granted scopes, token expiry, and OIDC user profile
FhirClientFactory — a HAPI R4 IGenericClient pre-configured with a bearer token interceptor, pointed at the correct FHIR server for this hospital
TokenRefreshFilter — transparent token refresh 120 seconds before expiry on every /api/** request — clinicians never see an unexpected 401
SecurityConfig — Spring Security 6 filter chain with session fixation protection, CSRF (Double-Submit Cookie), and denyAll() fallback for unknown routes
A working UI — patient banner, dashboard, conditions table, medications table, clinician profile from OIDC

What you build on top

The app is a functional starting point. You extend it by:

Adding new FHIR resource endpoints in PatientDataController
Adding new UI pages in UiController and templates/
Requesting additional scopes in application.yml
Connecting to your own backend services or databases

SMART App Launch v2.2

This client implements SMART App Launch 2.2, the current specification. Key differences from v1 (which most older libraries including HealthLX implement):

Capability	SMART v1	SMART v2 (this client)
Server discovery	Static YAML config	Dynamic `/.well-known/smart-configuration`
PKCE	Optional	Required (S256 enforced)
Scope syntax	`patient/*.read`	`patient/Patient.rs`
`aud` parameter	Not required	Required by Epic
Standalone launch	Partial	Full `launch/patient` support

EHR launch vs standalone launch

The app supports both SMART launch modes:

EHR launch

A clinician clicks your app's button inside Epic Hyperspace. Epic sends:

GET /launch?iss=https://hospital.epic.com/.../FHIR/R4&launch=abc123opaque

The launch token pre-selects the patient and encounter. After the OAuth2 handshake, SmartLaunchContext.patientId() is always populated.

Standalone launch

A user navigates directly to your app's URL (bookmarked, from a patient portal, etc.). Only iss is provided — no launch token. The OAuth2 flow uses launch/patient scope, which may trigger a patient picker in the auth server.

SmartLaunchController detects the mode automatically by checking whether the launch query parameter is present.

Technology stack

Layer	Technology	Version
Runtime	Java	21
Framework	Spring Boot	3.3.5
Security	Spring Security	6.x
FHIR client	HAPI FHIR	7.4.5
FHIR version	HL7 FHIR	R4
Templating	Thymeleaf	3.x
Build	Maven	3.9+
Testing	JUnit 5 + WireMock	5.x / 3.6.0

Project structure

smart-fhir-client/
├── src/main/java/com/smartfhir/client/
│   ├── auth/          PKCE generation + authorize URL builder
│   ├── context/       SmartLaunchContext + extraction from token response
│   ├── discovery/     /.well-known/smart-configuration fetching + caching
│   ├── fhir/          HAPI FHIR client factory + data controller
│   ├── launch/        /launch endpoint — EHR and standalone modes
│   ├── oidc/          id_token validation + UserProfile extraction
│   ├── refresh/       Proactive token refresh filter + service
│   ├── security/      Spring Security 6 filter chain + SMART session bridge
│   ├── token/         /callback endpoint + token exchange service
│   └── ui/            Thymeleaf page controller
├── src/main/resources/
│   ├── templates/     Thymeleaf HTML pages
│   ├── static/        CSS + JS
│   ├── application.yml
│   ├── application-epic.yml
│   └── application-smart.yml
└── src/test/java/
    └── com/smartfhir/client/
        └── it/        Epic + SMART Health IT integration tests

Next steps

Check prerequisites

Ensure Java 21, Maven 3.9+, and a compatible IDE are installed.

Run the quick start

Get the app running against the free SMART Health IT sandbox — no Epic account needed.

Register with Epic

Create a free developer account and get a non-production client ID for Epic sandbox testing.

Read the architecture docs

Understand the launch flow and package structure before extending the app.

Prerequisites → Quick Start →

Introduction

What is SMART on FHIR?​

What this client provides​

What is handled automatically​

What you build on top​

SMART App Launch v2.2​

EHR launch vs standalone launch​

EHR launch​

Standalone launch​

Technology stack​

Project structure​

Next steps​