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

Páciens hozzájárulás implementálása SMART on FHIR segítségével

Oktatóanyag: SMART on FHIR OAuth 2.1 és PKCE segítségével lépésről lépésre – felfedezés, app regisztráció, hozzájárulási képernyő, token csere, érvényesített scope-ok, frissítési rotáció és visszavonás – és mit implementál az Anpheros.

A SMART on FHIR az a szabványos módszer, amellyel egy alkalmazás hozzáférést kap egy személy FHIR rekordjához: OAuth 2.1 PKCE-vel a hitelesítéshez, hatókörök, amelyek pontosan meghatározzák, mit lehet olvasni vagy írni, és egy felfedezési dokumentum, amely megmondja az alkalmazásnak, hová kell mennie. Ez a tutorial a teljes folyamatot végigvezeti az Anpheros ellen, lépésről lépésre a curl segítségével: felfedezés, alkalmazás regisztrálása, a személy küldése a hozzájárulási képernyőre, a kód cseréje, az API meghívása az engedélyezett hatókörökön belül, frissítés, és mi történik, amikor a személy visszavonja a hozzáférést. Az Anpheros a SMART on FHIR backend: ez tárolja a hitelesítési szervert, a hozzájárulási képernyőt és az FHIR R4 szervert, így Önnek nem kell saját bejelentkezési vagy hozzájárulási UI-t írnia.

Miért beleegyezés, és nem csak API kulcs

Egy API kulcs az Ön által létrehozott projektekhez fér hozzá a betegekhez. Egy személy meglévő rekordja (saját adatai, amelyeket más alkalmazások, klinikák és laboratóriumok gyűjtöttek) az övé, és megosztható. A SMART on FHIR segítségével:

• a személy a saját nyelvén látja, hogy melyik alkalmazás kér, mit kíván olvasni vagy írni, milyen célból és mennyi ideig;
• az Ön alkalmazása csak azokat az erőforrás-típusokat és műveleteket kapja meg, és csak arra az egy rekordra vonatkozóan;
• minden hozzáférés naplózásra kerül, és látható a személy számára, aki bármikor visszavonhatja azt;
• az engedélyezés FHIR Consent erőforrásként is tárolódik.

A mögöttes modell a Egészségügyi API beteg beleegyezéssel és a Beleegyezés és hozzáférési modell dokumentumokban található.

1. lépés: discovery

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

A válasz felsorolja az endpointokat és azt, hogy a szerver mit támogat (rövidítve):

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

A SMART klienskönyvtárak elolvassák ezt a dokumentumot, és nincs szükségük további konfigurációra.

2. lépés: Az alkalmazás regisztrálása

A dashboard oldalon nyissa meg a projektjét, és adjon hozzá egy alkalmazást a visszairányítási URI-jával. Vagy az Admin API-n keresztül:

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

Használja a public-t mobil és böngésző alapú alkalmazásokhoz, amelyek nem tudják biztonságban tartani a titkot, és a PKCE-re támaszkodnak. Használja a confidential-t szerverekhez; annak client_secret egyszer jelenik meg. A név, a cél és az adatvédelmi link azok az információk, amelyeket a felhasználó a hozzájárulási képernyőn lát.

3. lépés: Irányítsa a személyt a hozzájárulási képernyőre

Hozzon létre egy PKCE párt. A verifier Önnel marad; csak a kivonata utazik:

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

Ezután nyissa meg ezt a címet a személy böngészőjében (sorvégi törések az olvashatóság kedvéért):

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

Kérjen annyit, amennyi feltétlenül szükséges. Ez az alkalmazás laboreredményeket és diagnózisokat olvas, semmi mást. A(z) offline_access frissítési tokent ad, így a személynek nem kell 30 percenként újra jóváhagynia.

A személy bejelentkezik az Anpherosba, elolvassa a kérést köznyelven, kiválasztja, melyik rekordot kívánja megosztani (a sajátját, egy gondozott családtagét, vagy azt, amelyet az Ön alkalmazása hozott létre számára), és mennyi ideig tart a hozzáférés, majd engedélyezi vagy megtagadja. Visszatér az Ön átirányítási URI-jához:

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

Ellenőrizze, hogy a(z) state megegyezik-e azzal az értékkel, amelyet korábban küldött, mielőtt a kódot felhasználja.

4. lépés: kód csere tokenekre

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

• A scope felsorolja, hogy mi lett megadva. Tartsa meg a tokenekkel együtt, és csak a lefedett funkciókat jelenítse meg.
• A patient az Ön alkalmazásának rekordazonosítója. Párosított: egy másik alkalmazás ugyanazt a személyt más azonosítóval látja.
• A id_token egy OpenID Connect token, amelynek fhirUser claimje megnevezi a beteg erőforrást.
• A kód egyszer használható, és csak a hozzáillő code_verifier-tal.

5. lépés: API meghívása a hatókörökön belül

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

