SMART App Launch vysvětleno: rozsahy, spuštění, PKCE

Krátká odpověď: SMART App Launch (SMART on FHIR) je specifikace HL7, jak aplikace získá autorizovaný přístup k FHIR serveru jménem uživatele. Jedná se o OAuth 2.0 a OpenID Connect s konvencemi specifickými pro FHIR: objevovací dokument na .well-known/smart-configuration; dva spouštěcí režimy (EHR launch, kde EHR otevře aplikaci v kontextu aktuálního pacienta, a standalone launch, kde uživatel otevře aplikaci a vybere pacienta); rozsahy ve syntaxi rozumějící FHIR (patient/Observation.rs znamená čtení a vyhledávání Observation pacienta v kontextu); spouštěcí kontext vrácený s tokenem (který pacient, který záznam o návštěvě); a backendové služby pro přístup systém-systém s podepsanou JWT autentizací klienta. SMART v2 (od roku 2021) učinil PKCE povinným, přidal granulární rozsahy a asymetrickou autentizaci klienta a je to verze, kterou vyžadují národní programy.

Krok 1: Objevování

Objevování SMART App Launch začíná tím, že si aplikace stáhne dokument .well-known/smart-configuration FHIR serveru. Ten obsahuje adresy koncových bodů pro autorizaci a tokeny, podporované funkce (spuštění z EHR, samostatné spuštění, veřejní a důvěrní klienti, OpenID Connect, oprávnění pacienta a uživatele), podporované rozsahy, metody výzvy pro PKCE a typy udělení. Aplikace tak ví, kam má uživatele přesměrovat.

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

Aplikace zjistí, kam má uživatele poslat a co server podporuje.

Krok 2: Spuštění

SMART App Launch má dva režimy spuštění. Při spuštění z EHR otevře lékař aplikaci uvnitř EHR, která předá parametr iss (FHIR server) a neprůhledný spouštěcí token s informacemi o aktuálním pacientovi a setkání. Při samostatném spuštění otevře uživatel aplikaci přímo a autorizační server ho požádá o výběr nebo potvrzení pacienta.

EHR launch. Klinický pracovník klikne na aplikaci uvnitř EHR; EHR otevře spouštěcí URL aplikace se dvěma parametry: iss (FHIR server) a launch (nečitelný token, který kóduje aktuálního pacienta a záznam o návštěvě). Aplikace musí echo launch ve svém autorizačním požadavku s rozsahem launch.

Standalone launch. Uživatel otevře aplikaci přímo; aplikace zná FHIR server (vybraný nebo nakonfigurovaný) a žádá o kontext pomocí launch/patient; autorizační server požádá uživatele o výběr nebo potvrzení 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: aplikace přesměruje uživatele na autorizační koncový bod s jejími rozsahy, aud FHIR serveru a výzvou kódu. Uživatel se autentizuje a schválí. Aplikace si vymění vrácený kód a ověřovací kód za přístupový token, který dorazí spolu s kontextem spuštění.

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

Uživatel se autentizuje (s poskytovatelem identity nemocnice) a schválí rozsahy; server přesměruje zpět s code; aplikace jej vymění:

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

Spouštěcí kontext (patient, encounter, fhirUser) dorazí spolu s tokenem. Veřejné klienty (mobilní a prohlížečové aplikace) používají PKCE a žádné tajné klíče klienta; důvěrné klienty autentizují pomocí tajného klíče nebo, s výhodou, pomocí podepsané JWT (private_key_jwt) podle asymetrické metody.

Rozsahy

Rozsahy SMART on FHIR v2 používají syntaxi kontext/zdroj.oprávnění, kde kontext je patient, user nebo system a oprávnění kombinují c, r, u, d a s pro vytvoření, čtení, aktualizaci, smazání a vyhledávání, jako například patient/Observation.rs. Granulární rozsahy přidávají filtr, openid a fhirUser poskytují identitu uživatele, spouštěcí rozsahy vyžadují kontext a offline_access vyžaduje obnovovací token.

