شرح SMART App Launch: النطاقات، التشغيل، PKCE

Q: ما هو الفرق بين نطاقات patient/ و user/؟

patient/ يحد الوصول إلى المريض الوحيد في سياق الإطلاق؛ user/ يمنح ما يُسمح للمستخدم المصادق عليه برؤيته، عبر المرضى. تستخدم التطبيقات التي تواجه المريض patient/ ؛ غالبًا ما تستخدم تطبيقات الأطباء user/ مع السياق.

إجابة مختصرة: SMART App Launch (SMART on FHIR) هي مواصفات HL7 لكيفية حصول التطبيق على وصول مصرح به إلى خادم FHIR نيابة عن مستخدم. إنها OAuth 2.0 و OpenID Connect مع اصطلاحات خاصة بـ FHIR: مستند اكتشاف في .well-known/smart-configuration؛ وضعان للإطلاق (إطلاق EHR، حيث يفتح EHR التطبيق في سياق المريض الحالي، و إطلاق مستقل، حيث يفتح المستخدم التطبيق ويختار مريضًا)؛ نطاقات بصيغة تفهم FHIR (patient/Observation.rs تعني قراءة والبحث عن الملاحظات للمريض في السياق)؛ سياق الإطلاق الذي يتم إرجاعه مع الرمز (أي مريض، أي لقاء)؛ و خدمات خلفية للوصول من نظام إلى نظام مع مصادقة عميل JWT موقعة. SMART v2 (من عام 2021 فصاعدًا) جعلت PKCE إلزامية، وأضافت نطاقات دقيقة ومصادقة عميل غير متماثلة، وهي النسخة التي تتطلبها البرامج الوطنية.

الخطوة 1: الاكتشاف

يبدأ اكتشاف SMART App Launch بجلب التطبيق لمستند .well-known/smart-configuration الخاص بخادم FHIR، والذي يسرد نقاط نهاية المصادقة والرمز المميز، والإمكانيات المدعومة (إطلاق EHR، إطلاق مستقل، عملاء عامون وسريون، OpenID Connect، أذونات المريض والمستخدم)، والنطاقات المدعومة، وطرق تحدي رمز PKCE، وأنواع المنح، حتى يعرف التطبيق أين يرسل المستخدم.

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

يتعلم التطبيق إلى أين يرسل المستخدم وما يدعمه الخادم.

الخطوة 2: الإطلاق

يحتوي SMART App Launch على وضعين للإطلاق. في إطلاق EHR، يفتح الطبيب التطبيق داخل EHR، والذي يمرر معلمة iss (خادم FHIR) ورمز إطلاق غير شفاف يشفّر المريض واللقاء الحاليين. في الإطلاق المستقل، يفتح المستخدم التطبيق مباشرة ويطلب منه خادم المصادقة اختيار أو تأكيد مريض.

إطلاق EHR. ينقر الطبيب على التطبيق داخل EHR؛ يفتح EHR عنوان URL للإطلاق الخاص بالتطبيق مع معلمين: iss (خادم FHIR) و launch (رمز غير شفاف يشفر المريض الحالي واللقاء). يجب على التطبيق عكس launch في طلب المصادقة الخاص به مع نطاق launch.

إطلاق مستقل. يفتح المستخدم التطبيق مباشرة؛ يعرف التطبيق خادم FHIR (المختار أو المُعد) ويطلب السياق باستخدام launch/patient؛ يطلب خادم المصادقة من المستخدم اختيار أو تأكيد مريض.

الخطوة 3: رمز المصادقة مع PKCE

خطوة المصادقة في SMART هي تدفق رمز تفويض OAuth 2.0 مع PKCE: يرسل التطبيق المستخدم إلى نقطة نهاية المصادقة مع نطاقاته، وaud لخادم FHIR، وتحدي رمز؛ يقوم المستخدم بالمصادقة والموافقة؛ يقوم التطبيق بتبادل الرمز المُعاد ومُحقّق الرمز المميز للحصول على رمز وصول يصل مع سياق الإطلاق.

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

يقوم المستخدم بالمصادقة (مع موفر هوية المستشفى) ويوافق على النطاقات؛ يعيد الخادم التوجيه مع code؛ يقوم التطبيق بتبادله:

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

يصل سياق الإطلاق (patient, encounter, fhirUser) بجانب الرمز. تستخدم العملاء العامة (تطبيقات الهاتف المحمول والمتصفح) PKCE ولا تستخدم سر العميل؛ المصادقة على العملاء السرية باستخدام سر أو، ويفضل، باستخدام JWT موقع (private_key_jwt) ضمن الطريقة غير المتماثلة.

النطاقات

تستخدم نطاقات SMART on FHIR v2 صيغة context/resource.permissions، حيث يكون السياق patient أو user أو system وتجمع الأذونات بين c و r و u و d و s لإنشاء وقراءة وتحديث وحذف والبحث، كما في patient/Observation.rs. تضيف النطاقات التفصيلية مرشحًا، ويوفر openid و fhirUser هوية المستخدم، وتطلب نطاقات الإطلاق السياق، ويطلب offline_access رمز تحديث.

