Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

Jak implementovat souhlas pacienta s SMART on FHIR

Návod: SMART on FHIR s OAuth 2.1 a PKCE krok za krokem — zjišťování, registrace aplikace, obrazovka souhlasu, výměna tokenů, vynucené rozsahy, rotace obnovení a odvolání — a co Anpheros implementuje.

SMART on FHIR je standardní způsob, jak aplikace získá souhlas osoby s přístupem k jejímu FHIR záznamu: OAuth 2.1 s PKCE pro autorizaci, rozsahy (scopes), které přesně říkají, co lze číst nebo zapisovat, a dokument pro zjišťování (discovery document), který aplikaci sdělí, kam má jít. Tento tutoriál provede celý tok proti Anpheros krok za krokem s curl: zjišťování, registrace aplikace, přesměrování osoby na obrazovku souhlasu, výměna kódu, volání API v rámci udělených rozsahů, obnovení a co se stane, když osoba odvolá přístup. Anpheros je SMART on FHIR backend: hostuje autorizační server, obrazovku souhlasu a FHIR R4 server, takže si nemusíte psát vlastní přihlašovací ani souhlasové UI.

Proč souhlas a ne jen API klíč

API klíč dosáhne na pacienty, které váš projekt vytvořil. Existující záznam osoby (její vlastní data, shromážděná jinými aplikacemi, klinikami a laboratořemi) je její a může je sdílet. S SMART on FHIR:

• osoba vidí ve svém jazyce, která aplikace žádá, co chce číst nebo zapisovat, za jakým účelem a na jak dlouho;
• vaše aplikace získá pouze ty typy zdrojů a akce, a to pouze pro tento jeden záznam;
• každý přístup je zaznamenán a viditelný pro osobu, která jej může kdykoli odvolat;
• udělení je také uloženo jako FHIR Consent zdroj.

Model za tím je popsán v Healthcare API with patient consent a Consent and access model.

Krok 1: zjištění

curl https://platform.anpheros.com/fhir/R4/.well-known/smart-configuration

Odpověď uvádí koncové body a to, co server podporuje (zkráceno):

{"issuer": "https://platform.anpheros.com",
 "authorization_endpoint": "https://platform.anpheros.com/oauth/authorize",
 "token_endpoint": "https://platform.anpheros.com/oauth/token",
 "revocation_endpoint": "https://platform.anpheros.com/oauth/revoke",
 "code_challenge_methods_supported": ["S256"],
 "scopes_supported": ["patient/*.rs", "patient/Patient.r", "patient/Observation.rs", "patient/Observation.rs?category=laboratory",
                      "patient/Observation.rs?category=vital-signs", "patient/Observation.c", "patient/Condition.rs",
                      "patient/MedicationStatement.rs", "patient/DocumentReference.rs", "patient/AllergyIntolerance.rs",
                      "offline_access", "launch/patient", "openid", "fhirUser"],
 "capabilities": ["launch-standalone", "client-public", "client-confidential-symmetric", "permission-patient",
                  "permission-offline", "context-standalone-patient", "sso-openid-connect"]}

Klientské knihovny SMART čtou tento dokument a nepotřebují nic dalšího konfigurovat.

Krok 2: Registrace vaší aplikace

V dashboardu otevřete svůj projekt a přidejte aplikaci s její redirect URI. Nebo prostřednictvím Admin API:

curl -X POST https://platform.anpheros.com/admin/projects/$PROJECT/applications \
     -H "Authorization: Bearer $FIREBASE_ID_TOKEN" -H "Content-Type: application/json" -d '{
  "name": "CardioAI", "client_type": "public",
  "redirect_uris": ["https://cardio.example/callback"],
  "purpose": "cardiology follow-up", "privacy_url": "https://cardio.example/privacy"
}'

{"id": "app_…", "name": "CardioAI", "client_type": "public", "client_id": "client_Hg6CknNkYlMgN190", "client_secret": null,
 "redirect_uris": ["https://cardio.example/callback"], "purpose": "cardiology follow-up", "status": "active", …}

