SMART App Launch vysvetlené: rozsahy, spustenie, PKCE

Krátka odpoveď: SMART App Launch (SMART on FHIR) je špecifikácia HL7, ako aplikácia získa autorizovaný prístup k FHIR serveru v mene používateľa. Je to OAuth 2.0 a OpenID Connect s konvenciami špecifickými pre FHIR: discovering document na .well-known/smart-configuration; dva launch módy (EHR launch, kde EHR otvorí aplikáciu v kontexte aktuálneho pacienta, a standalone launch, kde používateľ otvorí aplikáciu a vyberie pacienta); scopes vo syntaxi rozumnej pre FHIR (patient/Observation.rs znamená čítanie a vyhľadávanie Observation pacienta v kontexte); launch context vrátený s tokenom (ktorý pacient, ktorý encounter); a backend services pre prístup systém-na-systém s podpisom JWT autentizácie klienta. SMART v2 (od roku 2021) urobil PKCE povinným, pridal granulárne scopes a asymetrickú autentizáciu klienta, a je to verzia, ktorú vyžadujú národné programy.

Krok 1: discovery

Objavovanie SMART App Launch začína tým, že aplikácia načíta dokument .well-known/smart-configuration FHIR servera. Tento dokument obsahuje informácie o autorizačných a tokenových koncových bodoch, podporovaných možnostiach (spustenie z EHR, samostatné spustenie, verejné a dôverné klienty, OpenID Connect, povolenia pacienta a používateľa), podporovaných rozsahu (scopes), metódach výzvy kódu PKCE a typoch grantov. Vďaka tomu aplikácia vie, kam má používateľa presmerovať.

GET https://fhir.example-hospital.org/.well-known/smart-configuration

