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

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

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

Το 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 και Consent and access model.

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

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

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

{"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: Εγγραφή της εφαρμογής σας

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

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

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

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

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

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

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

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, μια αναζήτηση για όλες τις παρατηρήσεις επιστρέφει μόνο τις εργαστηριακές. Κανένας άλλος ασθενής δεν υπάρχει για αυτό το token (404). Η REST view (/v1) και το context API εφαρμόζουν τα ίδια πεδία εμβέλειας.

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

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

Λαμβάνετε ένα νέο access token και ένα νέο 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. Χειριστείτε το δείχνοντας στο άτομο ότι η σύνδεση έληξε και προσφέροντας να συνδεθεί ξανά. Εγγραφείτε στο webhook consent.revoked για να μάθετε χωρίς να περιμένετε μια αποτυχημένη κλήση.

Με τα SDKs

Τα TypeScript και Dart SDKs εκτελούν τα βήματα 3 έως 6 για εσάς: OAuthFlow.authorizeUrl με ένα ζεύγος PKCE που έχει δημιουργηθεί, exchange στο callback, και αυτόματη ανανέωση με περιστροφή. Πλήρη παραδείγματα: Πώς να δημιουργήσετε μια εφαρμογή AI υγείας με backend FHIR (TypeScript) και Πώς να δημιουργήσετε μια εφαρμογή υγείας με Flutter (Dart).

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

Η γραφή λειτουργεί με τον ίδιο τρόπο: γράψτε scopes (patient/Observation.c, .u, .d) επιτρέπουν στην εφαρμογή σας να δημιουργεί, να ενημερώνει ή να διαγράφει εντός του αρχείου. Οτιδήποτε γράφεται φέρει την εφαρμογή σας ως συγγραφέα, οι επαναδοκιμές με ένα κλειδί ιδιοσυγκρασίας δεν διπλασιάζουν ποτέ μια μέτρηση, και οι διαγραφές είναι soft και διατηρούν το ιστορικό (Medical data API).

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

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

Αυτά αναφέρονται μαζί με τα υπόλοιπα στο Versioning and deprecation, και η δήλωση δυνατοτήτων (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: Κλειδιά API, διακριτικά και διάρκειες ζωής αναλυτικά
• API Υγείας με συναίνεση ασθενούς: πώς οι αλλαγές συναίνεσης επηρεάζουν τον σχεδιασμό της εφαρμογής σας
• Μοντέλο συναίνεσης και πρόσβασης
• Πλατφόρμα FHIR
• Δημιουργία εφαρμογής υγείας

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