Scaffolding Smart On Fhir

Scaffolding SMART on FHIR

To put an OpenMed-powered tool inside a clinician's EHR (Epic, Cerner/Oracle Health), you build a SMART on FHIR app: a web app the EHR launches with an OAuth2 flow, granting scoped, time-limited access to the patient's FHIR data. The app fetches the clinical notes, then runs OpenMed on-device (de-id + NER) — so PHI is processed locally and only de-identified output, if anything, leaves the browser/host.

When to use

Reach for this when the deliverable is a clinician-facing app embedded in an EHR, or a standalone app authorizing against an EHR's FHIR endpoint. Triggers: "SMART on FHIR", "EHR launch", "OAuth2 scopes", "Epic/Cerner app", "embed OpenMed in the chart". For pulling notes at cohort scale (no UI), use exporting-bulk-fhir instead.

Two launch flows

• EHR launch — clinician clicks your app in the chart. The EHR opens your launch_uri?iss=<fhir-base>&launch=<opaque>; you complete OAuth2 and inherit the current patient/encounter context.
• Standalone launch — user opens your app directly; it discovers the FHIR server and runs OAuth2, and the user/EHR picks the patient.

Both use SMART App Launch v2: OAuth2 authorization code flow with PKCE (required in v2), discovered via .well-known/smart-configuration.

Quick start: the launch sequence

Copy code
1. EHR launch URL:
   GET https://app.example/launch?iss=https://ehr.example/fhir&launch=abc123

2. Discover endpoints:
   GET https://ehr.example/fhir/.well-known/smart-configuration
   -> { "authorization_endpoint": ".../authorize",
        "token_endpoint": ".../token",
        "code_challenge_methods_supported": ["S256"],
        "capabilities": ["launch-ehr","client-public","context-ehr-patient", ...] }

3. Redirect the browser to authorize (PKCE + the launch token):
   GET .../authorize?
       response_type=code&
       client_id=YOUR_CLIENT_ID&
       redirect_uri=https://app.example/callback&
       scope=launch openid fhirUser patient/DocumentReference.rs patient/Patient.r&
       state=RANDOM&
       aud=https://ehr.example/fhir&
       launch=abc123&
       code_challenge=BASE64URL(SHA256(verifier))&
       code_challenge_method=S256

4. Callback -> exchange code for token:
   POST .../token
       grant_type=authorization_code&code=...&redirect_uri=...&
       client_id=...&code_verifier=ORIGINAL_VERIFIER
   -> { "access_token": "...", "token_type": "Bearer", "expires_in": 3600,
        "scope": "patient/DocumentReference.rs ...",
        "patient": "Patient-123", "encounter": "Encounter-9",
        "id_token": "..." }

5. Call FHIR with the token:
   GET https://ehr.example/fhir/DocumentReference?patient=Patient-123&type=clinical-note
       Authorization: Bearer <access_token>

The token response carries the launch context (patient, sometimes encounter, and in v2 a fhirContext array). Use patient to scope every subsequent query.

Scopes you actually need

SMART v2 scopes are <level>/<Resource>.<permissions> where permissions are a subset of c r u d s (create/read/update/delete/search) — .rs = read + search. Request the minimum:

Prefer patient/… (current-patient) over user/… (everything the user can see) to keep the blast radius small. Granular v2 scopes (.rs) are stricter than the v1 .read/.write forms — use them.

Where OpenMed runs

Notes arrive as DocumentReference → content.attachment (often base64 or a url to a Binary). Decode, then process locally:

pythonCopy code
import base64, openmed

note_b64 = document_reference["content"][0]["attachment"]["data"]
note = base64.b64decode(note_b64).decode("utf-8")

# De-identify on-device before anything else touches it
deid = openmed.deidentify(note, method="replace", policy="hipaa_safe_harbor")

# Clinical NER on the (de-identified or raw, per your IRB) text
entities = openmed.analyze_text(deid.text, model_name="disease_detection_superclinical")
# -> render highlights in the SMART app UI, or export FHIR (exporting-to-fhir)

OpenMed models run on-device after a one-time download — no note text is sent to a third party by OpenMed. Keep the access token and any PHI in memory only; do not log them.

Hand-off to / from OpenMed

• From the EHR to OpenMed: fetched DocumentReference notes → openmed.deidentify → openmed.analyze_text.
• From OpenMed back to the EHR: built FHIR resources (exporting-to-fhir) → to_bundle (assembling-fhir-bundles) → write back with a write scope (e.g. patient/Condition.c) if your use case persists findings. Validate first (validating-us-core).
• MCP option: if the app calls a local OpenMed MCP server, the tools are openmed_analyze_text and openmed_deidentify — same on-device guarantees.

Edge cases & gotchas

• PKCE is mandatory in v2 and for public (browser) clients always. Generate a fresh code_verifier per launch; never reuse.
• Validate state and aud. Reject the callback if state does not match; set aud to the FHIR base or the EHR will reject the authorize request.
• Tokens are short-lived. Handle expires_in; use offline_access + refresh tokens only if you genuinely need background access, and store them securely (never client-side for confidential clients).
• Scope down-grade is normal. The EHR may grant fewer scopes than requested; read the returned scope and degrade gracefully.
• Don't persist PHI in the browser. Process in memory; if you must cache, cache the de-identified output only.
• App registration is per-EHR. Epic (fhir.epic.com) and Cerner each have their own developer portals, client registration, and sandbox FHIR endpoints; test against the sandbox before go-live.
• OpenMed stays local. The OAuth2 token authorizes FHIR calls to the EHR; it has nothing to do with OpenMed, which needs no network at inference time.

Standards & references

• SMART App Launch v2: https://hl7.org/fhir/smart-app-launch/
• Scopes & launch context: https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html
• .well-known/smart-configuration: https://hl7.org/fhir/smart-app-launch/conformance.html
• OAuth2 PKCE (RFC 7636): https://datatracker.ietf.org/doc/html/rfc7636
• Epic on FHIR: https://fhir.epic.com/
• Oracle Health (Cerner) FHIR: https://fhir.cerner.com/