# Jak implementovat souhlas pacienta s SMART on FHIR

> Tutoriál: SMART on FHIR s OAuth 2.1 a PKCE krok za krokem — zjišťování, registrace aplikace, obrazovka souhlasu, výměna tokenu, vynucené rozsahy, rotace obnovení a odvolání — a co Anpheros implementuje.

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

**SMART on FHIR je standardní způsob, jak aplikace získá souhlas osoby s přístupem k jejímu FHIR záznamu: OAuth 2.1 s PKCE pro autorizaci, rozsahy (scopes), které přesně říkají, co lze číst nebo zapisovat, a dokument pro zjišťování (discovery document), který aplikaci sdělí, kam má jít.** Tento tutoriál provede celý tok proti Anpheros krok za krokem s `curl`: zjišťování, registrace aplikace, přesměrování osoby na obrazovku souhlasu, výměna kódu, volání API v rámci udělených rozsahů, obnovení a co se stane, když osoba odvolá přístup. Anpheros je SMART on FHIR backend: hostuje autorizační server, obrazovku souhlasu a FHIR R4 server, takže si nemusíte psát vlastní přihlašovací ani souhlasové UI.

## Proč souhlas a ne jen API klíč

API klíč dosáhne na pacienty, které váš projekt vytvořil. Existující záznam osoby (její vlastní data, shromážděná jinými aplikacemi, klinikami a laboratořemi) je její a může je sdílet. S SMART on FHIR:

- osoba vidí ve svém jazyce, která aplikace žádá, co chce číst nebo zapisovat, za jakým účelem a na jak dlouho;
- vaše aplikace získá pouze ty typy zdrojů a akce, a to pouze pro tento jeden záznam;
- každý přístup je zaznamenán a viditelný pro osobu, která jej může kdykoli odvolat;
- udělení je také uloženo jako FHIR `Consent` zdroj.