A laboreredmények szokás szerint érkeznek vissza. Kérjen valamit a megadott engedélyen kívül esőt, például gyógyszereket:

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

Ez egy 403. A megadott engedélyen belüli keresések is szűrve vannak: a Observation.rs?category=laboratory segítségével az összes megfigyelésre irányuló keresés csak laboratóriumi eredményeket ad vissza. Bármely más páciens nem létezik erre a tokenre vonatkozóan (404). A REST nézet (/v1) és a kontext API ugyanazokat a hatóköröket alkalmazza.

6. lépés: frissítés

A hozzáférési tokenek 30 percig érvényesek. A frissítési tokenek 30 napig érvényesek, és minden használatkor elfordulnak:

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

Új hozzáférési tokent és új frissítési tokent kap. Az újat azonnal tárolja el. Egy régi frissítési token újrafelhasználása lopásnak minősül: 400 hibával meghiúsul, és az egész engedélyt visszavonja.

7. lépés: visszavonás

A személy bármikor visszavonhatja az Ön hozzáférését az Anpheros-ban, és Ön is visszavonhatja azt saját magától, például amikor az alkalmazásában leválasztják őket:

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

Ettől kezdve minden, ezzel a engedéllyel végrehajtott hívás 401 hibával válaszol. Kezelje ezt úgy, hogy megmutatja a személynek, hogy a kapcsolat véget ért, és felajánlja az újracsatlakozás lehetőségét. Iratkozzon fel a consent.revoked webhookra, hogy anélkül értesüljön erről, hogy meg kellene várnia egy sikertelen hívást.

Az SDK-kkal

A TypeScript és Dart SDK-k elvégzik a 3-6. lépéseket helyetted: OAuthFlow.authorizeUrl egy generált PKCE párral, exchange a visszahíváskor, és automatikus frissítéssel, forgatással. Teljes példák: Hogyan építsünk AI egészségügyi alkalmazást FHIR backenddel (TypeScript) és Hogyan építsünk egészségügyi alkalmazást Flutterrel (Dart).

Mit implementál az Anpheros

Az írás is ugyanúgy működik: írjon hatóköröket (patient/Observation.c, .u, .d), amelyek lehetővé teszik az alkalmazás számára, hogy létrehozzon, frissítsen vagy töröljön a rekordban. Minden írott adat az alkalmazást mint szerzőt hordozza, az idempotencia kulccsal történő újrapróbálkozások soha nem duplikálnak egy mérést, és a törlések lágyak, és megőrzik a történetet (Medical data API).

Mi hiányzik még

• EHR indítás (a kórházi rendszeren belülről indított alkalmazás indítási kontextussal).
• system/ hatókörök backend szolgáltatásokhoz; a szervezetek API kulcsokat használnak helyette.
• Tömeges adatexport ($export); $everything betegre vonatkozóan elérhető.

Ezek a többi elemmel együtt szerepelnek a Verziókezelés és elavulás részben, és a képességnyilatkozat (capability statement) mindig az irányadó forrás.

Gyakran ismételt kérdések

Mi az a SMART on FHIR?

Egy nyílt szabvány, amely az OAuth 2.0/2.1 és az OpenID Connect szabványokra épül, és meghatározza, hogyan kérjen egy alkalmazás hozzáférést egy FHIR rekordhoz, milyen hatókörök (scopes) írják le ezt a hozzáférést, és hogyan hirdeti meg a szerver az endpointjait. Bármely SMART-kompatibilis klienskönyvtár használhat bármely SMART-kompatibilis szervert.

Szükségem van PKCE-re?

Igen. Az Anpheros minden engedélyezési kódfolyamat (authorisation code flow) esetén megköveteli a PKCE-t a S256 azonosítóval, mind nyilvános, mind bizalmas kliensek esetében. Megakadályozza, hogy egy lehallgatott engedélyezési kódot bárki más felhasználjon.

Mi történik, ha a személy nemet mond?

A rendszer visszatér a megadott redirect URI-ra a error=access_denied és a state azonosítókkal, de kód nélkül. Magyarázza el, mire van szüksége a funkciónak, és engedje meg, hogy újra próbálkozzanak; az engedélyen kívüli hívások mindig 403 választ adnak.

Adhat-e szülő hozzájárulást egy gyermek számára?

Igen. A hozzájárulási képernyőn a személy kiválaszthat egy általa gondozott rekordot, például egy gyermekét, ha az a fiókjához van kapcsolva. Az engedély csak arra a rekordra vonatkozik.

Kapcsolódó

• Hitelesítés és OAuth: API kulcsok, tokenek és élettartamuk részletesen
• Egészségügyi API beteg beleegyezéssel: a beleegyezés változásai az alkalmazás tervezésében
• Beleegyezési és hozzáférési modell
• FHIR platform
• Egészségügyi alkalmazás fejlesztése

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