# Πώς να υλοποιήσετε τη συναίνεση ασθενούς με SMART on FHIR

> Οδηγός: SMART on FHIR με OAuth 2.1 και PKCE βήμα προς βήμα — ανακάλυψη, εγγραφή εφαρμογής, οθόνη συναίνεσης, ανταλλαγή token, επιβολή scopes, ανανέωση και ανάκληση — και τι υλοποιεί το Anpheros.

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

**Το SMART on FHIR είναι ο τυπικός τρόπος με τον οποίο μια εφαρμογή λαμβάνει την άδεια ενός ατόμου για να αποκτήσει πρόσβαση στο αρχείο FHIR του: OAuth 2.1 με PKCE για την εξουσιοδότηση, scopes που λένε ακριβώς τι μπορεί να διαβαστεί ή να γραφτεί, και ένα έγγραφο ανακάλυψης που λέει στην εφαρμογή πού να πάει.** Αυτός ο οδηγός εκτελεί ολόκληρη τη ροή έναντι του Anpheros, βήμα προς βήμα με `curl`: ανακάλυψη, εγγραφή μιας εφαρμογής, αποστολή του ατόμου στην οθόνη συναίνεσης, ανταλλαγή του κωδικού, κλήση του API εντός των χορηγηθέντων scopes, ανανέωση και τι συμβαίνει όταν το άτομο ανακαλεί την πρόσβαση. Το Anpheros είναι το backend SMART on FHIR: φιλοξενεί τον διακομιστή εξουσιοδότησης, την οθόνη συναίνεσης και τον διακομιστή FHIR R4, οπότε δεν γράφετε δικό σας UI σύνδεσης ή συναίνεσης.

## Γιατί συναίνεση και όχι απλό κλειδί API

Ένα κλειδί API φτάνει στους ασθενείς που δημιούργησε το έργο σας. Ένα υπάρχον αρχείο ενός ατόμου (τα δικά του δεδομένα, που συλλέχθηκαν από άλλες εφαρμογές, κλινικές και εργαστήρια) είναι δικό του για να το μοιραστεί. Με το SMART on FHIR:

- το άτομο βλέπει, στη γλώσσα του, ποια εφαρμογή ζητά, τι θέλει να διαβάσει ή να γράψει, για ποιον σκοπό και για πόσο καιρό·
- η εφαρμογή σας λαμβάνει μόνο αυτούς τους τύπους πόρων και ενέργειες, και μόνο για αυτό το ένα αρχείο·
- κάθε πρόσβαση καταγράφεται και είναι ορατή στο άτομο, το οποίο μπορεί να την ανακαλέσει ανά πάσα στιγμή·
- η παραχώρηση αποθηκεύεται επίσης ως πόρος FHIR `Consent`.

