SMART App Launch: пояснення областей доступу, запуску, PKCE

Коротка відповідь: 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. Цей документ містить інформацію про кінцеві точки авторизації та токенів, підтримувані можливості (запуск з ЕІС, автономний запуск, публічні та конфіденційні клієнти, 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 має два режими запуску. Під час запуску з ЕІС (Електронної Історії Хвороби) лікар відкриває додаток всередині ЕІС, яка передає параметр 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 використовують синтаксис контекст/ресурс.дозволи, де контекст — це 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 надають ID-токен та ідентифікатор користувача FHIR; launch, launch/patient, launch/encounter запитують контекст; offline_access — токен оновлення для використання, коли користувача немає, online_access — дійсна лише під час сесії. Синтаксис v1 (patient/Observation.read) досі приймається багатьма серверами.

Бек-енд-сервіси

Для системи, яка діє без користувача (нічний експорт, інтеграційний механізм), SMART Backend Services використовує client_credentials з підписаним JWT-твердженням (публічні ключі клієнта, опубліковані за URL JWKS) та system/ області видимості. Без користувача, без контексту запуску, сувора реєстрація.

Безпечне використання

Безпечне використання SMART App Launch означає реєстрацію точних URI перенаправлення, ніколи не використовувати неявний потік, безпечно зберігати та періодично змінювати токени оновлення, перевіряти state та aud токенів ID, перевіряти токени під час кожного виклику API, забезпечувати дотримання як областей видимості, так і контексту пацієнта на рівні даних, щоб токен одного пацієнта ніколи не читав дані іншого, а також реєструвати кожен доступ.

Реєструйте точні URI перенаправлення; ніколи не використовуйте неявний потік; безпечно зберігайте токени оновлення та ротуйте їх; перевіряйте state; перевіряйте aud ID-токенів; перевіряйте токени під час кожного виклику API (інтроспекція або валідація JWT) та застосовуйте області видимості та контекст пацієнта на рівні даних, оскільки токен для Patient/123 ніколи не повинен читати Patient/124; реєструйте кожен доступ (Безпека та ідентифікація: карта). SMART також визначає Бренди доступу пацієнтів, спосіб для додатків показувати користувачам, до яких організацій вони можуть підключатися, та взаємодіє з SMART Health Links для обміну даними за ініціативою пацієнта.

Де це вимагається

Правила доступу пацієнтів у США вимагають від сертифікованих EHR підтримувати SMART App Launch та Backend Services; національні програми в Європі приймають це для доступу додатків (MedMij у Нідерландах використовує OAuth 2.0 з еквівалентними конвенціями); IPS та багато посібників з впровадження припускають це. Дивіться TEFCA та Національні електронні медичні записи.

В Anpheros

Anpheros Platform використовує OAuth 2.0 з PKCE для додатків та автентифікацію клієнта за допомогою підписаного JWT для бек-ендів, з областями видимості, що походять від згоди особи, та контекстом пацієнта, що застосовується до кожного запиту. Сайт для розробників документує автентифікацію та шаблон SMART on FHIR backend для розробки на його основі.

Пов'язані сторінки

Джерела

Поширені запитання

Чи 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 хвилин. API стандарту HL7 FHIR R4 з вбудованою згодою пацієнта: спробуйте в пісочниці, а потім підключіть власну програму чи клінічну систему.

Створити безкоштовну пісочницю Запустити демо-застосунок →Стартовий код (Python) →Колекція Postman →Читати посібники для розробників →

Безкоштовно · 30 синтетичних пацієнтів · без картки

Цей посібник призначений для інформаційних цілей і не замінює медичну консультацію. Для прийняття рішень щодо вашого здоров'я зверніться до лікаря. У надзвичайній ситуації телефонуйте на місцевий номер екстреної допомоги (112 у Європі).

Написано

Команда Anpheros

Anpheros створює медичну карту, яку пацієнт контролює та може ділитися з будь-якою клінікою, на платформі HL7 FHIR R4, розташованій в ЄС. Ці посібники допоможуть вам зрозуміти та організувати своє здоров'я; вони не замінюють вашого лікаря.

Про Anpheros →