SMART App Launch: kapsamlar, başlatma, PKCE açıklaması

Kısa cevap: SMART App Launch (SMART on FHIR), bir uygulamanın kullanıcı adına bir FHIR sunucusuna yetkilendirilmiş erişimi nasıl alacağını belirleyen HL7'nin spesifikasyonudur. FHIR'ye özgü kurallarla OAuth 2.0 ve OpenID Connect kullanır: .well-known/smart-configuration adresinde bir keşif belgesi; iki başlatma modu (EHR başlatma, EHR'nin uygulamayı mevcut hastanın bağlamında açması ve bağımsız başlatma, kullanıcının uygulamayı açıp bir hasta seçmesi); FHIR'ye duyarlı bir sözdiziminde kapsamlar (patient/Observation.rs, bağlamdaki hastanın Gözlemlerini okuma ve arama anlamına gelir); belirteçle birlikte döndürülen başlatma bağlamı (hangi hasta, hangi karşılaşma); ve imzalı JWT istemci kimlik doğrulaması ile sistemden sisteme erişim için arka uç hizmetleri. SMART v2 (2021 ve sonrası), PKCE'yi zorunlu hale getirdi, ayrıntılı kapsamlar ve asimetrik istemci kimlik doğrulaması ekledi ve ulusal programların gerektirdiği sürümdür.

Adım 1: Keşif

SMART Uygulama Başlatma keşfi, uygulamanın FHIR sunucusunun .well-known/smart-configuration belgesini almasıyla başlar. Bu belge, yetkilendirme ve belirteç uç noktalarını, desteklenen yetenekleri (EHR başlatma, bağımsız başlatma, genel ve gizli istemciler, OpenID Connect, hasta ve kullanıcı izinleri), desteklenen kapsamları, PKCE kod zorluk yöntemlerini ve hibe türlerini listeler, böylece uygulama kullanıcısını nereye göndereceğini bilir.

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

Uygulama, kullanıcıyı nereye göndereceğini ve sunucunun neleri desteklediğini öğrenir.

Adım 2: Başlatma

SMART Uygulama Başlatma'nın iki başlatma modu vardır. Bir EHR başlatma modunda, klinisyen uygulamayı EHR içinde açar ve bu, bir iss parametresi (FHIR sunucusu) ve mevcut hastayı ve karşılaşmayı kodlayan opak bir başlatma belirteci iletir. Bağımsız bir başlatma modunda, kullanıcı uygulamayı doğrudan açar ve yetkilendirme sunucusu onlardan bir hasta seçmesini veya onaylamasını ister.

EHR başlatma. Klinik personel, EHR içindeki uygulamaya tıklar; EHR, uygulamanın başlatma URL'sini iki parametreyle açar: iss (FHIR sunucusu) ve launch (mevcut hastayı ve karşılaşmayı kodlayan opak bir belirteç). Uygulama, launch kapsamıyla yetkilendirme isteğinde launch'ı yansıtmalıdır.

Bağımsız başlatma. Kullanıcı uygulamayı doğrudan açar; uygulama FHIR sunucusunu bilir (seçilmiş veya yapılandırılmış) ve launch/patient ile bağlam ister; yetkilendirme sunucusu kullanıcıdan bir hasta seçmesini veya onaylamasını ister.

Adım 3: PKCE ile yetkilendirme kodu

SMART yetkilendirme adımı, PKCE ile OAuth 2.0 yetkilendirme kodu akışıdır: uygulama, kapsamları, FHIR sunucusunun aud'si ve bir kod zorluğu ile kullanıcıyı yetkilendirme uç noktasına gönderir; kullanıcı kimliğini doğrular ve onaylar; uygulama, başlatma bağlamıyla birlikte gelen bir erişim belirteci için döndürülen kodu ve kod doğrulayıcısını değiştirir.

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

Kullanıcı kimliğini doğrular (hastanenin kimlik sağlayıcısıyla) ve kapsamları onaylar; sunucu bir code ile geri yönlendirir; uygulama bunu değiştirir:

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

Başlatma bağlamı (patient, encounter, fhirUser) belirteçle birlikte gelir. Genel istemciler (mobil ve tarayıcı uygulamaları) PKCE ve istemci gizli anahtarı kullanmaz; gizli istemciler bir gizli anahtarla veya tercihen asimetrik yöntem altında imzalı bir JWT (private_key_jwt) ile kimlik doğrulaması yapar.

Kapsamlar

SMART on FHIR v2 kapsamları bağlam/kaynak.izinler sözdizimini kullanır; burada bağlam hasta, kullanıcı veya sistemdir ve izinler oluşturma, okuma, güncelleme, silme ve arama için c, r, u, d ve s'yi birleştirir, örneğin patient/Observation.rs. Ayrıntılı kapsamlar bir filtre ekler, openid ve fhirUser kullanıcının kimliğini verir, başlatma kapsamları bağlam ister ve offline_access bir yenileme belirteci ister.

SMART v2 sözdizimi: <bağlam>/<kaynak>.<izinler> burada bağlam patient (bağlamdaki hasta), user (kullanıcının görebileceği her şey) veya system (arka uç) ve izinler sırasıyla c oluşturma, r okuma, u güncelleme, d silme, s arama herhangi biridir: patient/Observation.rs, user/Patient.rs, system/*.cruds. Ayrıntılı kapsamlar bir filtre ekler: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser bir kimlik belirteci ve kullanıcının FHIR kimliğini verir; launch, launch/patient, launch/encounter bağlam ister; offline_access kullanıcının uzakta olduğu zamanlar için bir yenileme belirteci, online_access yalnızca oturum sırasında geçerli olan bir belirteç. v1 sözdizimi (patient/Observation.read) hala birçok sunucu tarafından kabul edilmektedir.

Arka uç hizmetleri

Bir kullanıcısı olmayan bir sistem (gecelik dışa aktarma, bir entegrasyon motoru) için SMART Arka Uç Hizmetleri, imzalı bir JWT iddiası (istemcinin genel anahtarları bir JWKS URL'sinde yayınlanır) ile client_credentials ve system/ kapsamlarını kullanır. Kullanıcı yok, başlatma bağlamı yok, katı kayıt.

Güvenli çalıştırma

SMART Uygulama Başlatma'yı güvenli bir şekilde çalıştırmak, tam yönlendirme URI'lerini kaydetmek, asla örtük akışı kullanmamak, yenileme belirteçlerini güvenli bir şekilde saklamak ve döndürmek, kimlik belirteçlerinin durumunu ve aud'sini doğrulamak, her API çağrısında belirteçleri doğrulamak, veri katmanında hem kapsamları hem de hasta bağlamını zorlamak, böylece bir hasta için olan bir belirtecin asla başka bir hastayı okumamasını sağlamak ve her erişimi günlüğe kaydetmek anlamına gelir.

Kesin yönlendirme URI'leri kaydedin; asla örtük akışı kullanmayın; yenileme belirteçlerini güvenli bir şekilde saklayın ve döndürün; state doğrulayın; kimlik belirteçlerinin aud alanını kontrol edin; her API çağrısında belirteçleri doğrulayın (yoklama veya JWT doğrulama) ve veri katmanında kapsamları ve hasta bağlamını zorunlu kılın, çünkü Patient/123 için bir belirteç asla Patient/124'ü okumamalıdır; her erişimi günlüğe kaydedin (Güvenlik ve kimlik: harita). SMART ayrıca, uygulamaların kullanıcılara hangi kuruluşlara bağlanabileceklerini göstermeleri için bir yol olan Hasta Erişim Markaları tanımlar ve hasta tarafından başlatılan paylaşım için SMART Health Links ile birlikte çalışır.

Nerede gereklidir

ABD hasta erişim kuralları, sertifikalı EHR'lerin SMART App Launch ve Backend Services'i desteklemesini gerektirir; Avrupa'daki ulusal programlar uygulama erişimi için bunu benimser (Hollanda'nın MedMij'i eşdeğer kurallarla OAuth 2.0 kullanır); IPS ve birçok uygulama kılavuzu bunu varsayar. TEFCA ve Ulusal elektronik sağlık kayıtları bölümüne bakın.

Anpheros'ta

Anpheros Platform, uygulamalar için PKCE ve arka uçlar için imzalı JWT istemci kimlik doğrulaması kullanan OAuth 2.0'ı kullanır; kapsamlar kişinin onayından türetilir ve hasta bağlamı her istekte zorlanır. Geliştirici sitesi, üzerinde oluşturmak için kimlik doğrulama ve SMART on FHIR arka uç deseni belgelerini içerir.

İlgili sayfalar

Kaynaklar

Sık sorulan sorular

SMART on FHIR, OAuth 2.0 ile aynı mı?

FHIR'ye özgü eklemelerle (keşif, başlatma bağlamı, kapsam sözdizimi ve arka uç hizmetleri) OAuth 2.0 ve OpenID Connect'tir. Herhangi bir OAuth kütüphanesi işe yarar; SMART kuralları, bir uygulamayı FHIR sunucuları arasında taşınabilir hale getiren şeydir.

Sunucu tarafı bir uygulama için PKCE'ye ihtiyacım var mı?

SMART v2'de, yetkilendirme kodu akışını kullanan tüm istemciler için evet. Gizli istemciler üzerine istemci kimlik doğrulaması (bir gizli anahtar veya imzalı bir JWT) ekler.

patient/ ve user/ kapsamları arasındaki fark nedir?

patient/ erişimi başlatma bağlamındaki tek hastayla sınırlar; user/ kimliği doğrulanmış kullanıcının hastalar arasında görebileceği her şeye izin verir. Hasta odaklı uygulamalar patient/ kullanır; klinik uygulamalar genellikle bağlamla user/ kullanır.

Bir SMART uygulaması kayda yazabilir mi?

Kapsamlarında oluşturma veya güncelleme izinleri (c, u) verilmişse ve sunucu buna izin veriyorsa. Birçok dağıtım, hasta uygulamalarına yalnızca okuma ve arama izni verir ve yazmaları QuestionnaireResponse gibi belirli kaynaklar aracılığıyla yönlendirir.

Anpheros Platform

Sandbox'ta ücretsiz deneyin

İlk FHIR çağrınız 5 dakikada. Hasta izniyle yerleşik HL7 FHIR R4 API: sandbox'ta deneyin, ardından kendi uygulamanızı veya klinik sisteminizi bağlayın.

Ücretsiz sandbox oluşturun Örnek uygulamayı başlat →Başlangıç kodu (Python) →Postman koleksiyonu →Geliştirici kılavuzlarını okuyun →

Ücretsiz · 30 sentetik hasta · kart gerekmez

Bu rehber bilgilendirme amaçlıdır ve tıbbi muayenenin yerini tutmaz. Sağlığınızla ilgili kararlar için doktorunuzla konuşun. Acil bir durumda yerel acil numarasını arayın (Avrupa’da 112).

Yazan

Anpheros Ekibi

Anpheros, hasta kontrolünde olan ve herhangi bir klinik ile paylaşılabilecek, AB merkezli bir HL7 FHIR R4 platformu üzerinde tıbbi kayıtlar oluşturur. Bu rehberler, sağlığınızı anlamanıza ve düzenlemenize yardımcı olur; doktorunuzun yerini tutmaz.

Anpheros Hakkında →