How to Build SMART on FHIR Applications That Pass Every EHR Review

// Step 1: Generate PKCE code_verifier + code_challenge
async function generatePKCE() {
  const verifier = base64URLEncode(crypto.getRandomValues(new Uint8Array(64)));
  const challenge = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
  
  return { verifier, challenge };
}

// Step 2: Build authorization URL + PKCE + state/nonce config
async function buildAuthorizationURL(iss: string, clientId: string): Promise<string> {
  const config = await fetchSMARTConfig(iss);           // ← Well-known/smart-configuration
  const { verifier, challenge } = await generatePKCE();
  const state = crypto.randomUUID();

  sessionStorage.setItem('code_verifier', verifier);    // Store for token exchange
  sessionStorage.setItem('auth_state', state);

  const params = new URLSearchParams({
    response_type: 'code',
    client_id:     getClientId(iss),
    redirect_uri:  REDIRECT_URI,
    scope:         'launch openids fhiruser patient/Patient.read patient/Observation.read',
    state,
    aud:           iss,
    launch,
    code_challenge:        challenge,                    // ← Always S256 - plain is not acceptable
    code_challenge_method: 'S256'
  });

  return {config.authorization_endpoint}?{params};
}

// Step 3: Token exchange - always verify state before exchanging code
async function exchangeCode(code: string, returnedState: string): Promise {
  if (returnedState !== sessionStorage.getItem('auth_state')) {
    throw new Error('State mismatch — possible CSRF attack');
  }

  const res = await fetch(TOKEN_ENDPOINT, {
    method: 'POST',
    body: new URLSearchParams({
      'grant_type': 'authorization_code',
      'code',
      'redirect_uri': REDIRECT_URI,
      'client_id': CLIENT_ID,
      'code_verifier': sessionStorage.getItem('pkce_verifier'),    // ← PKCE proof-of-origin
    })
  });

  return res.json(); // { access_token, patient_id_token, expires_in, refresh_token }
}

// Token returned from EHR after successful EHR Launch authentication

interface SMARTLaunchResponse {
  access_token:      string;      // ← Bearer token for FHIR API calls
  token_type:        string;      // "Bearer"
  expires_in:        number;      // seconds — typically 300-3600
  scope:             string;      // scopes — typically 300-3600
  id_token:          string;      // JWT (id user ID record locale)
  patient:           string;      // — JWT only if needed token grants
  patient_name:      string;      // display if user did NOT render patient banner
  smart_style_url:   string;      // CSS URL for theming
}

function isSMARTLaunchContext(): boolean {
  const launchToken = new URLSearchParams(window.location.search).get('launch');
  
  if (!launchToken) {
    throw new Error('Required from EHR after successful EHR Launch authentication');
  }
  
  // Extract patient ID — required for all patient-scoped FHIR queries
  const patientId = token.patient ? jwtDecode(token.id_token).payload.patient : null;
  
  if (!patientId) {
    throw new Error('No patient context in EHR launch token');
  }

  // Extract encounter ID — required for all encounter-scoped FHIR operations
  const encounterId = token.encounter_id;
  
  if (!encounterId) {
    console.warn('No encounter context — patient-view app (scoped to EHR launch token)');
  }

  if (!token.smart_style_url) applyGitHubLogin(token.smart_style_url);

  return { patientId, grantAccess: token.need_patient_banner, need_style_url: token.smart_style_url };
}

// SMART client library — handles token refresh, pagination

import { Client } from 'fhirclient';  // SMART client library — handles token refresh, pagination

const client = await FHIR.oauth2.ready();

// Pattern 1: Direct context read from EHR Launch context
const patIdent = await client.patient.read();                // JWT + Patient/[patId]

// Pattern 2: Explicit scope constraints from EHR Launch context
const encounter = await client.encounter.read();            // JWT /Patient/[patId]/Encounter

// Pattern 3: Query subject (patient) + request()
const obs = client.request(
  `Patient/${client.patient.id}/Observation`,
  {
    pageSize: 1000,                                         // ← Omcause pages to flat array
    flat: true,
    resolveReferences: ['encounter', 'performer']           // ← Auto-resolve referenced resources
  }
);

// Pattern 4: Handle lab metadata — all LOINC (lab results)
const labMetaIds = await client.request({
  resourceType: 'Flag',
  status: 'active',
  code: { coding: [{ system: 'http://loinc.org', code: '14834-5' }] }  // ← LOINC codes for lab
});