Použijte public pro mobilní a prohlížečové aplikace, které nemohou uchovávat tajný klíč a spoléhají na PKCE. Použijte confidential pro server; jeho client_secret se zobrazí jednou. Název, účel a odkaz na zásady ochrany osobních údajů jsou informace, které uživatel vidí na obrazovce souhlasu.

Krok 3: přesměrování osoby na obrazovku souhlasu

Vytvořte pár PKCE. Verifikátor zůstává u vás; cestuje pouze jeho hash:

VERIFIER=$(openssl rand -base64 64 | tr -d '=+/\n' | cut -c1-64)
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')

Poté otevřete tuto adresu v prohlížeči osoby (řádkové zlomy přidané pro čitelnost):

https://platform.anpheros.com/oauth/authorize?response_type=code
  &client_id=client_Hg6CknNkYlMgN190
  &redirect_uri=https://cardio.example/callback
  &scope=openid fhirUser patient/Observation.rs?category=laboratory patient/Condition.rs offline_access
  &state=8c1e…               ← a random value you check on return
  &code_challenge=$CHALLENGE&code_challenge_method=S256
  &purpose=treatment&lang=en

Požádejte o to nejnutnější. Tato aplikace čte laboratorní výsledky a diagnózy, nic jiného. offline_access poskytuje obnovovací token, takže osoba nemusí schvalovat znovu každých 30 minut.

Osoba se přihlásí do Anpheros, přečte si požadavek v prostém jazyce, vybere, které záznamy sdílet (své vlastní, záznam člena rodiny, o který pečuje, nebo ten, který pro ně vytvořila vaše aplikace) a jak dlouho přístup trvá, a poté povolí nebo zamítne. Vrátí se na váš redirect URI:

https://cardio.example/callback?code=…&state=8c1e…

Zkontrolujte, zda state je hodnota, kterou jste odeslali před použitím kódu.

Krok 4: Výměna kódu za tokeny

curl -X POST https://platform.anpheros.com/oauth/token \
  -d grant_type=authorization_code -d client_id=client_Hg6CknNkYlMgN190 \
  -d code=$CODE -d code_verifier=$VERIFIER -d redirect_uri=https://cardio.example/callback

{"access_token": "at_…", "token_type": "Bearer", "expires_in": 1800,
 "scope": "patient/Observation.rs?category=laboratory patient/Condition.rs openid fhirUser offline_access",
 "patient": "82bfd321-6a4d-4aea-943a-a62f4d81d419", "grant_id": "grant_…",
 "id_token": "eyJ…", "refresh_token": "rt_…"}

• scope uvádí, co bylo uděleno. Ponechte jej s tokeny a zobrazte pouze funkce, které pokrývá.
• patient je ID záznamu pro vaši aplikaci. Je párové: jiná aplikace vidí stejnou osobu pod jiným ID.
• id_token je token OpenID Connect, jehož nárok fhirUser pojmenovává zdroj pacienta.
• Kód funguje jednou a pouze s odpovídajícím code_verifier.

Krok 5: Volání API v rámci rozsahů

curl "https://platform.anpheros.com/fhir/R4/Observation?patient=$PATIENT&category=laboratory" -H "Authorization: Bearer $ACCESS_TOKEN"

Výsledky laboratorních testů se vracejí jako obvykle. Požádejte o něco mimo udělená oprávnění, například léky:

curl "https://platform.anpheros.com/fhir/R4/MedicationStatement?patient=$PATIENT" -H "Authorization: Bearer $ACCESS_TOKEN"

{"resourceType": "OperationOutcome", "issue": [{"severity": "error", "code": "forbidden",
  "diagnostics": "The consent behind this token does not allow 's' on MedicationStatement."}]}

To je 403. Vyhledávání v rámci udělených oprávnění jsou také filtrována: s Observation.rs?category=laboratory, vyhledávání všech pozorování vrátí pouze laboratorní. Žádný jiný pacient pro tento token neexistuje (404). REST pohled (/v1) a kontextové API aplikují stejné rozsahy.

Krok 6: Obnovení