{
  "issuer": "https://auth.example-hospital.org",
  "authorization_endpoint": "https://auth.example-hospital.org/authorize",
  "token_endpoint": "https://auth.example-hospital.org/token",
  "introspection_endpoint": "https://auth.example-hospital.org/introspect",
  "capabilities": ["launch-ehr", "launch-standalone", "client-public", "client-confidential-asymmetric", "sso-openid-connect", "context-ehr-patient", "context-standalone-patient", "permission-patient", "permission-user", "permission-v2", "permission-offline"],
  "scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "patient/*.rs", "user/*.rs", "offline_access"],
  "code_challenge_methods_supported": ["S256"],
  "grant_types_supported": ["authorization_code", "client_credentials"]
}

Aplikácia sa dozvie, kam má poslať používateľa a čo server podporuje.

Krok 2: launch

SMART App Launch má dva režimy spustenia. Pri spustení z EHR lekár otvorí aplikáciu priamo v EHR, ktorá odovzdá parameter iss (FHIR server) a jednorazový spúšťací token (launch token) obsahujúci informácie o aktuálnom pacientovi a stretnutí. Pri samostatnom spustení používateľ otvorí aplikáciu priamo a autorizačný server ho požiada o výber alebo potvrdenie pacienta.

EHR launch. Klinický lekár klikne na aplikáciu v rámci EHR; EHR otvorí spúšťací URL adresár aplikácie s dvoma parametrami: iss (FHIR server) a launch (nevykreslený token, ktorý kóduje aktuálneho pacienta a encounter). Aplikácia musí echo launch vo svojom autorizačnom požiadavku s launch scope.

Standalone launch. Používateľ otvorí aplikáciu priamo; aplikácia pozná FHIR server (vybraný alebo nakonfigurovaný) a žiada o kontext s launch/patient; autorizačný server požiada používateľa, aby vybral alebo potvrdil pacienta.

Krok 3: autorizačný kód s PKCE

Autorizačný krok SMART je tok autorizačného kódu OAuth 2.0 s PKCE: aplikácia presmeruje používateľa na autorizačný koncový bod s jej rozsahu (scopes), aud FHIR servera a výzvou kódu (code challenge). Používateľ sa autentizuje a schváli požiadavku. Aplikácia si vymení vrátený kód a overovateľ kódu (code verifier) za prístupový token, ktorý dorazí spolu s kontextom spustenia (launch context).

GET https://auth.example-hospital.org/authorize?
  response_type=code&client_id=my-app&redirect_uri=https://app.example.org/cb
  &scope=openid%20fhirUser%20launch%20patient/Observation.rs%20patient/Condition.rs%20offline_access
  &state=af0ifjsldkj&aud=https://fhir.example-hospital.org
  &launch=xyz123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

Používateľ sa autentizuje (s poskytovateľom identity nemocnice) a schváli scopes; server presmeruje späť s code; aplikácia ho vymení:

POST https://auth.example-hospital.org/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=https://app.example.org/cb&client_id=my-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid fhirUser launch patient/Observation.rs patient/Condition.rs offline_access",
  "refresh_token": "a8c3...",
  "id_token": "eyJhbGciOi...",
  "patient": "Patient/123",
  "encounter": "Encounter/456",
  "fhirUser": "Practitioner/42",
  "need_patient_banner": true,
  "smart_style_url": "https://ehr.example.org/styles/smart.json"
}

Launch context (patient, encounter, fhirUser) prichádza spolu s tokenom. Verejné klienty (mobilné a prehliadačové aplikácie) používajú PKCE a žiadne tajomstvo klienta; dôverné klienty sa autentizujú pomocou tajomstva alebo, preferovane, pomocou podpísaného JWT (private_key_jwt) pod asymetrickou metódou.

Scopes

Rozsahy (scopes) SMART on FHIR v2 používajú syntax kontext/zdroj.oprávnenia, kde kontext je patient, user alebo system a oprávnenia kombinujú c, r, u, d a s pre vytvorenie, čítanie, aktualizáciu, mazanie a vyhľadávanie, ako napríklad patient/Observation.rs. Granulárne rozsahy pridávajú filter, openid a fhirUser poskytujú identitu používateľa, spúšťacie rozsahy (launch scopes) vyžadujú kontext a offline_access žiada o obnovovací token.

SMART v2 syntax: <context>/<resource>.<permissions> kde kontext je patient (pacient v kontexte), user (čo používateľ môže vidieť) alebo system (backend), a povolenia sú akékoľvek z c create, r read, u update, d delete, s search, v tomto poradí: patient/Observation.rs, user/Patient.rs, system/*.cruds. Granulárne scopes pridávajú filter: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser poskytujú ID token a FHIR identitu používateľa; launch, launch/patient, launch/encounter žiadajú o kontext; offline_access refresh token na použitie, keď je používateľ preč, online_access platný len počas relácie. V1 syntax (patient/Observation.read) je stále akceptovaná mnohými servermi.

Backend services

Pre systém, ktorý funguje bez používateľa (nočný export, integračný engine), SMART Backend Services používa client_credentials s podpísaným JWT tvrdením (verejné kľúče klienta publikované na JWKS URL) a system/ scopes. Žiadny používateľ, žiadny launch kontext, prísna registrácia.

Bezpečné spustenie

Bezpečné spustenie SMART App Launch znamená zaregistrovanie presných URI presmerovania, nikdy nepoužívať implicitný tok, bezpečne ukladať a meniť obnovovacie tokeny, overovať stav (state) a aud ID tokenov, overovať tokeny pri každom API volaní, vynucovať rozsahy (scopes) aj kontext pacienta na úrovni dát, aby token jedného pacienta nikdy nečítal dáta iného, a zaznamenávať každý prístup.

Registrujte presné presmerovacie URI; nikdy nepoužívajte implicitný tok; bezpečne ukladajte refresh tokeny a rotujte ich; overte state; skontrolujte aud ID tokenov; overte tokeny pri každom API volaní (introspekcia alebo JWT validácia) a vynúťte scopes a kontext pacienta na dátovej vrstve, pretože token pre Patient/123 nesmie nikdy čítať Patient/124; zaznamenajte každý prístup (Security and identity: the map). SMART tiež definuje Patient Access Brands, spôsob, ako aplikácie môžu používateľom ukázať, s ktorými organizáciami sa môžu spojiť, a spolupracuje s SMART Health Links pre zdieľanie iniciované pacientom.

Kde je to vyžadované

Pravidlá prístupu pacientov v USA vyžadujú, aby certifikované EHR podporovali SMART App Launch a Backend Services; národné programy v Európe ich prijímajú pre prístup aplikácií (holandský MedMij používa OAuth 2.0 s ekvivalentnými konvenciami); IPS a mnohé implementačné príručky ich predpokladajú. Pozri TEFCA a National electronic health records.

V Anpheros

Anpheros Platform používa OAuth 2.0 s PKCE pre aplikácie a podpisovanie JWT klientov pre backendy, so scopes odvodenými od súhlasu osoby a kontextu pacienta vynúteného pri každej požiadavke. Vývojárska stránka dokumentuje authentication a SMART on FHIR backend pattern pre budovanie na ňom.

Súvisiace stránky

Zdroje

Časté otázky

Je SMART on FHIR to isté ako OAuth 2.0?

Je to OAuth 2.0 a OpenID Connect s dodatkami špecifickými pre FHIR: discovery, launch context, syntax scope a backend services. Akákoľvek OAuth knižnica funguje; SMART konvencie sú to, čo robí aplikáciu prenosnou medzi FHIR servermi.

Potrebujem PKCE pre serverovú aplikáciu?

V SMART v2, áno, pre všetkých klientov používajúcich autorizačný kódový tok. Dôverné klienty pridávajú autentizáciu klienta (tajomstvo alebo podpísaný JWT) navrch.

Aký je rozdiel medzi patient/ a user/ scopes?

patient/ obmedzuje prístup k jedinému pacientovi v launch kontexte; user/ udeľuje prístup k tomu, čo autentizovaný používateľ môže vidieť, naprieč pacientmi. Aplikácie zamerané na pacienta používajú patient/; aplikácie pre klinických lekárov často používajú user/ s kontextom.

Môže SMART aplikácia zapisovať do záznamu?

Ak jej boli udelené povolenia na vytváranie alebo aktualizáciu (c, u) v jej scopes a server to umožňuje. Mnohé nasadenia udeľujú pacientskym aplikáciám iba čítanie a vyhľadávanie a smerujú zápisy cez špecifické zdroje, ako je QuestionnaireResponse.

Anpheros Platform

Vyskúšajte zadarmo v sandboxe

Prvé volanie FHIR za 5 minút. API podľa štandardu HL7 FHIR R4 s integrovaným súhlasom pacienta: vyskúšajte si ho v sandboxe a potom pripojte svoju vlastnú aplikáciu alebo klinický systém.

Vytvoriť sandbox zadarmo Spustiť ukážkovú aplikáciu →Štartovací kód (Python) →Kolekcia Postman →Prečítať návody pre vývojárov →

Zadarmo · 30 syntetických pacientov · bez karty

Tento návod slúži na informačné účely a nenahrádza lekársku radu. Pri rozhodovaní o svojom zdraví sa poraďte so svojím lekárom. V núdzi volajte miestne tiesňové číslo (v Európe 112).

Napísal

Tím Anpheros

Anpheros vyvíja zdravotný záznam, ktorý pacient ovláda a môže zdieľať s akoukoľvek klinikou, na platforme HL7 FHIR R4, so sídlom v EÚ. Tieto návody vám pomôžu pochopiť a usporiadať si svoje zdravie; nenahrádzajú vášho lekára.

O Anpherose →