# Ako implementovať súhlas pacienta pomocou SMART on FHIR

> Tutoriál: SMART on FHIR s OAuth 2.1 a PKCE krok za krokom — zistenie, registrácia aplikácie, obrazovka súhlasu, výmena tokenov, vynútené rozsahy, rotácia obnovenia a odvolanie — a čo implementuje Anpheros.

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

**SMART on FHIR je štandardný spôsob, ako aplikácia získa povolenie osoby na prístup k jej FHIR záznamu: OAuth 2.1 s PKCE pre autorizáciu, rozsahy (scopes), ktoré presne hovoria, čo sa môže čítať alebo zapisovať, a dokument na zistenie (discovery document), ktorý aplikácii povie, kam má ísť.** Tento tutoriál prebehne celý proces proti Anpheros, krok za krokom s `curl`: zistenie, registrácia aplikácie, presmerovanie osoby na obrazovku súhlasu, výmena kódu, volanie API v rámci udelených rozsahov, obnovenie a čo sa stane, keď osoba odvolá prístup. Anpheros je SMART on FHIR backend: hostuje autorizačný server, obrazovku súhlasu a FHIR R4 server, takže nemusíte písať vlastné prihlasovacie alebo súhlasové UI.

## Prečo súhlas a nie len API kľúč

API kľúč dosiahne pacientov, ktorých váš projekt vytvoril. Existujúci záznam osoby (jej vlastné údaje, zhromaždené inými aplikáciami, klinikami a laboratóriami) je jej na zdieľanie. So SMART on FHIR:

- osoba vidí vo svojom jazyku, ktorá aplikácia žiada, čo chce čítať alebo zapisovať, na aký účel a na ako dlho;
- vaša aplikácia získa iba tie typy zdrojov a akcie, a to len pre tento jeden záznam;
- každý prístup je zaznamenaný a viditeľný pre osobu, ktorá ho môže kedykoľvek odvolať;
- povolenie je tiež uložené ako FHIR `Consent` zdroj.

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

## Krok 1: objavovanie

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

Odpoveď uvádza koncové body a to, čo server podporuje (skrátené):

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

Klientske knižnice SMART čítajú tento dokument a nepotrebujú žiadne ďalšie nastavenia.

## Krok 2: registrácia vašej aplikácie

V [dashboarde](https://platform.anpheros.com/dashboard/) otvorte svoj projekt a pridajte aplikáciu s jej redirect URI. Alebo cez 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žite `public` pre mobilné a prehliadačové aplikácie, ktoré nemôžu uchovávať tajný kľúč a spoliehajú sa na PKCE. Použite `confidential` pre server; jeho `client_secret` sa zobrazí raz. Názov, účel a odkaz na ochranu osobných údajov sú informácie, ktoré osoba vidí na obrazovke súhlasu.

## Krok 3: presmerujte osobu na obrazovku súhlasu

Vytvorte pár PKCE. Verifikátor zostáva u vás; cestuje iba 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 '=')
```

Potom otvorte túto adresu v prehliadači osoby (zlomy riadkov pridané pre čitateľnosť):

```
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žiadajte o minimum, ktoré potrebujete. Táto aplikácia číta laboratórne výsledky a diagnózy, nič iné. `offline_access` poskytuje obnovovací token, takže osoba nemusí schvaľovať znova každých 30 minút.

Osoba sa prihlási do Anpheros, prečíta si žiadosť v zrozumiteľnom jazyku, vyberie, ktorý záznam zdieľať (svoj vlastný, záznam člena rodiny, o ktorého sa stará, alebo ten, ktorý pre ňu vytvorila vaša aplikácia) a ako dlho prístup trvá, potom povolí alebo zamietne. Vráti sa na váš redirect URI:

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

Skontrolujte, či `state` je hodnota, ktorú ste poslali predtým, ako použijete kód.

## Krok 4: výmena 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ádza, čo bolo udelené. Ponechajte ho s tokenmi a zobrazte iba funkcie, ktoré pokrýva.
- `patient` je ID záznamu pre vašu aplikáciu. Je párové: iná aplikácia vidí tú istú osobu pod iným ID.
- `id_token` je token OpenID Connect, ktorého nárok `fhirUser` pomenúva zdroj pacienta.
- Kód funguje raz a iba s zodpovedajúcim `code_verifier`.

## Krok 5: Volanie API v rámci scopes

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

Výsledky laboratórnych testov sa vracajú ako obvykle. Požiadajte o niečo mimo povolenia, napríklad lieky:

