SMART App Launch: zakresy, uruchomienie, PKCE

Krótka odpowiedź: SMART App Launch (SMART on FHIR) to specyfikacja HL7 określająca, w jaki sposób aplikacja uzyskuje autoryzowany dostęp do serwera FHIR w imieniu użytkownika. Jest to OAuth 2.0 i OpenID Connect z konwencjami specyficznymi dla FHIR: dokument odkrywania pod adresem .well-known/smart-configuration; dwa tryby uruchamiania (uruchomienie z poziomu EHR, gdzie EHR otwiera aplikację w kontekście bieżącego pacjenta, oraz uruchomienie samodzielne, gdzie użytkownik otwiera aplikację i wybiera pacjenta); zakresy w składni zrozumiałe dla FHIR (patient/Observation.rs oznacza odczyt i wyszukiwanie Obserwacji pacjenta w kontekście); kontekst uruchomienia zwracany wraz z tokenem (który pacjent, które spotkanie); oraz usługi backendowe do dostępu system-do-system z podpisana autentykacją klienta JWT. SMART v2 (od 2021 r.) uczynił PKCE obowiązkowym, dodał granularne zakresy i asymetryczną autentykację klienta, i jest to wersja wymagana przez programy krajowe.

Krok 1: odkrywanie

Odkrywanie SMART App Launch rozpoczyna się od pobrania przez aplikację dokumentu .well-known/smart-configuration serwera FHIR. Dokument ten zawiera listę punktów końcowych autoryzacji i tokenów, obsługiwane możliwości (uruchomienie w systemie EHR, uruchomienie samodzielne, klienci publiczni i poufni, OpenID Connect, uprawnienia pacjenta i użytkownika), obsługiwane zakresy, metody wyzwania kodu PKCE oraz typy przyznawania uprawnień. Dzięki temu aplikacja wie, dokąd skierować użytkownika.

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

Aplikacja dowiaduje się, dokąd wysłać użytkownika i co obsługuje serwer.

Krok 2: uruchomienie

SMART App Launch ma dwa tryby uruchamiania. W trybie uruchomienia w systemie EHR, lekarz otwiera aplikację wewnątrz systemu EHR, który przekazuje parametr iss (serwer FHIR) i nieprzezroczysty token uruchomienia kodujący bieżącego pacjenta i wizytę. W trybie uruchomienia samodzielnego, użytkownik otwiera aplikację bezpośrednio, a serwer autoryzacji prosi go o wybranie lub potwierdzenie pacjenta.

Uruchomienie z poziomu EHR. Lekarz klika aplikację w EHR; EHR otwiera adres URL uruchomienia aplikacji z dwoma parametrami: iss (serwer FHIR) i launch (nieprzezroczysty token, który koduje bieżącego pacjenta i spotkanie). Aplikacja musi powtórzyć launch w swoim żądaniu autoryzacji z zakresem launch.

Uruchomienie samodzielne. Użytkownik otwiera aplikację bezpośrednio; aplikacja zna serwer FHIR (wybrany lub skonfigurowany) i prosi o kontekst za pomocą launch/patient; serwer autoryzacji prosi użytkownika o wybranie lub potwierdzenie pacjenta.

Krok 3: kod autoryzacyjny z PKCE

Krok autoryzacji SMART to przepływ kodu autoryzacyjnego OAuth 2.0 z PKCE: aplikacja przekierowuje użytkownika do punktu końcowego autoryzacji wraz z jej zakresami, aud serwera FHIR i wyzwaniem kodu; użytkownik uwierzytelnia się i zatwierdza; aplikacja wymienia zwrócony kod i weryfikator kodu na token dostępu, który przychodzi wraz z kontekstem uruchomienia.

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żytkownik uwierzytelnia się (za pomocą dostawcy tożsamości szpitala) i zatwierdza zakresy; serwer przekierowuje z powrotem z code; aplikacja wymienia go:

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

Kontekst uruchomienia (patient, encounter, fhirUser) pojawia się obok tokena. Publiczne klienty (aplikacje mobilne i przeglądarkowe) używają PKCE i nie mają sekretu klienta; poufne klienty uwierzytelniają się za pomocą sekretu lub, co preferowane, za pomocą podpisanego JWT (private_key_jwt) w ramach metody asymetrycznej.

Zakresy

Zakresy SMART on FHIR v2 używają składni kontekst/zasób.uprawnienia, gdzie kontekstem jest patient, user lub system, a uprawnienia łączą c, r, u, d i s dla tworzenia, odczytu, aktualizacji, usuwania i wyszukiwania, jak w patient/Observation.rs. Granularne zakresy dodają filtr, openid i fhirUser podają tożsamość użytkownika, zakresy uruchomienia żądają kontekstu, a offline_access żąda tokenu odświeżania.

