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

Ako implementovať súhlas pacienta pomocou SMART on FHIR

Návod: SMART on FHIR s OAuth 2.1 a PKCE krok za krokom — objavovanie, registrácia aplikácie, obrazovka súhlasu, výmena tokenov, vynútené scopes, rotácia obnovenia a odvolanie — a čo Anpheros implementuje.

SMART on FHIR je štandardný spôsob, ako aplikácia získa povolenie osoby na prístup k jej FHIR záznamu: OAuth 2.1 s PKCE pre autorizáciu, rozsahy (scopes), ktoré presne hovoria, čo sa môže čítať alebo zapisovať, a dokument na zistenie (discovery document), ktorý aplikácii povie, kam má ísť. Tento tutoriál prebehne celý proces proti Anpheros, krok za krokom s curl: zistenie, registrácia aplikácie, presmerovanie osoby na obrazovku súhlasu, výmena kódu, volanie API v rámci udelených rozsahov, obnovenie a čo sa stane, keď osoba odvolá prístup. Anpheros je SMART on FHIR backend: hostuje autorizačný server, obrazovku súhlasu a FHIR R4 server, takže nemusíte písať vlastné prihlasovacie alebo súhlasové UI.

Prečo súhlas a nie len API kľúč

API kľúč dosiahne pacientov, ktorých váš projekt vytvoril. Existujúci záznam osoby (jej vlastné údaje, zhromaždené inými aplikáciami, klinikami a laboratóriami) je jej na zdieľanie. So SMART on FHIR:

• osoba vidí vo svojom jazyku, ktorá aplikácia žiada, čo chce čítať alebo zapisovať, na aký účel a na ako dlho;
• vaša aplikácia získa iba tie typy zdrojov a akcie, a to len pre tento jeden záznam;
• každý prístup je zaznamenaný a viditeľný pre osobu, ktorá ho môže kedykoľvek odvolať;
• povolenie je tiež uložené ako FHIR Consent zdroj.

Model za tým je opísaný v Healthcare API with patient consent a Consent and access model.

Krok 1: objavovanie

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

Odpoveď uvádza koncové body a to, čo server podporuje (skrátené):

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

Klientske knižnice SMART čítajú tento dokument a nepotrebujú žiadne ďalšie nastavenia.

Krok 2: registrácia vašej aplikácie

V dashboarde otvorte svoj projekt a pridajte aplikáciu s jej redirect URI. Alebo cez 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žite public pre mobilné a prehliadačové aplikácie, ktoré nemôžu uchovávať tajný kľúč a spoliehajú sa na PKCE. Použite confidential pre server; jeho client_secret sa zobrazí raz. Názov, účel a odkaz na ochranu osobných údajov sú informácie, ktoré osoba vidí na obrazovke súhlasu.

Krok 3: presmerujte osobu na obrazovku súhlasu

Vytvorte pár PKCE. Verifikátor zostáva u vás; cestuje iba 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 '=')

Potom otvorte túto adresu v prehliadači osoby (zlomy riadkov pridané pre čitateľnosť):

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žiadajte o minimum, ktoré potrebujete. Táto aplikácia číta laboratórne výsledky a diagnózy, nič iné. offline_access poskytuje obnovovací token, takže osoba nemusí schvaľovať znova každých 30 minút.

Osoba sa prihlási do Anpheros, prečíta si žiadosť v zrozumiteľnom jazyku, vyberie, ktorý záznam zdieľať (svoj vlastný, záznam člena rodiny, o ktorého sa stará, alebo ten, ktorý pre ňu vytvorila vaša aplikácia) a ako dlho prístup trvá, potom povolí alebo zamietne. Vráti sa na váš redirect URI:

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

Skontrolujte, či state je hodnota, ktorú ste poslali predtým, ako použijete kód.

Krok 4: výmena 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ádza, čo bolo udelené. Ponechajte ho s tokenmi a zobrazte iba funkcie, ktoré pokrýva.
• patient je ID záznamu pre vašu aplikáciu. Je párové: iná aplikácia vidí tú istú osobu pod iným ID.
• id_token je token OpenID Connect, ktorého nárok fhirUser pomenúva zdroj pacienta.
• Kód funguje raz a iba s zodpovedajúcim code_verifier.