Přístupové tokeny platí 30 minut. Obnovovací tokeny platí 30 dní a při každém použití se rotují:

curl -X POST https://platform.anpheros.com/oauth/token \
  -d grant_type=refresh_token -d client_id=client_Hg6CknNkYlMgN190 -d refresh_token=$REFRESH_TOKEN

Získáte nový přístupový token a nový obnovovací token. Nový token si ihned uložte. Opětovné použití starého obnovovacího tokenu je považováno za krádež: selže s chybou 400 a zruší celý grant.

Krok 7: Odvolání

Osoba vám může kdykoli odvolat přístup z Anpheros a vy můžete odvolat přístup sami, například když se osoba odpojí ve vaší aplikaci:

curl -X POST https://platform.anpheros.com/oauth/revoke -d token=$REFRESH_TOKEN -d client_id=client_Hg6CknNkYlMgN190

Od tohoto okamžiku každý volání s tímto grantem odpoví 401. Zpracujte to tak, že osobě ukážete, že spojení skončilo, a nabídnete jí možnost se znovu připojit. Přihlaste se k odběru consent.revoked webhooku, abyste se o tom dozvěděli bez čekání na neúspěšné volání.

S pomocí SDK

TypeScript a Dart SDK za vás provedou kroky 3 až 6: OAuthFlow.authorizeUrl s vygenerovaným PKCE párem, exchange při zpětném volání a automatickým obnovením s rotací. Kompletní příklady: Jak vytvořit aplikaci pro zdravotnictví s umělou inteligencí a backendem FHIR (TypeScript) a Jak vytvořit aplikaci pro zdravotnictví s Flutterem (Dart).

Co Anpheros implementuje

Psaní funguje stejně: definujte scopes (patient/Observation.c, .u, .d), které vaší aplikaci umožní vytvářet, aktualizovat nebo mazat v rámci záznamu. Vše, co je zapsáno, nese vaši aplikaci jako autora, opakované pokusy s idempotency klíčem nikdy nebudou duplikovat měření a smazání jsou měkká a zachovávají historii (Medical data API).

Co ještě není k dispozici

• Spuštění z EHR (aplikace otevřená zevnitř nemocničního systému s kontextem spuštění).
• system/ scopes pro backendové služby; organizace místo toho používají API klíče.
• Export hromadných dat ($export); export pro jednoho pacienta je k dispozici ($everything).

Tyto položky jsou uvedeny spolu s ostatními v části Versioning and deprecation a capability statement je vždy autoritativním zdrojem.

Často kladené dotazy

Co je SMART on FHIR?

Otevřený standard, postavený na OAuth 2.0/2.1 a OpenID Connect, který definuje, jak aplikace žádá o přístup k záznamu FHIR, jaké rozsahy (scopes) tento přístup popisují a jak server inzeruje své koncové body. Jakákoli klientská knihovna schopná SMART může použít jakýkoli server schopný SMART.

Potřebuji PKCE?

Ano. Anpheros vyžaduje PKCE s S256 pro každý tok autorizačního kódu, a to jak pro veřejné, tak pro důvěrné klienty. Zabraňuje tomu, aby zachycený autorizační kód použil kdokoli jiný.

Co se stane, když osoba odmítne?

Osoba se vrátí na váš redirect URI s error=access_denied a vaším state, ale bez kódu. Vysvětlete, co funkce potřebuje, a nechte ji to zkusit znovu; volání mimo udělení oprávnění vždy odpoví 403.

Může rodič udělit souhlas za dítě?

Ano. Na obrazovce souhlasu může osoba vybrat záznam, na kterém jí záleží, například záznam dítěte, pokud je propojen s jejím účtem. Udělení oprávnění se vztahuje pouze na tento záznam.

Související

• Autentizace a OAuth: API klíče, tokeny a jejich životnost podrobně
• Zdravotnické API s pacientovým souhlasem: jak souhlas mění návrh vaší aplikace
• Model souhlasu a přístupu
• Platforma FHIR
• Vytvoření zdravotnické aplikace

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card