```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`. Vyhľadávania v rámci povolenia sú tiež filtrované: s `Observation.rs?category=laboratory`, vyhľadávanie všetkých pozorovaní vráti iba laboratórne. Žiadny iný pacient pre tento token neexistuje (`404`). REST pohľad (`/v1`) a [context API](https://developers.anpheros.com/sk/guides/llm-healthcare-data) aplikujú rovnaké scopes.

## Krok 6: Obnovenie

Prístupové tokeny platia 30 minút. Obnovovacie tokeny platia 30 dní a pri každom použití sa 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ískate nový prístupový token a nový obnovovací token. Nový token si ihneď uložte. Opätovné použitie starého obnovovacieho tokenu sa považuje za krádež: zlyhá s chybou `400` a zruší celý grant.

## Krok 7: odvolanie

Osoba vám môže kedykoľvek odvolať prístup z Anpheros a vy si ho môžete odvolať sami, napríklad keď sa v vašej aplikácii odpojí:

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

Odo vtedy každý hovor s týmto grantom odpovie `401`. Riešte to tak, že osobe ukážete, že spojenie skončilo, a ponúknete jej možnosť opätovného pripojenia. Prihláste sa na odber `consent.revoked` [webhooku](https://developers.anpheros.com/sk/guides/webhooks), aby ste to zistili bez čakania na neúspešný hovor.

## Súpravami SDK

[TypeScript a Dart SDK](https://developers.anpheros.com/sk/guides/sdks) vykonajú kroky 3 až 6 za vás: `OAuthFlow.authorizeUrl` s vygenerovaným párom PKCE, `exchange` pri spätnom volaní a automatickým obnovením s rotáciou. Úplné príklady: [Ako vytvoriť AI zdravotnícku aplikáciu s FHIR backendom](https://developers.anpheros.com/sk/guides/build-ai-healthcare-app) (TypeScript) a [Ako vytvoriť zdravotnícku aplikáciu s Flutterom](https://developers.anpheros.com/guides/healthcare-app-flutter) (Dart).

## Čo Anpheros implementuje

| Časť SMART | V Anpheros |
|---|---|
| Discovery | `/.well-known/smart-configuration` na FHIR základe, s podporovanými endpointmi, scopes a PKCE metódami |
| Launch | standalone launch (aplikácia sa spustí, potom požiada o prístup); EHR launch z klinického systému nie je ponúkaný |
| Authorisation | OAuth 2.1 s vyžadovaným PKCE, autorizačný kód flow |
| Scopes | SMART v2 patient scopes, `patient/<Resource>.<cruds>` s filtrami kategórií, plus `openid` a `fhirUser` |
| Identity | OpenID Connect `id_token` pomenúvajúci pacienta ako FHIR resource |
| Consent | hostovaná obrazovka súhlasu v jazyku pacienta, s trvaním zvoleným pacientom, zrkadlená ako FHIR `Consent` |
| Tokens | 30-minútové access tokeny, rotujúce 30-dňové refresh tokeny viazané na súhlas, revokácia |
| Conformance | capability statement deklaruje SMART security service; skupina "Standalone Launch" z Inferno SMART App Launch STU2 test kitu prechádza 22 z 22 testov (spustené 28. septembra 2026); ostatné Inferno skupiny a test kity neboli spustené |

Písanie funguje rovnako: zápis scopes (`patient/Observation.c`, `.u`, `.d`) umožňuje vašej aplikácii vytvárať, aktualizovať alebo mazať v rámci záznamu. Všetko zapísané nesie vašu aplikáciu ako autora, opätovné pokusy s idempotency kľúčom nikdy neduplujú meranie a mazanie je mäkké a zachováva históriu ([Medical data API](https://developers.anpheros.com/sk/guides/medical-data-api)).

## Čo ešte nie je k dispozícii

- Spustenie z EHR (aplikácia spustená z nemocničného systému s kontextom spustenia).
- `system/` scopes pre backendové služby; organizácie namiesto toho používajú API kľúče.
- Export hromadných dát (`$export`); export pre jedného pacienta (`$everything`) je k dispozícii.

Tieto položky sú uvedené spolu s ostatnými v časti [Versioning and deprecation](https://developers.anpheros.com/sk/guides/versioning) a capability statement je vždy autoritatívnym zdrojom.

## Často kladené otázky

### Čo je SMART on FHIR?
Otvorený štandard, postavený na OAuth 2.0/2.1 a OpenID Connect, ktorý definuje, ako aplikácia žiada o prístup k FHIR záznamu, aké rozsahy (scopes) tento prístup popisujú a ako server oznamuje svoje koncové body. Akákoľvek klientska knižnica s podporou SMART môže použiť akýkoľvek server s podporou SMART.

### Potrebujem PKCE?
Áno. Anpheros vyžaduje PKCE s `S256` pre každý tok autorizačného kódu, a to pre verejné aj dôverné klientov. Zabraňuje tomu, aby bol zachytený autorizačný kód použitý niekým iným.

### Čo sa stane, ak osoba povie nie?
Vrátia sa na váš redirect URI s `error=access_denied` a vaším `state`, a bez kódu. Vysvetlite, čo funkcia potrebuje, a nechajte ich skúsiť to znova; volania mimo grantu vždy odpovedajú `403`.

### Môže rodič udeliť súhlas za dieťa?
Áno. Na obrazovke súhlasu môže osoba vybrať záznam, o ktorý sa stará, napríklad záznam dieťaťa, ak je prepojený s jej účtom. Grant sa vzťahuje iba na tento záznam.

## Súvisiace

- [Autentizácia a OAuth](https://developers.anpheros.com/sk/guides/authentication): API kľúče, tokeny a ich životnosť podrobne
- [Zdravotnícke API so súhlasom pacienta](https://developers.anpheros.com/sk/guides/healthcare-api-patient-consent): ako súhlas mení dizajn vašej aplikácie
- [Model súhlasu a prístupu](https://developers.anpheros.com/sk/guides/consent)
- [FHIR platforma](https://developers.anpheros.com/sk/guides/fhir)
- [Vytvorenie zdravotníckej aplikácie](https://developers.anpheros.com/sk/guides/build-a-healthcare-app)