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

Як реалізувати згоду пацієнта з SMART on FHIR

Q: Чи потрібен мені PKCE?

Так. Anpheros вимагає PKCE з S256 для кожного потоку коду авторизації, як для публічних, так і для конфіденційних клієнтів. Це запобігає використанню перехопленого коду авторизації будь-ким іншим.

Q: Що станеться, якщо людина відмовиться?

Вони повернуться до вашого URI перенаправлення з error=access_denied та вашим state, але без коду. Поясніть, що потрібно для цієї функції, і дозвольте їм спробувати ще раз; виклики поза межами дозволу (grant) завжди повертають 403.

Посібник: SMART on FHIR з OAuth 2.1 та PKCE крок за кроком — виявлення, реєстрація додатку, екран згоди, обмін токенами, застосування скоупів, ротація оновлення та відкликання — і що реалізує Anpheros.

SMART on FHIR — це стандартний спосіб отримання програмою дозволу особи на доступ до її запису FHIR: OAuth 2.1 з PKCE для авторизації, області дії (scopes), які точно визначають, що можна читати чи записувати, та документ виявлення (discovery document), який повідомляє програмі, куди звертатися. Цей посібник крок за кроком проводить весь процес проти Anpheros з curl: виявлення, реєстрація програми, надсилання особи на екран згоди, обмін кодом, виклик API в межах наданих областей дії, оновлення та те, що відбувається, коли особа відкликає доступ. Anpheros — це бекенд SMART on FHIR: він розміщує сервер авторизації, екран згоди та сервер FHIR R4, тому вам не потрібно створювати власний інтерфейс для входу чи згоди.

Чому згода, а не просто ключ API

Ключ API досягає пацієнтів, яких створив ваш проєкт. Існуючий запис особи (її власні дані, зібрані іншими додатками, клініками та лабораторіями) належить їй для спільного використання. За допомогою SMART on FHIR:

особа бачить своєю мовою, яка програма запитує, що вона хоче прочитати чи записати, з якою метою та як довго;
ваш додаток отримує лише ті типи ресурсів та дії, і лише для цього одного запису;
кожен доступ реєструється та видимий особі, яка може відкликати його в будь-який час;
дозвіл також зберігається як ресурс FHIR Consent.

Модель, що лежить в основі цього, описана в Healthcare API with patient consent та Consent and access model.

Крок 1: discovery

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

Відповідь містить список кінцевих точок та інформацію про те, що підтримує сервер (скорочено):

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

Клієнтські бібліотеки SMART читають цей документ і не потребують додаткових налаштувань.

Крок 2: зареєструйте вашу програму

У панелі керування відкрийте свій проєкт і додайте програму з її URI перенаправлення. Або через Admin API:

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

Використовуйте public для мобільних та браузерних програм, які не можуть зберігати секрет і покладаються на PKCE. Використовуйте confidential для сервера; його client_secret відображається один раз. Назва, призначення та посилання на політику конфіденційності — це те, що бачить користувач на екрані згоди.

Крок 3: перенаправлення користувача на екран згоди

Створіть пару PKCE. Верифікатор залишається у вас; подорожує лише його хеш:

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

Потім відкрийте цю адресу в браузері користувача (розриви рядків додано для зручності читання):

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

Запитуйте лише те, що вам потрібно. Цей додаток читає лабораторні результати та діагнози, нічого більше. offline_access надає токен оновлення, тому користувачеві не доведеться погоджуватися знову кожні 30 хвилин.