صيغة SMART v2: <context>/<resource>.<permissions> حيث السياق هو patient (المريض في السياق)، user (ما يمكن للمستخدم رؤيته)، أو system (الخلفية)، والأذونات هي أي من c إنشاء، r قراءة، u تحديث، d حذف، s بحث، بهذا الترتيب: patient/Observation.rs, user/Patient.rs, system/*.cruds. النطاقات الدقيقة تضيف مرشحًا: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser يوفران رمز هوية وهوية المستخدم في FHIR؛ launch, launch/patient, launch/encounter يطلبان السياق؛ offline_access رمز تحديث للاستخدام عندما يكون المستخدم بعيدًا، online_access صالح فقط أثناء الجلسة. صيغة v1 (patient/Observation.read) لا تزال مقبولة من قبل العديد من الخوادم.

خدمات الخلفية

بالنسبة لنظام يعمل بدون مستخدم (تصدير ليلي، محرك تكامل)، تستخدم خدمات الخلفية في SMART client_credentials مع تأكيد JWT موقع (مفاتيح العميل العامة المنشورة في عنوان URL لـ JWKS) ونطاقات system/. لا يوجد مستخدم، لا يوجد سياق إطلاق، تسجيل صارم.

التشغيل بأمان

يعني تشغيل SMART App Launch بأمان تسجيل عناوين URI لإعادة التوجيه الدقيقة، وعدم استخدام التدفق الضمني أبدًا، وتخزين رموز التحديث وتدويرها بشكل آمن، والتحقق من الحالة وaud لرموز الهوية، والتحقق من الرموز المميزة في كل استدعاء لواجهة برمجة التطبيقات، وفرض كل من النطاقات وسياق المريض على طبقة البيانات حتى لا يقرأ رمز لمريض واحد مريضًا آخر، وتسجيل كل وصول.

قم بتسجيل عناوين URL لإعادة التوجيه الدقيقة؛ لا تستخدم أبدًا التدفق الضمني؛ قم بتخزين رموز التحديث بشكل آمن وقم بتدويرها؛ تحقق من state؛ تحقق من aud لرموز الهوية؛ تحقق من الرموز في كل استدعاء API (فحص أو التحقق من صحة JWT) وفرض النطاقات وسياق المريض في طبقة البيانات، لأن رمزًا لـ Patient/123 يجب ألا يقرأ أبدًا Patient/124؛ سجل كل وصول (الأمان والهوية: الخريطة). تحدد SMART أيضًا علامات وصول المريض، وهي طريقة للتطبيقات لإظهار للمستخدمين المؤسسات التي يمكنهم الاتصال بها، وتتفاعل مع روابط صحة SMART للمشاركة التي يبدأها المريض.

أين هو مطلوب

تتطلب قواعد وصول المرضى في الولايات المتحدة أن تدعم EHRs المعتمدة SMART App Launch وخدمات الخلفية؛ تتبناها البرامج الوطنية في أوروبا للوصول إلى التطبيقات (تستخدم MedMij في هولندا OAuth 2.0 مع اصطلاحات مكافئة)؛ تفترض IPS والعديد من أدلة التنفيذ ذلك. انظر TEFCA و السجلات الصحية الإلكترونية الوطنية.

في Anpheros

تستخدم منصة Anpheros Platform بروتوكول OAuth 2.0 مع PKCE للتطبيقات ومصادقة عميل JWT موقعة للخلفيات، مع نطاقات مشتقة من موافقة الشخص وسياق المريض المطبق على كل طلب. يوثق موقع المطور المصادقة و نمط الخلفية SMART on FHIR للبناء عليها.

صفحات ذات صلة

المصادر

الأسئلة الشائعة

هل SMART on FHIR هو نفسه OAuth 2.0؟

إنه OAuth 2.0 و OpenID Connect مع إضافات خاصة بـ FHIR: الاكتشاف، سياق الإطلاق، صيغة النطاق، وخدمات الخلفية. أي مكتبة OAuth تعمل؛ اصطلاحات SMART هي ما يجعل التطبيق قابلاً للنقل عبر خوادم FHIR.

هل أحتاج إلى PKCE لتطبيق يعمل من جانب الخادم؟

في SMART v2، نعم، لجميع العملاء الذين يستخدمون تدفق رمز المصادقة. يضيف العملاء السريون مصادقة العميل (سر أو JWT موقع) فوق ذلك.

ما هو الفرق بين نطاقات patient/ و user/؟

patient/ يحد الوصول إلى المريض الوحيد في سياق الإطلاق؛ user/ يمنح ما يُسمح للمستخدم المصادق عليه برؤيته، عبر المرضى. تستخدم التطبيقات التي تواجه المريض patient/؛ غالبًا ما تستخدم تطبيقات الأطباء user/ مع السياق.

هل يمكن لتطبيق SMART الكتابة في السجل؟

إذا تم منح أذونات الإنشاء أو التحديث (c, u) في نطاقاته وكان الخادم يسمح بذلك. تمنح العديد من عمليات النشر للتطبيقات الخاصة بالمرضى القراءة والبحث فقط، وتوجه عمليات الكتابة عبر موارد محددة مثل QuestionnaireResponse.

Anpheros Platform

جرّبه مجانًا في بيئة الاختبار

أول طلب FHIR خلال 5 دقائق. واجهة برمجة تطبيقات HL7 FHIR R4 مع موافقة المريض مدمجة: جربها في بيئة الاختبار، ثم اربط تطبيقك الخاص أو نظام عيادتك.

أنشئ بيئة اختبار مجانية شغّل التطبيق التجريبي →كود البداية (Python) →مجموعة Postman →اقرأ أدلة المطورين →

مجاني · 30 مريضًا اصطناعيًا · دون بطاقة

هذا الدليل هو للمعلومات فقط ولا يغني عن الاستشارة الطبية. لاتخاذ قرارات بشأن صحتك، تحدث مع طبيبك. في حالة الطوارئ، اتصل برقم الطوارئ المحلي (112 في أوروبا).

بقلم

فريق Anpheros

تبني Anpheros سجلًا طبيًا يتحكم فيه المريض ويمكن مشاركته مع أي عيادة، على منصة HL7 FHIR R4، مقرها في الاتحاد الأوروبي. تساعدك هذه الأدلة على فهم وتنظيم صحتك؛ ولا تغني عن استشارة طبيبك.

عن Anpheros →