SMART App Launch ismertetése: hatókörök, indítás, PKCE

Rövid válasz: A SMART App Launch (SMART on FHIR) az HL7 specifikációja arra, hogyan kap egy alkalmazás engedélyezett hozzáférést egy FHIR szerverhez egy felhasználó nevében. Ez az OAuth 2.0 és az OpenID Connect FHIR-specifikus konvenciókkal: egy discovery dokumentum a .well-known/smart-configuration címen; két indítási mód (EHR indítás, ahol az EHR megnyitja az alkalmazást az aktuális beteg kontextusában, és önálló indítás, ahol a felhasználó megnyitja az alkalmazást és kiválaszt egy beteget); hatókörök FHIR-kompatibilis szintaxisban (patient/Observation.rs azt jelenti, hogy olvashatók és kereshetők az aktuális beteg megfigyelései); indítási kontextus a token mellett (melyik beteg, melyik vizsgálat); és backend szolgáltatások rendszer-rendszer közötti hozzáféréshez aláírt JWT kliens-hitelesítéssel. A SMART v2 (2021-től) kötelezővé tette a PKCE-t, hozzáadott granuláris hatóköröket és aszimmetrikus kliens-hitelesítést, és ez az a verzió, amit a nemzeti programok megkövetelnek.

1. lépés: discovery

A SMART App Launch felfedezése azzal kezdődik, hogy az alkalmazás lekéri a FHIR szerver .well-known/smart-configuration dokumentumát, amely felsorolja az engedélyezési és token végpontokat, a támogatott képességeket (EHR indítás, önálló indítás, nyilvános és bizalmas kliensek, OpenID Connect, beteg- és felhasználói engedélyek), a támogatott hatóköröket, a PKCE kód kihívás módszereket és a kiutalási típusokat, így az alkalmazás tudja, hova küldje a felhasználót.

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"]
}

Az alkalmazás megtudja, hova küldje a felhasználót, és mit támogat a szerver.

2. lépés: indítás

A SMART App Launch két indítási móddal rendelkezik. EHR indítás esetén a klinikus az alkalmazást az EHR-en belül nyitja meg, amely átad egy iss paramétert (a FHIR szerver) és egy átlátszatlan indítási tokent, amely kódolja az aktuális beteget és a vizitet. Önálló indítás esetén a felhasználó közvetlenül nyitja meg az alkalmazást, és az engedélyezési szerver arra kéri, hogy válasszon ki vagy erősítsen meg egy beteget.

EHR indítás. A klinikus rákattint az alkalmazásra az EHR-ben; az EHR megnyitja az alkalmazás indítási URL-jét két paraméterrel: iss (a FHIR szerver) és launch (egy átlátszatlan token, amely az aktuális beteget és vizsgálatot kódolja). Az alkalmazásnak vissza kell küldenie a launch értéket az engedélyezési kérésben a launch hatókörrel.

Önálló indítás. A felhasználó közvetlenül megnyitja az alkalmazást; az alkalmazás ismeri a FHIR szervert (kiválasztott vagy konfigurált), és a launch/patient segítségével kér kontextust; az engedélyezési szerver arra kéri a felhasználót, hogy válasszon vagy erősítse meg a beteget.

3. lépés: engedélyezési kód PKCE-vel

A SMART engedélyezési lépés az OAuth 2.0 engedélyezési kód folyamata PKCE-vel: az alkalmazás a felhasználót az engedélyezési végpontra küldi a hatóköreivel, a FHIR szerver aud azonosítójával és egy kód kihívással; a felhasználó hitelesíti magát és jóváhagyja; az alkalmazás kicseréli a visszaküldött kódot és kód ellenőrzőt egy hozzáférési tokenre, amely az indítási kontextussal együtt érkezik.

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

A felhasználó hitelesíti magát (a kórház identitásszolgáltatójával) és jóváhagyja a hatóköröket; a szerver visszairányít egy code értékkel; az alkalmazás kicseréli azt:

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"
}

Az indítási kontextus (patient, encounter, fhirUser) a token mellett érkezik. A nyilvános kliensek (mobil és böngésző alkalmazások) PKCE-t használnak titkos kulcs nélkül; a bizalmas kliensek titkos kulccsal vagy, lehetőleg, aláírt JWT-vel (private_key_jwt) hitelesítik magukat az aszimmetrikus módszerrel.

Hatókörök

A SMART on FHIR v2 hatókörök a kontextus/erőforrás.engedélyek szintaxist használják, ahol a kontextus patient, user vagy system, a permissions pedig a c, r, u, d és s kombinációja a létrehozás, olvasás, frissítés, törlés és keresés esetében, mint például a patient/Observation.rs. A granularis hatókörök szűrőt adnak hozzá, az openid és fhirUser a felhasználó azonosítóját adják meg, az launch hatókörök a kontextust kérik, az offline_access pedig egy frissítési tokent kér.