Krok 5: Volanie API v rámci scopes

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

Výsledky laboratórnych testov sa vracajú ako obvykle. Požiadajte o niečo mimo povolenia, napríklad lieky:

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. Vyhľadávania v rámci povolenia sú tiež filtrované: s Observation.rs?category=laboratory, vyhľadávanie všetkých pozorovaní vráti iba laboratórne. Žiadny iný pacient pre tento token neexistuje (404). REST pohľad (/v1) a context API aplikujú rovnaké scopes.

Krok 6: Obnovenie

Prístupové tokeny platia 30 minút. Obnovovacie tokeny platia 30 dní a pri každom použití sa 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ískate nový prístupový token a nový obnovovací token. Nový token si ihneď uložte. Opätovné použitie starého obnovovacieho tokenu sa považuje za krádež: zlyhá s chybou 400 a zruší celý grant.

Krok 7: odvolanie

Osoba vám môže kedykoľvek odvolať prístup z Anpheros a vy si ho môžete odvolať sami, napríklad keď sa v vašej aplikácii odpojí:

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

Odo vtedy každý hovor s týmto grantom odpovie 401. Riešte to tak, že osobe ukážete, že spojenie skončilo, a ponúknete jej možnosť opätovného pripojenia. Prihláste sa na odber consent.revoked webhooku, aby ste to zistili bez čakania na neúspešný hovor.

Súpravami SDK

TypeScript a Dart SDK vykonajú kroky 3 až 6 za vás: OAuthFlow.authorizeUrl s vygenerovaným párom PKCE, exchange pri spätnom volaní a automatickým obnovením s rotáciou. Úplné príklady: Ako vytvoriť AI zdravotnícku aplikáciu s FHIR backendom (TypeScript) a Ako vytvoriť zdravotnícku aplikáciu s Flutterom (Dart).

Čo Anpheros implementuje

Písanie funguje rovnako: zápis scopes (patient/Observation.c, .u, .d) umožňuje vašej aplikácii vytvárať, aktualizovať alebo mazať v rámci záznamu. Všetko zapísané nesie vašu aplikáciu ako autora, opätovné pokusy s idempotency kľúčom nikdy neduplujú meranie a mazanie je mäkké a zachováva históriu (Medical data API).

Čo ešte nie je k dispozícii

• Spustenie z EHR (aplikácia spustená z nemocničného systému s kontextom spustenia).
• system/ scopes pre backendové služby; organizácie namiesto toho používajú API kľúče.
• Export hromadných dát ($export); export pre jedného pacienta ($everything) je k dispozícii.

Tieto položky sú uvedené spolu s ostatnými v časti Versioning and deprecation a capability statement je vždy autoritatívnym zdrojom.

Často kladené otázky

Čo je SMART on FHIR?

Otvorený štandard, postavený na OAuth 2.0/2.1 a OpenID Connect, ktorý definuje, ako aplikácia žiada o prístup k FHIR záznamu, aké rozsahy (scopes) tento prístup popisujú a ako server oznamuje svoje koncové body. Akákoľvek klientska knižnica s podporou SMART môže použiť akýkoľvek server s podporou SMART.

Potrebujem PKCE?

Áno. Anpheros vyžaduje PKCE s S256 pre každý tok autorizačného kódu, a to pre verejné aj dôverné klientov. Zabraňuje tomu, aby bol zachytený autorizačný kód použitý niekým iným.

Čo sa stane, ak osoba povie nie?

Vrátia sa na váš redirect URI s error=access_denied a vaším state, a bez kódu. Vysvetlite, čo funkcia potrebuje, a nechajte ich skúsiť to znova; volania mimo grantu vždy odpovedajú 403.

Môže rodič udeliť súhlas za dieťa?

Áno. Na obrazovke súhlasu môže osoba vybrať záznam, o ktorý sa stará, napríklad záznam dieťaťa, ak je prepojený s jej účtom. Grant sa vzťahuje iba na tento záznam.

Súvisiace

• Autentizácia a OAuth: API kľúče, tokeny a ich životnosť podrobne
• Zdravotnícke API so súhlasom pacienta: ako súhlas mení dizajn vašej aplikácie
• Model súhlasu a prístupu
• FHIR platforma
• Vytvorenie zdravotníckej aplikácie

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