Model za tím je popsán v [Healthcare API with patient consent](https://developers.anpheros.com/cs/guides/healthcare-api-patient-consent) a [Consent and access model](https://developers.anpheros.com/cs/guides/consent).

## Krok 1: zjištění

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

Odpověď uvádí koncové body a to, co server podporuje (zkráceno):

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

Klientské knihovny SMART čtou tento dokument a nepotřebují nic dalšího konfigurovat.

## Krok 2: Registrace vaší aplikace

V [dashboardu](https://platform.anpheros.com/dashboard/) otevřete svůj projekt a přidejte aplikaci s její redirect URI. Nebo prostřednictvím 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", …}
```

Použijte `public` pro mobilní a prohlížečové aplikace, které nemohou uchovávat tajný klíč a spoléhají na PKCE. Použijte `confidential` pro server; jeho `client_secret` se zobrazí jednou. Název, účel a odkaz na zásady ochrany osobních údajů jsou informace, které uživatel vidí na obrazovce souhlasu.

## Krok 3: přesměrování osoby na obrazovku souhlasu

Vytvořte pár PKCE. Verifikátor zůstává u vás; cestuje pouze jeho hash:

```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 '=')
```

Poté otevřete tuto adresu v prohlížeči osoby (řádkové zlomy přidané pro čitelnost):

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

Požádejte o to nejnutnější. Tato aplikace čte laboratorní výsledky a diagnózy, nic jiného. `offline_access` poskytuje obnovovací token, takže osoba nemusí schvalovat znovu každých 30 minut.

Osoba se přihlásí do Anpheros, přečte si požadavek v prostém jazyce, vybere, které záznamy sdílet (své vlastní, záznam člena rodiny, o který pečuje, nebo ten, který pro ně vytvořila vaše aplikace) a jak dlouho přístup trvá, a poté povolí nebo zamítne. Vrátí se na váš redirect URI:

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

Zkontrolujte, zda `state` je hodnota, kterou jste odeslali před použitím kódu.

## Krok 4: Výměna kódu za tokeny

```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` uvádí, co bylo uděleno. Ponechte jej s tokeny a zobrazte pouze funkce, které pokrývá.
- `patient` je ID záznamu pro vaši aplikaci. Je párové: jiná aplikace vidí stejnou osobu pod jiným ID.
- `id_token` je token OpenID Connect, jehož nárok `fhirUser` pojmenovává zdroj pacienta.
- Kód funguje jednou a pouze s odpovídajícím `code_verifier`.

## Krok 5: Volání API v rámci rozsahů

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

Výsledky laboratorních testů se vracejí jako obvykle. Požádejte o něco mimo udělená oprávnění, například léky:

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

To je `403`. Vyhledávání v rámci udělených oprávnění jsou také filtrována: s `Observation.rs?category=laboratory`, vyhledávání všech pozorování vrátí pouze laboratorní. Žádný jiný pacient pro tento token neexistuje (`404`). REST pohled (`/v1`) a [kontextové API](https://developers.anpheros.com/cs/guides/llm-healthcare-data) aplikují stejné rozsahy.

## Krok 6: Obnovení

Přístupové tokeny platí 30 minut. Obnovovací tokeny platí 30 dní a při každém použití se rotují:

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

Získáte nový přístupový token a nový obnovovací token. Nový token si ihned uložte. Opětovné použití starého obnovovacího tokenu je považováno za krádež: selže s chybou `400` a zruší celý grant.

## Krok 7: Odvolání

Osoba vám může kdykoli odvolat přístup z Anpheros a vy můžete odvolat přístup sami, například když se osoba odpojí ve vaší aplikaci:

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

Od tohoto okamžiku každý volání s tímto grantem odpoví `401`. Zpracujte to tak, že osobě ukážete, že spojení skončilo, a nabídnete jí možnost se znovu připojit. Přihlaste se k odběru `consent.revoked` [webhooku](https://developers.anpheros.com/cs/guides/webhooks), abyste se o tom dozvěděli bez čekání na neúspěšné volání.

## S pomocí SDK

[TypeScript a Dart SDK](https://developers.anpheros.com/cs/guides/sdks) za vás provedou kroky 3 až 6: `OAuthFlow.authorizeUrl` s vygenerovaným PKCE párem, `exchange` při zpětném volání a automatickým obnovením s rotací. Kompletní příklady: [Jak vytvořit aplikaci pro zdravotnictví s umělou inteligencí a backendem FHIR](https://developers.anpheros.com/cs/guides/build-ai-healthcare-app) (TypeScript) a [Jak vytvořit aplikaci pro zdravotnictví s Flutterem](https://developers.anpheros.com/guides/healthcare-app-flutter) (Dart).

## Co Anpheros implementuje

| Část SMART | V Anpheros |
|---|---|
| Discovery | `/.well-known/smart-configuration` na FHIR bázi, s podporovanými endpointy, scopes a PKCE metodami |
| Launch | standalone launch (aplikace se spustí a poté požádá o přístup); EHR launch z klinického systému není nabízen |
| Authorisation | OAuth 2.1 s povinným PKCE, autorizační kód flow |
| Scopes | SMART v2 patient scopes, `patient/<Resource>.<cruds>` s filtry kategorií, plus `openid` a `fhirUser` |
| Identity | OpenID Connect `id_token` pojmenovávající pacienta jako FHIR resource |
| Consent | hostovaná obrazovka souhlasu v jazyce pacienta, s dobou trvání zvolenou pacientem, zrcadlená jako FHIR `Consent` |
| Tokens | 30minutové access tokeny, rotující 30denní refresh tokeny vázané na souhlas, revokace |
| Conformance | capability statement deklaruje SMART security service; skupina "Standalone Launch" testovací sady Inferno SMART App Launch STU2 prochází 22 z 22 testů (běh z 28. září 2026); ostatní skupiny a testovací sady Inferno nebyly spuštěny |

Psaní funguje stejně: definujte scopes (`patient/Observation.c`, `.u`, `.d`), které vaší aplikaci umožní vytvářet, aktualizovat nebo mazat v rámci záznamu. Vše, co je zapsáno, nese vaši aplikaci jako autora, opakované pokusy s idempotency klíčem nikdy nebudou duplikovat měření a smazání jsou měkká a zachovávají historii ([Medical data API](https://developers.anpheros.com/cs/guides/medical-data-api)).

## Co ještě není k dispozici

- Spuštění z EHR (aplikace otevřená zevnitř nemocničního systému s kontextem spuštění).
- `system/` scopes pro backendové služby; organizace místo toho používají API klíče.
- Export hromadných dat (`$export`); export pro jednoho pacienta je k dispozici (`$everything`).

Tyto položky jsou uvedeny spolu s ostatními v části [Versioning and deprecation](https://developers.anpheros.com/cs/guides/versioning) a capability statement je vždy autoritativním zdrojem.

## Často kladené dotazy

### Co je SMART on FHIR?
Otevřený standard, postavený na OAuth 2.0/2.1 a OpenID Connect, který definuje, jak aplikace žádá o přístup k záznamu FHIR, jaké rozsahy (scopes) tento přístup popisují a jak server inzeruje své koncové body. Jakákoli klientská knihovna schopná SMART může použít jakýkoli server schopný SMART.

### Potřebuji PKCE?
Ano. Anpheros vyžaduje PKCE s `S256` pro každý tok autorizačního kódu, a to jak pro veřejné, tak pro důvěrné klienty. Zabraňuje tomu, aby zachycený autorizační kód použil kdokoli jiný.

### Co se stane, když osoba odmítne?
Osoba se vrátí na váš redirect URI s `error=access_denied` a vaším `state`, ale bez kódu. Vysvětlete, co funkce potřebuje, a nechte ji to zkusit znovu; volání mimo udělení oprávnění vždy odpoví `403`.

### Může rodič udělit souhlas za dítě?
Ano. Na obrazovce souhlasu může osoba vybrat záznam, na kterém jí záleží, například záznam dítěte, pokud je propojen s jejím účtem. Udělení oprávnění se vztahuje pouze na tento záznam.

## Související

- [Autentizace a OAuth](https://developers.anpheros.com/cs/guides/authentication): API klíče, tokeny a jejich životnost podrobně
- [Zdravotnické API s pacientovým souhlasem](https://developers.anpheros.com/cs/guides/healthcare-api-patient-consent): jak souhlas mění návrh vaší aplikace
- [Model souhlasu a přístupu](https://developers.anpheros.com/cs/guides/consent)
- [Platforma FHIR](https://developers.anpheros.com/cs/guides/fhir)
- [Vytvoření zdravotnické aplikace](https://developers.anpheros.com/cs/guides/build-a-healthcare-app)