Składnia SMART v2: <kontekst>/<zasób>.<uprawnienia> gdzie kontekstem jest patient (pacjent w kontekście), user (cokolwiek użytkownik może zobaczyć) lub system (backend), a uprawnieniami są dowolne z c create (twórz), r read (czytaj), u update (aktualizuj), d delete (usuń), s search (szukaj), w tej kolejności: patient/Observation.rs, user/Patient.rs, system/*.cruds. Granularne zakresy dodają filtr: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser dają token ID i tożsamość użytkownika FHIR; launch, launch/patient, launch/encounter proszą o kontekst; offline_access token odświeżający do użytku, gdy użytkownik jest nieobecny, online_access ważny tylko podczas sesji. Składnia v1 (patient/Observation.read) jest nadal akceptowana przez wiele serwerów.

Usługi backendowe

Dla systemu działającego bez użytkownika (nocny eksport, silnik integracyjny), SMART Backend Services używa client_credentials z podpisana asercją JWT (publiczne klucze klienta opublikowane pod adresem URL JWKS) i zakresami system/. Brak użytkownika, brak kontekstu uruchomienia, ścisła rejestracja.

Bezpieczne uruchamianie

Bezpieczne uruchamianie SMART App Launch oznacza rejestrowanie dokładnych adresów URI przekierowania, nigdy niekorzystanie z przepływu niejawnego, bezpieczne przechowywanie i rotację tokenów odświeżania, walidację stanu i aud tokenów ID, weryfikację tokenów przy każdym wywołaniu API, egzekwowanie zarówno zakresów, jak i kontekstu pacjenta na poziomie danych, aby token dla jednego pacjenta nigdy nie odczytywał danych innego, oraz logowanie każdego dostępu.

Rejestruj dokładne adresy URI przekierowania; nigdy nie używaj przepływu niejawnego; bezpiecznie przechowuj tokeny odświeżające i rotuj je; waliduj state; sprawdzaj aud tokenów ID; weryfikuj tokeny przy każdym wywołaniu API (introspekcja lub walidacja JWT) i egzekwuj zakresy oraz kontekst pacjenta na poziomie danych, ponieważ token dla Patient/123 nigdy nie powinien odczytywać Patient/124; loguj każdy dostęp (Bezpieczeństwo i tożsamość: mapa). SMART definiuje również Marki Dostępu do Pacjenta, sposób, w jaki aplikacje mogą pokazywać użytkownikom, z którymi organizacjami mogą się połączyć, i współpracuje z SMART Health Links w celu udostępniania zainicjowanego przez pacjenta.

Gdzie jest wymagane

Amerykańskie przepisy dotyczące dostępu pacjentów wymagają od certyfikowanych EHR obsługi SMART App Launch i Backend Services; programy krajowe w Europie przyjmują je do dostępu aplikacji (holenderski MedMij używa OAuth 2.0 z równoważnymi konwencjami); IPS i wiele przewodników implementacyjnych zakłada ich użycie. Zobacz TEFCA i Krajowe elektroniczne rekordy medyczne.

W Anpheros

Anpheros Platform używa OAuth 2.0 z PKCE dla aplikacji i uwierzytelniania klienta JWT podpisanego dla backendów, z zakresami pochodzącymi z zgody osoby i kontekstem pacjenta egzekwowanym przy każdym żądaniu. Witryna dla deweloperów dokumentuje uwierzytelnianie i wzorzec backendu SMART on FHIR do budowania na jego podstawie.

Powiązane strony

Źródła

Najczęstsze pytania

Czy SMART on FHIR to to samo co OAuth 2.0?

To jest OAuth 2.0 i OpenID Connect z dodatkami specyficznymi dla FHIR: odkrywanie, kontekst uruchomienia, składnia zakresów i usługi backendowe. Działa każda biblioteka OAuth; konwencje SMART sprawiają, że aplikacja jest przenośna między serwerami FHIR.

Czy potrzebuję PKCE dla aplikacji po stronie serwera?

W SMART v2 tak, dla wszystkich klientów korzystających z przepływu kodu autoryzacyjnego. Poufne klienty dodają uwierzytelnianie klienta (sekret lub podpisany JWT) na wierzchu.

Jaka jest różnica między zakresami patient/ a user/?

patient/ ogranicza dostęp do pojedynczego pacjenta w kontekście uruchomienia; user/ przyznaje dostęp do tego, co uwierzytelniony użytkownik może zobaczyć, niezależnie od pacjenta. Aplikacje skierowane do pacjentów używają patient/; aplikacje klinicystów często używają user/ z kontekstem.

Czy aplikacja SMART może zapisywać w rekordzie?

Jeśli otrzyma uprawnienia do tworzenia lub aktualizacji (c, u) w swoich zakresach, a serwer na to zezwala. Wiele wdrożeń przyznaje aplikacjom pacjentów tylko odczyt i wyszukiwanie, a zapisy kieruje przez określone zasoby, takie jak QuestionnaireResponse.

Anpheros Platform

Wypróbuj za darmo w sandboksie

Pierwsze wywołanie FHIR w 5 minut. API HL7 FHIR R4 z wbudowaną zgodą pacjenta: wypróbuj w piaskownicy, a następnie połącz własną aplikację lub system kliniczny.

Utwórz darmowy sandbox Uruchom przykładową aplikację →Kod startowy (Python) →Kolekcja Postman →Przeczytaj przewodniki dla programistów →

Za darmo · 30 syntetycznych pacjentów · bez karty

Ten poradnik ma charakter informacyjny i nie zastępuje konsultacji lekarskiej. Decyzje dotyczące zdrowia podejmuj z lekarzem. W nagłym wypadku zadzwoń pod lokalny numer alarmowy (112 w Europie).

Napisane przez

Zespół Anpheros

Anpheros tworzy dokumentację medyczną, nad którą pacjent ma kontrolę i którą może udostępniać dowolnej klinice, na platformie HL7 FHIR R4, z siedzibą w UE. Te przewodniki pomogą Ci zrozumieć i uporządkować informacje o Twoim zdrowiu; nie zastępują one wizyty u lekarza.

O Anpheros →