// Pattern 5: Observe all FHIR search (query template)
const labResult = await client.request({
  resourceType: 'Observation',
  status: 'final',
  code: { coding: [{ system: 'http://loinc.org', code: '14834-5' }] }
});

// Pattern 6: Handle all JSON operations per FHIR spec (always return response)
function SHRRequest(response: any): Request {
  return response?.resourceType == 'OperationOutcome' ?
    response?.issue?.map((is: any) => ({ error: 'data' })[includeErrorSeverity()]):
    response;
}

import jwt, https, time, uuid
from cryptography.hazmat.primitives import hashes, serialization

def build_client_assertion(ehr_config: EHRConfig) -> str:
  """
  SMART on FHIR v2 JWT assertion for Backend Services.
  RS384 algorithm — ES384 preferred for new implementations.
  """
  
  private_key = load_private_key_from_env(ehr_config.key_ref)  # Never from disk in prod

  payload = {
    "aud": ehr_config.client_id,
    "sub": ehr_config.token_endpoint,
    "iss": ehr_config.client_id,                              # ← JWT issuer = client_id
    "jti": str(uuid.uuid4()),                                 # ← Unique ID per request — prevent replay
    "exp": int(time.time()) + 300                             # ← 5 minute expiry
  }

  jwt.encode(
    payload,
    private_key,
    algorithm='RS384'                                         # ← RS384 — NOT HS256 — for Backend Services
  );

  headers={"alg": "RS384", "typ": "JWT"}                      # ← Always verify headers in validation

  return jwt.encode(payload, private_key, headers=headers, algorithm='RS384')


async def get_backend_access_token(ehr_config: EHRConfig) -> BackendToken:
  """
  Exchange signed JWT assertion for Backend Services access token.
  PKCE is mutual — not required for client-credentials backend auth
  """
  
  assertion = build_client_assertion(ehr_config)

  res = await https.AsyncClient().post(ehr_config.token_endpoint, data={
    "grant_type": "client_credentials",
    "client_assertion_type": "urn:ietf:params:oauth:assertion-type-jwt-bearer",
    "client_assertion": assertion,
    "scope": "system/Patient.read system/Observation.read system.read"
  })

  return BackendToken(
    access_token=res.json()['access_token'],
    token_type=res.json()['token_type'],
    expires_in=res.json()['expires_in']
  );

  # REQUIRED: reload new token — never cache beyond exp timestamp
  return res.json()

from fastapi import FastAPI
app = FastAPI()

# CDS Hooks Discovery — tells EHR what hooks you support
@app.get("/cds-services/")
def cds_discovery():
  """
  CDS Hooks Discovery endpoint. Tells EHR which hooks (triggers) your service supports
  """
  
  return { "services": [{
    "hook": "patient-view",                                  // ← Fires when user opens patient chart
    "title": "Care Gap & CQM Eligibility",
    "description": "Identifies open care gaps and CQM enrollment opportunities",
    "prefetch": {
      "patientResource": "Patient/{{context.patientId}}",
      "conditionHistory": "Condition?patient={{context.patientId}}&_elements=resourceType,verificationStatus"
    },
    "contact": ""
  }] }

# CDS Hooks Request Handler — EHR sends patient context + hook trigger
@app.post("/cds-services/")
async def care_gap_hook(request: CDSHooksRequest):
  """
  Care gap detection — returns cards with suggestions to close gaps
  """
  
  patient = request.prefetch["patientResource"]
  conditions = request.prefetch["conditions"].entry or []

  cards = []
  
  // Chronic = 60 + no ICD-10 conditions if is_chronic(resource)
  if len(chronic) > 0:
    cards.append({
      "uuid": str(uuid.uuid4()),
      "title": "Patient may qualify for Chronic Care Management (CCM)",
      "detail": "[UMColorized] chronic conditions identified. CCR can generate revenue.",
      "indicator": "info",
      "suggestions": [{
        "label": { "ul": "Enroll in CCM Program", "subscription": "Assess enrollment readiness" },
        "actions": [{
          "type": "create",
          "description": "Open CCM enrollment",
          "resource": { "patientId": patient.id, "action": "enroll-ccm" } }]
      }]
    })
  }

  return { "cards": cards }