Το μοντέλο πίσω από αυτό περιγράφεται στο [Healthcare API with patient consent](https://developers.anpheros.com/el/guides/healthcare-api-patient-consent) και [Consent and access model](https://developers.anpheros.com/el/guides/consent).

## Βήμα 1: ανακάλυψη

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

Η απάντηση παραθέτει τα τελικά σημεία (endpoints) και τι υποστηρίζει ο διακομιστής (συντομευμένη):

```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/), ανοίξτε το έργο σας και προσθέστε μια εφαρμογή με το redirect 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` δίνει ένα refresh token, οπότε το άτομο δεν χρειάζεται να εγκρίνει ξανά κάθε 30 λεπτά.

Το άτομο συνδέεται στο Anpheros, διαβάζει το αίτημα σε απλή γλώσσα, επιλέγει ποιο αρχείο να μοιραστεί (το δικό του, ενός μέλους της οικογένειας για το οποίο φροντίζει, ή αυτό που δημιούργησε η εφαρμογή σας για αυτό) και για πόσο χρονικό διάστημα ισχύει η πρόσβαση, και στη συνέχεια επιτρέπει ή απορρίπτει. Επιστρέφει στο redirect URI σας:

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

Ελέγξτε ότι το `state` είναι η τιμή που στείλατε πριν χρησιμοποιήσετε τον κωδικό.

## Βήμα 4: Ανταλλαγή του κωδικού για tokens

```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` παραθέτει τι χορηγήθηκε. Διατηρήστε το μαζί με τα tokens και εμφανίστε μόνο τις δυνατότητες που καλύπτει.
- Το `patient` είναι το αναγνωριστικό εγγραφής για την εφαρμογή σας. Είναι ζεύγος: μια άλλη εφαρμογή βλέπει το ίδιο άτομο με διαφορετικό αναγνωριστικό.
- Το `id_token` είναι ένα token OpenID Connect του οποίου η δήλωση `fhirUser` ονομάζει τον πόρο ασθενούς.
- Ο κωδικός λειτουργεί μία φορά, και μόνο με το αντίστοιχο `code_verifier`.

## Βήμα 5: Κλήση του API εντός των πεδίων εμβέλειας (scopes)

```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`, μια αναζήτηση για όλες τις παρατηρήσεις επιστρέφει μόνο τις εργαστηριακές. Κανένας άλλος ασθενής δεν υπάρχει για αυτό το token (`404`). Η REST view (`/v1`) και το [context API](https://developers.anpheros.com/el/guides/llm-healthcare-data) εφαρμόζουν τα ίδια πεδία εμβέλειας.

## Βήμα 6: ανανέωση

Τα access tokens διαρκούν 30 λεπτά. Τα refresh tokens διαρκούν 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
```

Λαμβάνετε ένα νέο access token και ένα νέο 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`. Χειριστείτε το δείχνοντας στο άτομο ότι η σύνδεση έληξε και προσφέροντας να συνδεθεί ξανά. Εγγραφείτε στο [webhook](https://developers.anpheros.com/el/guides/webhooks) `consent.revoked` για να μάθετε χωρίς να περιμένετε μια αποτυχημένη κλήση.

## Με τα SDKs

Τα [TypeScript και Dart SDKs](https://developers.anpheros.com/el/guides/sdks) εκτελούν τα βήματα 3 έως 6 για εσάς: `OAuthFlow.authorizeUrl` με ένα ζεύγος PKCE που έχει δημιουργηθεί, `exchange` στο callback, και αυτόματη ανανέωση με περιστροφή. Πλήρη παραδείγματα: [Πώς να δημιουργήσετε μια εφαρμογή AI υγείας με backend FHIR](https://developers.anpheros.com/el/guides/build-ai-healthcare-app) (TypeScript) και [Πώς να δημιουργήσετε μια εφαρμογή υγείας με Flutter](https://developers.anpheros.com/el/guides/healthcare-app-flutter) (Dart).

## Τι υλοποιεί το Anpheros

| Μέρος του SMART | Στο Anpheros |
|---|---|
| Discovery | `/.well-known/smart-configuration` στη βάση FHIR, με τα υποστηριζόμενα endpoints, scopes και μεθόδους PKCE |
| Launch | standalone launch (η εφαρμογή ξεκινά, στη συνέχεια ζητά πρόσβαση); το EHR launch από ένα κλινικό σύστημα δεν προσφέρεται |
| Authorisation | OAuth 2.1 με PKCE απαιτείται, ροή κωδικού εξουσιοδότησης |
| Scopes | SMART v2 patient scopes, `patient/<Resource>.<cruds>` με φίλτρα κατηγορίας, συν `openid` και `fhirUser` |
| Identity | ένα OpenID Connect `id_token` που ονομάζει τον ασθενή ως FHIR resource |
| Consent | μια φιλοξενούμενη οθόνη συναίνεσης στη γλώσσα του ασθενούς, με τη διάρκεια που επιλέγεται από τον ασθενή, η οποία αντικατοπτρίζεται ως FHIR `Consent` |
| Tokens | access tokens 30 λεπτών, rotating refresh tokens 30 ημερών συνδεδεμένα με τη συναίνεση, ανάκληση |
| Conformance | η δήλωση capabilities δηλώνει την υπηρεσία ασφαλείας SMART. Η ομάδα "Standalone Launch" του Inferno SMART App Launch STU2 test kit περνά 22 από 22 τεστ (εκτέλεση στις 28 Σεπτεμβρίου 2026). Οι άλλες ομάδες και τα test kits του Inferno δεν έχουν εκτελεστεί |

Η γραφή λειτουργεί με τον ίδιο τρόπο: γράψτε scopes (`patient/Observation.c`, `.u`, `.d`) επιτρέπουν στην εφαρμογή σας να δημιουργεί, να ενημερώνει ή να διαγράφει εντός του αρχείου. Οτιδήποτε γράφεται φέρει την εφαρμογή σας ως συγγραφέα, οι επαναδοκιμές με ένα κλειδί ιδιοσυγκρασίας δεν διπλασιάζουν ποτέ μια μέτρηση, και οι διαγραφές είναι soft και διατηρούν το ιστορικό ([Medical data API](https://developers.anpheros.com/el/guides/medical-data-api)).

## Τι δεν υπάρχει ακόμα

- Εκκίνηση EHR (η εφαρμογή που ανοίγει από ένα νοσοκομειακό σύστημα με ένα πλαίσιο εκκίνησης).
- `system/` scopes για backend υπηρεσίες· οι οργανισμοί χρησιμοποιούν αντ' αυτού API keys.
- Μαζική εξαγωγή δεδομένων (`$export`)· `$everything` για έναν ασθενή είναι διαθέσιμο.

Αυτά αναφέρονται μαζί με τα υπόλοιπα στο [Versioning and deprecation](https://developers.anpheros.com/el/guides/versioning), και η δήλωση δυνατοτήτων (capability statement) είναι πάντα η έγκυρη πηγή.

## Συχνές ερωτήσεις

### Τι είναι το SMART on FHIR;
Ένα ανοιχτό πρότυπο, βασισμένο στα OAuth 2.0/2.1 και OpenID Connect, που ορίζει πώς μια εφαρμογή ζητά πρόσβαση σε ένα αρχείο FHIR, ποιες εμβέλειες (scopes) περιγράφουν αυτήν την πρόσβαση και πώς ο διακομιστής διαφημίζει τα τελικά του σημεία (endpoints). Οποιαδήποτε βιβλιοθήκη πελάτη (client library) συμβατή με SMART μπορεί να χρησιμοποιήσει οποιονδήποτε διακομιστή συμβατό με SMART.

### Χρειάζομαι PKCE;
Ναι. Το Anpheros απαιτεί PKCE με `S256` για κάθε ροή κώδικα εξουσιοδότησης (authorisation code flow), τόσο για δημόσιους όσο και για εμπιστευτικούς πελάτες. Αποτρέπει τη χρήση ενός υποκλαπέντος κώδικα εξουσιοδότησης από οποιονδήποτε άλλο.

### Τι συμβαίνει αν το άτομο αρνηθεί;
Επιστρέφει στο URI ανακατεύθυνσής σας (redirect URI) με `error=access_denied` και το `state` σας, και χωρίς κωδικό. Εξηγήστε τι χρειάζεται η λειτουργία και αφήστε τους να προσπαθήσουν ξανά. Οι κλήσεις εκτός μιας χορήγησης (grant) απαντούν πάντα `403`.

### Μπορεί ένας γονέας να δώσει συγκατάθεση για ένα παιδί;
Ναι. Στην οθόνη συγκατάθεσης, ένα άτομο μπορεί να επιλέξει ένα αρχείο για το οποίο ενδιαφέρεται, όπως αυτό ενός παιδιού, εάν συνδέεται με τον λογαριασμό του. Η χορήγηση ισχύει μόνο για αυτό το αρχείο.

## Σχετικά

- [Έλεγχος ταυτότητας και OAuth](https://developers.anpheros.com/el/guides/authentication): Κλειδιά API, διακριτικά και διάρκειες ζωής αναλυτικά
- [API Υγείας με συναίνεση ασθενούς](https://developers.anpheros.com/el/guides/healthcare-api-patient-consent): πώς οι αλλαγές συναίνεσης επηρεάζουν τον σχεδιασμό της εφαρμογής σας
- [Μοντέλο συναίνεσης και πρόσβασης](https://developers.anpheros.com/el/guides/consent)
- [Πλατφόρμα FHIR](https://developers.anpheros.com/el/guides/fhir)
- [Δημιουργία εφαρμογής υγείας](https://developers.anpheros.com/el/guides/build-a-healthcare-app)