Користувач входить до Anpheros, читає запит простою мовою, обирає, яким записом поділитися (своїм власним, записом члена сім'ї, за яким він доглядає, або тим, який ваш додаток створив для нього) та на який термін надається доступ, а потім дозволяє або відмовляє. Користувач повертається до вашого URI перенаправлення:

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

Перевірте, що state відповідає значенню, яке ви надіслали раніше, перш ніж використовувати код.

Крок 4: Обмін коду на токени

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

scope перелічує те, що було надано. Зберігайте це разом з токенами та показуйте лише функції, які вони охоплюють.
patient — це ідентифікатор запису для вашої програми. Він є парним: інша програма бачить ту саму особу під іншим ідентифікатором.
id_token — це токен OpenID Connect, де fhirUser claim називає ресурс пацієнта.
Код працює один раз і тільки з відповідним code_verifier.

Крок 5: виклик API в межах областей дозволів

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

Результати лабораторних досліджень надходять як зазвичай. Запит на щось поза межами дозволу, наприклад, ліки:

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

Це 403. Пошуки в межах дозволу також фільтруються: з Observation.rs?category=laboratory, пошук усіх спостережень повертає лише лабораторні. Будь-який інший пацієнт не існує для цього токена (404). REST-представлення (/v1) та context API застосовують ті самі області дозволів.

Крок 6: Оновлення

Токени доступу діють 30 хвилин. Токени оновлення діють 30 днів і обертаються при кожному використанні:

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

Ви отримуєте новий токен доступу та новий токен оновлення. Збережіть новий відразу. Повторне використання старого токена оновлення розглядається як крадіжка: це призведе до помилки 400 та відкликання всього гранту.

Крок 7: відкликання

Користувач може будь-коли відкликати ваш доступ з Anpheros, і ви також можете відкликати його самостійно, наприклад, коли користувач відключається у вашому додатку:

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

З цього моменту кожен виклик з цим дозволом повертатиме 401. Обробляйте це, показуючи користувачеві, що з'єднання розірвано, та пропонуючи підключитися знову. Підпишіться на вебхук consent.revoked, щоб дізнатися про це, не чекаючи невдалого виклику.

За допомогою SDK

TypeScript та Dart SDK виконують кроки з 3 по 6 за вас: OAuthFlow.authorizeUrl з згенерованою парою PKCE, exchange при зворотньому виклику та автоматичне оновлення з ротацією. Повні приклади: Як створити додаток для медичної допомоги зі штучним інтелектом та бекендом FHIR (TypeScript) та Як створити додаток для медичної допомоги з Flutter (Dart).

Що реалізує Anpheros

Частина SMART	В Anpheros
Discovery	`/.well-known/smart-configuration` на базі FHIR, з підтримуваними кінцевими точками, областями дії (scopes) та методами PKCE
Launch	автономний запуск (додаток запускається, потім запитує доступ); запуск з EHR з клінічної системи не пропонується
Authorisation	OAuth 2.1 з обов'язковим PKCE, потік коду авторизації
Scopes	пацієнтські області дії SMART v2, `patient/<Resource>.<cruds>` з фільтрами за категоріями, а також `openid` та `fhirUser`
Identity	OpenID Connect `id_token`, що називає пацієнта як ресурс FHIR
Consent	розміщений екран згоди мовою пацієнта, з тривалістю, обраною пацієнтом, що відображається як FHIR `Consent`
Tokens	токени доступу на 30 хвилин, ротовані токени оновлення на 30 днів, прив'язані до згоди, відкликання
Conformance	заява про можливості оголошує службу безпеки SMART; група "Standalone Launch" набору тестів Inferno SMART App Launch STU2 проходить 22 з 22 тестів (запуск від 28 вересня 2026 року); інші групи та набори тестів Inferno не запускалися

Запис працює так само: запишіть області дії (patient/Observation.c, .u, .d), дозволяючи вашому додатку створювати, оновлювати або видаляти записи. Усе, що записується, несе ваш додаток як автора, повторні спроби з ключем ідемпотентності ніколи не дублюють вимірювання, а видалення є м'якими та зберігають історію (Medical data API).

Чого ще немає

Запуск EHR (додаток, відкритий зсередини лікарняної системи з контекстом запуску).
system/ скоупів для бекенд-сервісів; організації використовують API ключі натомість.
Експорт масових даних ($export); експорт $everything для пацієнта доступний.

Це перелічено разом з іншим у розділі Версіонування та застарівання, а заява про можливості (capability statement) завжди є авторитетним джерелом.

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

Що таке SMART on FHIR?

Відкритий стандарт, побудований на базі OAuth 2.0/2.1 та OpenID Connect, який визначає, як додаток запитує доступ до запису FHIR, які області (scopes) описують цей доступ, і як сервер рекламує свої кінцеві точки (endpoints). Будь-яка клієнтська бібліотека, сумісна з SMART, може використовувати будь-який сервер, сумісний з SMART.

Чи потрібен мені PKCE?

Так. Anpheros вимагає PKCE з S256 для кожного потоку коду авторизації, як для публічних, так і для конфіденційних клієнтів. Це запобігає використанню перехопленого коду авторизації будь-ким іншим.

Що станеться, якщо людина відмовиться?

Вони повернуться до вашого URI перенаправлення з error=access_denied та вашим state, але без коду. Поясніть, що потрібно для цієї функції, і дозвольте їм спробувати ще раз; виклики поза межами дозволу (grant) завжди повертають 403.

Чи може батько надати згоду для дитини?

Так. На екрані згоди людина може вибрати запис, який її цікавить, наприклад, запис дитини, якщо він пов'язаний з її обліковим записом. Дозвіл (grant) застосовується лише до цього запису.

Пов'язані теми

Автентифікація та OAuth: ключі API, токени та терміни їх дії детально
API для охорони здоров'я з дозволом пацієнта: як зміни дозволів впливають на дизайн вашого застосунку
Модель дозволів та доступу
Платформа FHIR
Створення застосунку для охорони здоров'я

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