SMART on FHIR Authorization Framework

SMART on FHIR (Substitutable Medical Applications, Reusable Technologies) is a specification maintained by HL7 that defines an authorization and app launch framework layered on top of OAuth 2.0 and OpenID Connect, adapted for the specific trust and consent requirements of healthcare data access. Originally developed at Boston Children's Hospital and standardized through HL7, SMART on FHIR has become a regulatory requirement: the ONC's 21st Century Cures Act Final Rule mandates SMART on FHIR app launch as a criterion for ONC Health IT Certification (2015 Edition), and CMS requires SMART on FHIR for the Patient Access API under the Interoperability Rule. SMART v2.0 (the current version) adds PKCE (Proof Key for Code Exchange) as mandatory for all public clients, introduces granular scopes using the v2 resource-level scope syntax, and defines the Backend Services profile for system-to-system access without user interaction.

The SMART App Launch flow involves several distinct technical steps that differ from vanilla OAuth 2.0. A SMART-aware FHIR server publishes a `.well-known/smart-configuration` discovery document advertising supported capabilities including launch modes, scope types, and authorization endpoints. EHR Launch flow embeds a launch token in the initial authorization request, allowing an EHR to pass patient and encounter context to the launching app — the app exchanges the launch token alongside the authorization code to receive both an access token and context parameters (patient, encounter, user) in the token response. Standalone Launch bypasses EHR context injection, requiring the app to collect patient context independently. The scope language — `patient/Observation.read`, `user/Patient.read`, `system/Encounter.read` — maps directly to FHIR resource types and REST operations, and SMART v2 introduces fine-grained filtering extensions for specific FHIR search parameters within a scope.

Implementing SMART on FHIR in regulated environments introduces nuances beyond the core OAuth flow. Token lifetimes must balance security with clinical usability — short-lived access tokens (15 minutes is common) combined with refresh token rotation are standard, but clinical workflows that span hours require careful session management to avoid mid-workflow access failures. Token introspection endpoints allow resource servers to validate tokens issued by the authorization server without sharing signing keys, which is essential for multi-component FHIR architectures where separate microservices serve different resource types. PKCE implementation must use S256 (SHA-256 code challenge method) — plain method must not be accepted. Consent management integration is required for regulatory compliance: authorization grants for patient data access must be linked to active patient consent records, and token revocation must be propagated to consent management systems when patients withdraw consent.

We implement SMART on FHIR v2.0 authorization servers with full PKCE enforcement, granular v2 scope handling, and EHR launch context propagation, tested against the HL7 Inferno certification test suite prior to ONC submission. Our token lifecycle management integrates with consent management platforms to enforce real-time consent status during token issuance and introspection, preventing access grants that violate patient preferences. Backend Services implementations use asymmetric JWT client authentication (private_key_jwt) with key rotation automation to eliminate shared secret exposure in system-to-system integrations.

Compliance-Native Architecture Guide

Design principles and a structured checklist for building software that is compliant by default — not compliant by retrofit. Covers data architecture, access controls, audit trails, and vendor due diligence.