Syntaxe SMART v2: <kontext>/<zdroj>.<oprávnění> kde kontext je patient (pacient v kontextu), user (cokoliv uživatel může vidět) nebo system (backend), a oprávnění jsou libovolná z c create, r read, u update, d delete, s search, v tomto pořadí: patient/Observation.rs, user/Patient.rs, system/*.cruds. Granulární rozsahy přidávají filtr: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser poskytují ID token a FHIR identitu uživatele; launch, launch/patient, launch/encounter žádají o kontext; offline_access obnovovací token pro použití, když je uživatel pryč, online_access platný pouze během relace. Syntaxe v1 (patient/Observation.read) je stále přijímána mnoha servery.

Backendové služby

Pro systém, který funguje bez uživatele (noční export, integrační engine), SMART Backend Services používá client_credentials s podepsaným JWT tvrzením (veřejné klíče klienta publikované na JWKS URL) a rozsahy system/. Žádný uživatel, žádný spouštěcí kontext, přísná registrace.

Bezpečné spouštění

Bezpečné spouštění SMART App Launch znamená registraci přesných přesměrovacích URI, nikdy nepoužívat implicitní tok, bezpečně ukládat a rotovat obnovovací tokeny, ověřovat stav a aud ID tokenů, ověřovat tokeny při každém volání API, vynucovat jak rozsahy, tak kontext pacienta na vrstvě dat, aby token pro jednoho pacienta nikdy nečetl jiného, a zaznamenávat každý přístup.

Registrujte přesné přesměrovací URI; nikdy nepoužívejte implicitní tok; bezpečně ukládejte obnovovací tokeny a rotujte je; ověřujte state; kontrolujte aud ID tokenů; ověřujte tokeny při každém volání API (introspekce nebo ověření JWT) a vynucujte rozsahy a kontext pacienta na vrstvě dat, protože token pro Patient/123 nikdy nesmí číst Patient/124; zaznamenávejte každý přístup (Bezpečnost a identita: mapa). SMART také definuje Patient Access Brands, způsob, jak aplikace ukazují uživatelům, ke kterým organizacím se mohou připojit, a spolupracuje s SMART Health Links pro sdílení iniciované pacientem.

Kde je vyžadováno

Pravidla přístupu pacientů v USA vyžadují, aby certifikované EHR podporovaly SMART App Launch a Backend Services; národní programy v Evropě jej přijímají pro přístup aplikací (nizozemský MedMij používá OAuth 2.0 s ekvivalentními konvencemi); IPS a mnoho implementačních průvodců jej předpokládá. Viz TEFCA a Národní elektronické zdravotní záznamy.

V Anpheros

Anpheros Platform používá OAuth 2.0 s PKCE pro aplikace a podepsanou JWT autentizaci klienta pro backendy, s rozsahy odvozenými ze souhlasu osoby a kontextem pacienta vynuceným při každém požadavku. Vývojářské stránky dokumentují autentizaci a SMART on FHIR backend pattern pro budování na něm.

Související stránky

Zdroje

Časté otázky

Je SMART on FHIR totéž co OAuth 2.0?

Je to OAuth 2.0 a OpenID Connect s dodatky specifickými pro FHIR: objevování, spouštěcí kontext, syntaxe rozsahu a backendové služby. Jakákoli knihovna OAuth funguje; konvence SMART jsou to, co činí aplikaci přenositelnou mezi FHIR servery.

Potřebuji PKCE pro serverovou aplikaci?

Ve SMART v2 ano, pro všechny klienty používající tok autorizačního kódu. Důvěrné klienty navíc přidávají autentizaci klienta (tajný klíč nebo podepsané JWT).

Jaký je rozdíl mezi rozsahy patient/ a user/?

patient/ omezuje přístup k jednomu pacientovi ve spouštěcím kontextu; user/ uděluje přístup k tomu, co autentizovaný uživatel může vidět, napříč pacienty. Aplikace zaměřené na pacienta používají patient/; aplikace pro klinické pracovníky často používají user/ s kontextem.

Může SMART aplikace zapisovat do záznamu?

Pokud jí jsou uděleny oprávnění k vytváření nebo aktualizaci (c, u) v jejích rozsazích a server to umožňuje. Mnoho nasazení uděluje aplikacím pro pacienty pouze oprávnění ke čtení a vyhledávání a směruje zápisy prostřednictvím specifických zdrojů, jako je QuestionnaireResponse.

Anpheros Platform

Vyzkoušejte zdarma v sandboxu

První volání FHIR za 5 minut. API standardu HL7 FHIR R4 s integrovaným souhlasem pacienta: vyzkoušejte si ho v sandboxu a poté propojte svou vlastní aplikaci nebo klinický systém.

Vytvořit sandbox zdarma Spustit ukázkovou aplikaci →Startovací kód (Python) →Kolekce Postman →Přečíst návody pro vývojáře →

Zdarma · 30 syntetických pacientů · bez karty

Tento návod slouží pouze pro informační účely a nenahrazuje lékařskou radu. Ohledně rozhodnutí o svém zdraví se poraďte se svým lékařem. V naléhavém případě volejte místní tísňové číslo (v Evropě 112).

Napsal

Tým Anpheros

Anpheros vytváří zdravotní záznamy, které pacient ovládá a může sdílet s jakoukoli klinikou, na platformě HL7 FHIR R4 se sídlem v EU. Tyto průvodce vám pomohou porozumět vašemu zdraví a uspořádat si ho; nenahrazují vašeho lékaře.

O Anpheros →