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

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

Source: https://developers.anpheros.com/uk/guides/smart-on-fhir-backend

**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](https://developers.anpheros.com/uk/guides/healthcare-api-patient-consent) та [Consent and access model](https://developers.anpheros.com/uk/guides/consent).

## Крок 1: discovery

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

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

```json
{"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: зареєструйте вашу програму

У [панелі керування](https://platform.anpheros.com/dashboard/) відкрийте свій проєкт і додайте програму з її URI перенаправлення. Або через Admin API:

```bash
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"
}'
```

```json
{"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. Верифікатор залишається у вас; подорожує лише його хеш:

```bash
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: Обмін коду на токени

```bash
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
```

```json
{"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 в межах областей дозволів

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

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

```bash
curl "https://platform.anpheros.com/fhir/R4/MedicationStatement?patient=$PATIENT" -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{"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](https://developers.anpheros.com/uk/guides/llm-healthcare-data) застосовують ті самі області дозволів.

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

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

```bash
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, і ви також можете відкликати його самостійно, наприклад, коли користувач відключається у вашому додатку:

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

З цього моменту кожен виклик з цим дозволом повертатиме `401`. Обробляйте це, показуючи користувачеві, що з'єднання розірвано, та пропонуючи підключитися знову. Підпишіться на [вебхук](https://developers.anpheros.com/uk/guides/webhooks) `consent.revoked`, щоб дізнатися про це, не чекаючи невдалого виклику.

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

[TypeScript та Dart SDK](https://developers.anpheros.com/uk/guides/sdks) виконують кроки з 3 по 6 за вас: `OAuthFlow.authorizeUrl` з згенерованою парою PKCE, `exchange` при зворотньому виклику та автоматичне оновлення з ротацією. Повні приклади: [Як створити додаток для медичної допомоги зі штучним інтелектом та бекендом FHIR](https://developers.anpheros.com/uk/guides/build-ai-healthcare-app) (TypeScript) та [Як створити додаток для медичної допомоги з Flutter](https://developers.anpheros.com/uk/guides/healthcare-app-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](https://developers.anpheros.com/uk/guides/medical-data-api)).

## Чого ще немає

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

Це перелічено разом з іншим у розділі [Версіонування та застарівання](https://developers.anpheros.com/uk/guides/versioning), а заява про можливості (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](https://developers.anpheros.com/uk/guides/authentication): ключі API, токени та терміни їх дії детально
- [API для охорони здоров'я з дозволом пацієнта](https://developers.anpheros.com/uk/guides/healthcare-api-patient-consent): як зміни дозволів впливають на дизайн вашого застосунку
- [Модель дозволів та доступу](https://developers.anpheros.com/uk/guides/consent)
- [Платформа FHIR](https://developers.anpheros.com/uk/guides/fhir)
- [Створення застосунку для охорони здоров'я](https://developers.anpheros.com/uk/guides/build-a-healthcare-app)