Package Structure

com.ajfhir.auth/
├── SmartFhirServerApplication    Entry point + @EnableScheduling
├── SmartServerProperties         @ConfigurationProperties(prefix="smart.server")
│
├── auth/                         Spring Security + registered apps + user store
├── discovery/                    SMART discovery document + proxy filter
├── launch/                       EHR launch tokens
├── oidc/                         RSA keys + JWKS + id_token claims
├── token/                        SMART token customization
└── (test)                       Unit + component tests

---

auth/ — Authorization server and user store

The largest package. Contains Spring Security configuration, clinician credentials, and registered app management.

Class	Responsibility
AuthorizationServerConfig	Defines two SecurityFilterChain beans (auth server + default), registers SmartTokenResponseConverter as token endpoint handler, provides OAuth2AuthorizationService, OAuth2AuthorizationConsentService, JwtDecoder, PasswordEncoder
Clinician	JPA entity — login username, BCrypt password hash, display name, FHIR Practitioner ID
ClinicianRepository	Spring Data JPA — findByUsername()
ClinicianUserDetails	Spring Security UserDetails wrapping Clinician. Exposes displayName and fhirUserId for IdTokenBuilder
CliniciansUserDetailsService	UserDetailsService — loads Clinician from DB, wraps in ClinicianUserDetails. Called by Spring Auth Server login flow
JpaRegisteredClientRepository	RegisteredClientRepository implementation backed by PostgreSQL. Converts RegisteredApp → RegisteredClient with PKCE enforced
RegisteredApp	JPA entity — clientId, appName, redirectUri, allowedScopes (comma-separated), accessTokenTtlSeconds override
SmartScopeAuthorizationInterceptor	HAPI @Interceptor — validates bearer token scopes on every FHIR request. Register this on the HAPI server, not this auth server
DataInitializer	CommandLineRunner — seeds dr.smith, dr.jones, and ajfhir-smart-clientjfhir-smart-client` on first startup if DB is empty

Dependency direction: auth/ depends on token/ (for SmartTokenResponseConverter) and oidc/ (for RSAKey).

---

discovery/ — SMART discovery and proxy

Class	Responsibility
SmartDiscoveryController	GET /.well-known/smart-configuration — returns the exact fields our SMART client expects: authorization_endpoint, token_endpoint, capabilities (including launch-ehr), code_challenge_methods_supported: [S256], jwks_uri
SmartDiscoveryProxyFilter	OncePerRequestFilter — proxies /.well-known/smart-configuration requests to this auth server. Register this on the HAPI FHIR JPA server so clients reaching port 8080 get the discovery document

---

launch/ — EHR launch context tokens

Class	Responsibility
LaunchContext	JPA entity — token (32-byte random), patientFhirId, encounterFhirId, needPatientBanner, clientId, launchedBy, expiresAt (+5 min), used flag
LaunchContextRepository	findByTokenAndUsedFalse() — returns empty when already used or expired
LaunchContextService	createLaunchToken() — generates token, persists. resolveLaunchToken() — validates, marks used (single-use). @Scheduled purge every 10 minutes
LaunchPortalController	GET /portal — shows patient list from HAPI. POST /portal/launch — creates launch token, redirects to SMART client
LaunchTokenException	Thrown for invalid, expired, or already-used tokens

---

oidc/ — RSA keys, JWKS, and id_token claims

Class	Responsibility
RsaKeyConfig	Generates RSA-2048 key pair at startup. Exposes @Bean RSAKey and @Bean JWKSource<SecurityContext>. Used by Spring Auth Server for JWT signing
JwksController	GET /oauth2/jwks — returns the public key only via rsaKey.toPublicJWK(). Clients use this to verify JWT signatures
IdTokenBuilder	Builds OIDC claims map for id_token — loads ClinicianUserDetails for the authenticated username, extracts displayName (→ name claim) and fhirUserId (→ fhirUser claim)

Key persistence

The RSA key pair is regenerated on every server restart. Tokens issued before a restart cannot be verified after it. For production, load the key from a keystore or secrets manager. See Deployment.

---

token/ — SMART token customization

Class	Responsibility
SmartTokenCustomizer	OAuth2TokenCustomizer<JwtEncodingContext> — for access_token: reads launch param from stored OAuth2AuthorizationRequest, resolves launch token, adds patient/encounter/need_patient_banner JWT claims. For id_token: calls IdTokenBuilder
SmartTokenResponseConverter	AuthenticationSuccessHandler on token endpoint — decodes the issued JWT, extracts SMART extras, writes them as top-level fields in the JSON response body alongside access_token