{"id":58447,"date":"2026-11-05T04:12:49","date_gmt":"2026-11-05T04:12:49","guid":{"rendered":"https:\/\/www.bridge-global.com\/blog\/?p=58447"},"modified":"2026-11-05T04:12:51","modified_gmt":"2026-11-05T04:12:51","slug":"smart-on-fhir-launch-scopes-security","status":"publish","type":"post","link":"https:\/\/www.bridge-global.com\/blog\/smart-on-fhir-launch-scopes-security\/","title":{"rendered":"SMART on FHIR: Launch, Scopes and Security"},"content":{"rendered":"

SMART on FHIR combines a standard app launch, authorization, and FHIR clinical data access so applications can connect to electronic health records. Product teams need to get launch context, least-privilege scopes, security checks, and per-EHR compatibility right, since resources, search behavior, and approval requirements can differ across systems.<\/p>\n

Why a Certified EHR Must Speak SMART on FHIR<\/h2>\n

SMART on FHIR is an open app-launch and authorization profile that lets one healthcare application run against different electronic health records. It combines HL7 FHIR resources for clinical data, OAuth 2.0 for permission, and a standard way to pass the selected patient and signed-in user into the app. Say a clinician opens a chart and launches a lab review tool from inside the record. The tool shouldn't ask the clinician to find the patient again, and it shouldn't invent its own login. SMART defines how that handoff happens.<\/p>\n

The regulatory reason comes first for most U.S. products. Under the ONC Cures Act Final Rule, certified health IT must offer standardized APIs so third-party apps can reach structured clinical data under defined authorization and patient-context rules, a requirement described in the HealthIT.gov overview of the Cures Act API standards<\/a>. That makes SMART on FHIR a platform contract your team designs against, whether you sell to hospitals, build patient-facing tools, or add an embedded module to an existing product.<\/p>\n

Where the standard came from<\/h3>\n

The history is short. The SMART Health IT project began in 2010, when Harvard Medical School and Boston Children's Hospital received a four-year, $15 million award from the U.S. Office of the National Coordinator for Health Information Technology, as recorded in the peer-reviewed history of the SMART project<\/a>. The goal was to let developers build a medical application once and run it across different record systems. In 2013, the project built an open-source FHIR API server and adopted HL7's emerging FHIR standard.<\/p>\n

In January 2014, Cerner, Intermountain Healthcare, Hewlett-Packard for the U.S. Veterans Administration, and Harris Corporation demonstrated prototype implementations. FHIR reached the Draft Standard for Trial Use milestone in the same month. That pairing, FHIR resources plus OAuth-based authorization plus web launch, is still the architecture teams implement today.<\/p>\n

For buyers, the practical questions are what the server publishes, which scopes it honors, and how your team will handle gaps. Those decisions sit inside larger work such as custom healthcare software development, where security review should start early. Teams planning that review can use continuous threat modeling for healthtech teams<\/a> as a prompt to map threats against each launch path before code hardens.<\/p>\n

FHIR Data, OAuth and Launch Context<\/h2>\n

Think of SMART on FHIR as three contracts that travel together. FHIR resources are the clinical vocabulary, typically Patient, Observation, MedicationRequest, and Encounter, narrowed by the US Core profiles an EHR exposes. OAuth 2.0 is the permission system. An authorization server issues an access token limited to granted scopes, and the app sends that token as a bearer token when it calls the FHIR base URL. Launch context tells the app which patient, encounter, or user is already selected, so the clinician doesn't repeat a search.<\/p>\n

One analogy covers it, and then you can drop it. FHIR is the chart's language, OAuth is the badge, and launch context is the open exam room. A badge doesn't tell you how to read the chart. The chart's language doesn't prove you're allowed in the room. You need all three working together before a screen can safely show clinical data.<\/p>\n

\"A<\/figure>\n<\/p>\n

The roles behind the contracts<\/h3>\n

Name the roles before you write code, because each role decides where a control belongs. The EHR's FHIR server acts as the resource server and is often paired with the authorization server that decides whether to issue a token. Your app is the OAuth client that requests tokens. The clinician's browser carries the redirect between them.<\/p>\n

Your backend, or your browser code for a public client, has to handle each role's responses correctly. A token error points to an authorization failure rather than a FHIR parsing failure. A valid token permits access, while the returned Observation still needs to be checked for the fields your logic requires. Separating those failures early saves painful debugging during site testing.<\/p>\n

Discovery ties the roles together. The app reads the server document at .well-known\/smart-configuration to find the authorization and token endpoints and to see which launch and challenge methods the server supports. Don't hard-code those endpoints from a sandbox and assume production matches.<\/p>\n

What each contract gives the app<\/h3>\n

Use this table as a design checklist. Each row should have an owner on your team and a test that proves it works against a real target server.<\/p>\n

What each SMART on FHIR contract gives the app<\/strong><\/p>\n\n\n

\n\n\n\n\n
Contract<\/th>\nJob in the integration<\/th>\nWhat the app receives<\/th>\nWhen it is required<\/th>\n<\/tr>\n
FHIR resources<\/td>\nClinical data model and REST API<\/td>\nPatient, Observation and other profiled resources<\/td>\nAlways, for any clinical read or write<\/td>\n<\/tr>\n
OAuth 2.0 authorization<\/td>\nPermission and token issuance<\/td>\nAuthorization code, then access token bound to scopes<\/td>\nAlways<\/td>\n<\/tr>\n
SMART launch context<\/td>\nBind the app to the open chart or a chosen patient<\/td>\npatient, encounter and related context<\/td>\nEHR launch, or standalone when a patient must be picked<\/td>\n<\/tr>\n
OpenID Connect<\/td>\nAuthenticated user identity<\/td>\nID token when openid and fhirUser are granted<\/td>\nOnly if the app must know which user launched it<\/td>\n<\/tr>\n<\/table><\/figure>\n\n\n

Add OpenID Connect only when the product needs a signed-in user identity. The scopes openid and fhirUser, when granted, allow the app to receive an ID token. If your app only needs patient data for a chart already open, requesting identity scopes adds consent surface without improving the feature.<\/p>\n

The mapping work sits between these contracts and your own product model. Your internal objects rarely match FHIR resources field for field, so someone must decide how codes, units, statuses, and missing values translate. That's the core engineering behind FHIR integration services<\/a> and the FHIR and HL7 integration services guide<\/a>. Vague assumptions turn into site-specific defects if nobody writes the mapping down.<\/p>\n

A screen is ready to build when the team can name the FHIR resource, scope, and launch context it depends on.<\/p>\n

EHR Launch Versus Standalone Launch<\/h2>\n

Choose a launch style before you write the authorize URL. Swapping flows later changes your scope request, your consent screen, and your handling of patient selection. Both flows end with an access token, but each establishes patient context differently.<\/p>\n

In an EHR launch, the record system opens the app and places an opaque launch handle on the launch URL. The app returns that handle on the authorization request so the server can attach session context, including the selected patient, as described in the HL7 SMART App Launch specification<\/a>. The launch scope is what permits that embedded context. Treat the handle as opaque. Don't parse it, store it as a clinical identifier, or reuse it after the launch completes.<\/p>\n

\"A<\/figure>\n<\/p>\n

In a standalone launch, the user opens the app outside the EHR, from a phone, a portal link, or a bookmark. There's no session handle because there's no EHR session. The launch\/patient<\/strong> scope asks the authorization server to have the user pick a patient during consent. If you request the wrong context scope, the server may reject the request or return a token without the patient context your first screen expects.<\/p>\n

The shared sequence in order<\/h3>\n

Both flows then follow the same redirect and token exchange. Write these steps into your implementation ticket, not just your architecture diagram.<\/p>\n

    \n
  1. \n

    Discover endpoints:<\/strong> Fetch .well-known\/smart-configuration<\/strong> and read the authorization and token endpoints.<\/p>\n<\/li>\n

  2. \n

    Create PKCE values:<\/strong> Generate a verifier and derive its S256<\/strong> challenge.<\/p>\n<\/li>\n

  3. \n

    Redirect to authorize:<\/strong> Send the client ID, redirect URI, requested scopes, state<\/strong>, code challenge, and, for an EHR launch only, the launch handle.<\/p>\n<\/li>\n

  4. \n

    Validate the return:<\/strong> Reject the response if state<\/strong> does not match what you sent.<\/p>\n<\/li>\n

  5. \n

    Exchange the code:<\/strong> Post the authorization code and the verifier to the token endpoint.<\/p>\n<\/li>\n

  6. \n

    Plan for expiry:<\/strong> Read expires_in<\/strong> from the token response and plan a new authorization when the token lapses.<\/p>\n<\/li>\n

  7. \n

    Call FHIR safely:<\/strong> Call the FHIR base URL with the bearer token, never place it in a URL or long-lived browser storage, and confirm the token audience matches the FHIR server you're calling.<\/p>\n<\/li>\n<\/ol>\n

    Step 6 catches teams out. A token that works during a short demo can expire mid-shift, and an app that responds with a blank screen will lose clinicians quickly. Decide what the user sees when reauthorization is needed, and test that path on purpose by using short-lived tokens in your sandbox.<\/p>\n

    Step 7 matters just as much. A token issued for one FHIR server shouldn't be replayed against another, even if both sit behind similar URLs. Checking audience expectation is a small control that prevents a confusing class of wrong-environment bugs.<\/p>\n

    EHR launch and standalone launch side by side<\/h3>\n\n\n
    \n\n\n\n\n
    Question<\/th>\nEHR launch<\/th>\nStandalone launch<\/th>\n<\/tr>\n
    Who starts the app<\/td>\nThe EHR opens the app from a launch URL<\/td>\nThe user opens the app outside the EHR<\/td>\n<\/tr>\n
    Context handle<\/td>\nOpaque launch parameter from the EHR session<\/td>\nNo EHR session handle<\/td>\n<\/tr>\n
    Context scope<\/td>\nlaunch<\/td>\nlaunch\/patient<\/td>\n<\/tr>\n
    Who selects the patient<\/td>\nAlready selected in the EHR<\/td>\nThe authorization server asks the user<\/td>\n<\/tr>\n<\/table><\/figure>\n\n\n

    If your product supports both styles, build them as two explicit entry points with separate tests. Don’t detect the flow by guessing from missing parameters and then improvise. Explicit entry points make consent behavior predictable, and predictable consent behavior is what hospital reviewers want to see.<\/p>\n

    Scope Strings That Enforce Least Privilege<\/h2>\n

    A SMART scope encodes who the access is for, which FHIR resource is involved, and which operations are allowed. SMART App Launch 2.0 writes that structure as patient, user, or system, then a FHIR resource or wildcard, then a dot and the letters c, r, u, d, and s for create, read, update, delete, and search, according to the US Core scopes documentation<\/a>. The current published version on hl7.org is SMART App Launch 2.2 (STU 2.2)<\/a>. An optional search parameter can narrow the set further.<\/p>\n

    Read a scope from left to right, and it tells a story. The subject says whose data boundary applies. The resource says which clinical concept is exposed. The letters say what the app may do to it. If any part is broader than the screen needs, the request is broader than it should be.<\/p>\n

    Four strings worth decoding<\/h3>\n