AJ FHIR Smart Auth Server

v1.0.0 · Spring Authorization Server 1.3 · Spring Boot 3.3 · Java 21 · Apache 2.0

The AJ FHIR Auth Server is the authorization layer that sits between SMART client apps and a HAPI FHIR JPA server. It implements the complete SMART App Launch v2.2 protocol — PKCE S256, dynamic SMART discovery, EHR launch tokens, SMART token extras (patient, encounter, need_patient_banner), OIDC id_token, and scope enforcement — without requiring Epic.

It runs on port 9000.

What it does

SMART Client :8081              Auth Server :9000              HAPI FHIR :8080
      │                               │                              │
      │── GET /.well-known/ ─────────►│                              │
      │     smart-configuration       │                              │
      │◄─ authorization_endpoint ─────│                              │
      │   token_endpoint, jwks_uri    │                              │
      │                               │                              │
      │── GET /oauth2/authorize ──────►│                              │
      │   ?launch=TOKEN&code_challenge│                              │
      │   &scope=launch+openid+...    │                              │
      │                               │ SmartTokenCustomizer:        │
      │── POST /oauth2/token ─────────►│ resolves launch token        │
      │◄─ {                           │ → patient, encounter         │
      │     access_token,             │                              │
      │     patient,       ◄──────────┤ SmartTokenResponseConverter: │
      │     encounter,                │ promotes to top-level JSON   │
      │     need_patient_banner,      │                              │
      │     id_token                  │                              │
      │   }                           │                              │
      │                               │                              │
      │── GET /fhir/Observation ──────────────────────────────────►  │
      │   Authorization: Bearer ...   │   SmartScopeAuthInterceptor  │
      │◄─ 200 OK (or 403 if no scope)─────────────────────────────── │

Key components

Class	Package	Role
AuthorizationServerConfig	auth	Two SecurityFilterChain beans — OAuth2 protocol endpoints + portal/login
SmartTokenCustomizer	token	Adds patient, encounter, need_patient_banner to access token JWT
SmartTokenResponseConverter	token	Writes SMART extras as top-level fields in the token response body
SmartDiscoveryController	discovery	Serves GET /.well-known/smart-configuration
LaunchContextService	launch	Creates and resolves single-use, 5-minute EHR launch tokens
LaunchPortalController	launch	Patient picker portal — clinician login + patient select + launch redirect
JpaRegisteredClientRepository	auth	PostgreSQL-backed SMART app registry
RsaKeyConfig	oidc	Generates RSA-2048 signing key pair on startup
SmartScopeAuthorizationInterceptor	auth	HAPI FHIR interceptor — enforces patient/Patient.rs scopes

Port layout

Port	Service
9000	This auth server — OAuth2 endpoints, discovery, portal
8080	HAPI FHIR JPA server
8081	SMART Client app
8082	Consent Manager
8083	Referral Module

What it is not

This server handles authentication (who you are) and authorization (what you can access). It does not store FHIR clinical data — that is HAPI FHIR's job. It does not enforce consent beyond SMART scopes — that is the Consent Manager's job.

---

Next: Quick Start →