SMART v2 szintaxis: <kontextus>/<erőforrás>.<engedélyek> ahol a kontextus patient (az aktuális beteg), user (amit a felhasználó láthat) vagy system (backend), és az engedélyek bármelyike lehet c létrehozás, r olvasás, u frissítés, d törlés, s keresés, ebben a sorrendben: patient/Observation.rs, user/Patient.rs, system/*.cruds. A granuláris hatókörök szűrőt adnak hozzá: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. Az openid fhirUser egy ID tokent és a felhasználó FHIR azonosítóját adja; a launch, launch/patient, launch/encounter kontextust kér; az offline_access egy frissítési tokent biztosít, amikor a felhasználó távol van, az online_access pedig csak a munkamenet alatt érvényes. Az v1 szintaxis (patient/Observation.read) még mindig elfogadott sok szerver által.

Backend szolgáltatások

Egy olyan rendszer számára, amely felhasználó nélkül működik (éjszakai export, integrációs motor), a SMART Backend Services a client_credentials használja aláírt JWT-s állítással (a kliens nyilvános kulcsai egy JWKS URL-en közzétéve) és system/ hatókörökkel. Nincs felhasználó, nincs indítási kontextus, szigorú regisztráció.

Biztonságos futtatás

A SMART App Launch biztonságos futtatása azt jelenti, hogy pontos átirányítási URI-kat regisztrálunk, soha nem használjuk az implicit folyamatot, biztonságosan tároljuk és forgatjuk a frissítési tokeneket, érvényesítjük az ID tokenek állapotát és aud azonosítóját, minden API hívásnál érvényesítjük a tokeneket, az adatrétegen érvényesítjük mind a hatóköröket, mind a beteg kontextust, így egy betegre vonatkozó token soha nem olvashat másikat, és minden hozzáférést naplózunk.

Regisztráljon pontos átirányítási URI-kat; soha ne használja az implicit folyamatot; tárolja biztonságosan a frissítési tokeneket és forgassa őket; érvényesítse a state értéket; ellenőrizze az ID tokenek aud értékét; minden API hívásnál érvényesítse a tokeneket (introspekció vagy JWT érvényesítés), és érvényesítse a hatóköröket és a beteg kontextust az adatrétegen, mert egy Patient/123 tokenhez tartozó token soha nem olvashatja a Patient/124 értéket; naplózzon minden hozzáférést (Security and identity: the map). A SMART definiálja a Patient Access Brands-t is, amely egy módja annak, hogy az alkalmazások megmutassák a felhasználóknak, mely szervezetekhez csatlakozhatnak, és együttműködik a SMART Health Links-szel a beteg által kezdeményezett megosztás érdekében.

Hol van rá szükség

Az amerikai beteg-hozzáférési szabályok megkövetelik a tanúsított EHR-ektől a SMART App Launch és a Backend Services támogatását; az európai nemzeti programok elfogadják az alkalmazásokhoz való hozzáféréshez (Hollandia MedMij OAuth 2.0-t használ hasonló konvenciókkal); az IPS és sok implementációs útmutató feltételezi. Lásd TEFCA és National electronic health records.

Az Anpheros-ban

Az Anpheros Platform OAuth 2.0-t használ PKCE-vel az alkalmazásokhoz és aláírt JWT kliens-hitelesítéssel a backendekhez, a személy beleegyezéséből származó hatókörökkel és a beteg kontextusának minden kérésnél történő érvényesítésével. A fejlesztői weboldal dokumentálja a hitelesítést és a SMART on FHIR backend mintát az erre épülő fejlesztéshez.

Kapcsolódó oldalak

Források

Gyakori kérdések

A SMART on FHIR ugyanaz, mint az OAuth 2.0?

Ez az OAuth 2.0 és az OpenID Connect FHIR-specifikus kiegészítésekkel: discovery, indítási kontextus, a hatókör szintaxis és a backend szolgáltatások. Bármely OAuth könyvtár működik; a SMART konvenciók azok, amelyek hordozhatóvá teszik az alkalmazást a FHIR szerverek között.

Szükségem van PKCE-re egy szerveroldali alkalmazáshoz?

A SMART v2-ben igen, minden kliens számára, amely az engedélyezési kód folyamatot használja. A bizalmas kliensek ezen felül kliens-hitelesítést (titkos kulcs vagy aláírt JWT) adnak hozzá.

Mi a különbség a patient/ és a user/ hatókörök között?

A patient/ hozzáférést az indítási kontextusban lévő egyetlen betegre korlátozza; a user/ hozzáférést biztosít ahhoz, amit az hitelesített felhasználó láthat, betegektől függetlenül. A beteg-orientált alkalmazások patient/-et használnak; a klinikus alkalmazások gyakran user/-et használnak kontextussal.

Írhat egy SMART alkalmazás az egészségügyi rekordba?

Ha megkapta a létrehozási vagy frissítési engedélyeket (c, u) a hatókörében, és a szerver ezt megengedi. Sok telepítés csak olvasási és keresési engedélyeket ad a beteg-alkalmazásoknak, és a írásokat olyan specifikus erőforrásokon keresztül irányítja, mint a QuestionnaireResponse.

Anpheros Platform

Próbálja ki ingyen a sandboxban

Az első FHIR-hívás 5 perc alatt. Egy HL7 FHIR R4 API, amely tartalmazza a beteg beleegyezését: próbáld ki a sandboxban, majd csatlakoztasd saját alkalmazásodat vagy klinikai rendszeredet.

Ingyenes sandbox létrehozása Mintaalkalmazás indítása →Kezdőkód (Python) →Postman-gyűjtemény →Olvasd el a fejlesztői útmutatókat →

Ingyenes · 30 szintetikus beteg · kártya nélkül

Ez az útmutató tájékoztató jellegű, és nem helyettesíti az orvosi tanácsot. Az egészségeddel kapcsolatos döntésekhez beszélj az orvosoddal. Vészhelyzetben hívja a helyi segélyhívó számot (Európában 112).

Szerző:

Az Anpheros csapata

Az Anpheros egy olyan egészségügyi nyilvántartást épít, amelyet a beteg irányít, és megoszthat bármelyik klinikával, egy EU-ban működő HL7 FHIR R4 platformon. Ezek az útmutatók segítenek megérteni és rendszerezni az egészségügyi adataidat; nem helyettesítik az orvosodat.

Tudj meg többet az Anpherosról →