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

Come implementare il consenso del paziente con SMART on FHIR

Q: Ho bisogno di PKCE?

Sì. Anpheros richiede PKCE con S256 per ogni flusso di codice di autorizzazione, sia per client pubblici che confidenziali. Impedisce che un codice di autorizzazione intercettato venga utilizzato da chiunque altro.

Q: Cosa succede se la persona dice di no?

Vengono reindirizzati al tuo URI di reindirizzamento con error=access_denied e il tuo state, e nessun codice. Spiega di cosa ha bisogno la funzionalità e lascia che riprovino; le chiamate al di fuori di una concessione rispondono sempre 403.

Tutorial: SMART on FHIR con OAuth 2.1 e PKCE passo dopo passo — discovery, registrazione app, schermata di consenso, scambio token, ambiti applicati, rotazione refresh e revoca — e cosa implementa Anpheros.

SMART on FHIR è il modo standard con cui un'applicazione ottiene il permesso di una persona di accedere al proprio record FHIR: OAuth 2.1 con PKCE per l'autorizzazione, scope che indicano esattamente cosa può essere letto o scritto, e un documento di discovery che dice all'applicazione dove andare. Questo tutorial esegue l'intero flusso contro Anpheros, passo dopo passo con curl: discovery, registrazione di un'applicazione, invio della persona alla schermata di consenso, scambio del codice, chiamata dell'API all'interno degli scope concessi, refresh e cosa succede quando la persona revoca l'accesso. Anpheros è il backend SMART on FHIR: ospita il server di autorizzazione, la schermata di consenso e il server FHIR R4, quindi non è necessario scrivere alcuna UI di login o consenso propria.

Perché il consenso e non solo una chiave API

Una chiave API raggiunge i pazienti creati dal tuo progetto. Il record esistente di una persona (i propri dati, raccolti da altre app, cliniche e laboratori) è loro da condividere. Con SMART on FHIR:

la persona vede, nella propria lingua, quale applicazione chiede, cosa vuole leggere o scrivere, per quale scopo e per quanto tempo;
la tua applicazione ottiene solo quei tipi di risorse e azioni, e solo per quel singolo record;
ogni accesso viene registrato e visibile alla persona, che può revocarlo in qualsiasi momento;
la concessione viene anche memorizzata come una risorsa FHIR Consent.

Il modello sottostante è descritto in Healthcare API with patient consent e Consent and access model.

Passaggio 1: discovery

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

La risposta elenca gli endpoint e ciò che il server supporta (abbreviato):

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

Le librerie client SMART leggono questo documento e non necessitano di ulteriori configurazioni.

Passaggio 2: Registra la tua applicazione

Nel dashboard, apri il tuo progetto e aggiungi un'applicazione con il suo redirect URI. Oppure tramite l'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", …}

Usa public per app mobile e browser, che non possono mantenere un segreto e si basano su PKCE. Usa confidential per un server; il suo client_secret viene mostrato una sola volta. Il nome, lo scopo e il link alla privacy sono ciò che la persona vede nella schermata di consenso.

Passaggio 3: inviare la persona alla schermata di consenso

Crea una coppia PKCE. Il verificatore rimane con te; solo il suo hash viaggia:

VERIFIER=$(openssl rand -base64 64 | tr -d '=+/\n' | cut -c1-64)
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')

Quindi apri questo indirizzo nel browser della persona (interruzioni di riga aggiunte per la lettura):

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

Chiedi il minimo necessario. Questa applicazione legge i risultati di laboratorio e le diagnosi, nient'altro. offline_access fornisce un token di aggiornamento, in modo che la persona non debba approvare nuovamente ogni 30 minuti.

La persona accede ad Anpheros, legge la richiesta in linguaggio chiaro, sceglie quale record condividere (il proprio, quello di un familiare di cui si prende cura, o quello creato dalla tua app per loro) e per quanto tempo dura l'accesso, quindi consente o nega. Torna al tuo URI di reindirizzamento:

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

Verifica che state sia il valore che hai inviato prima di utilizzare il codice.

Fase 4: Scambiare il codice per i token

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 elenca ciò che è stato concesso. Mantenerlo con i token e mostrare solo le funzionalità che copre.
patient è l'ID del record per la tua applicazione. È pairwise: un'altra applicazione vede la stessa persona con un ID diverso.
id_token è un token OpenID Connect il cui claim fhirUser nomina la risorsa paziente.
Il codice funziona una sola volta e solo con il code_verifier corrispondente.

Passo 5: chiamare l'API all'interno degli scope

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

I risultati di laboratorio arrivano come al solito. Chiedi qualcosa al di fuori della concessione, come i farmaci:

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

Questo è un 403. Anche le ricerche all'interno della concessione vengono filtrate: con Observation.rs?category=laboratory, una ricerca di tutte le osservazioni restituisce solo quelle di laboratorio. Qualsiasi altro paziente non esiste per questo token (404). La vista REST (/v1) e l'API di contesto applicano gli stessi scope.

Step 6: refresh

I token di accesso durano 30 minuti. I token di refresh durano 30 giorni e ruotano ad ogni utilizzo:

curl -X POST https://platform.anpheros.com/oauth/token \
  -d grant_type=refresh_token -d client_id=client_Hg6CknNkYlMgN190 -d refresh_token=$REFRESH_TOKEN

Ottieni un nuovo token di accesso e un nuovo token di refresh. Memorizza subito quello nuovo. Il riutilizzo di un vecchio token di refresh viene trattato come un furto: fallisce con 400 e revoca l'intera concessione.

Passaggio 7: revoca

La persona può revocare il tuo accesso da Anpheros in qualsiasi momento, e tu puoi revocarlo autonomamente, ad esempio quando si disconnettono nella tua app:

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

Da quel momento in poi, ogni chiamata con quella concessione risponderà 401. Gestiscilo mostrando alla persona che la connessione è terminata e offrendoti di riconnetterti. Iscriviti al webhook consent.revoked per scoprirlo senza attendere una chiamata fallita.

Con gli SDK

I SDK TypeScript e Dart eseguono i passaggi da 3 a 6 per te: OAuthFlow.authorizeUrl con una coppia PKCE generata, exchange al callback e refresh automatico con rotazione. Esempi completi: Come creare un'app sanitaria AI con un backend FHIR (TypeScript) e Come creare un'app sanitaria con Flutter (Dart).

Cosa implementa Anpheros

Parte di SMART	In Anpheros
Discovery	`/.well-known/smart-configuration` sulla base FHIR, con gli endpoint, gli scope e i metodi PKCE supportati
Launch	standalone launch (l'applicazione si avvia, quindi richiede l'accesso); EHR launch dall'interno di un sistema clinico non è offerto
Authorisation	OAuth 2.1 con PKCE richiesto, flusso di autorizzazione tramite codice
Scopes	scope paziente SMART v2, `patient/<Resource>.<cruds>` con filtri per categoria, più `openid` e `fhirUser`
Identity	un OpenID Connect `id_token` che nomina il paziente come risorsa FHIR
Consent	una schermata di consenso ospitata nella lingua del paziente, con la durata scelta dal paziente, rispecchiata come un FHIR `Consent`
Tokens	token di accesso da 30 minuti, token di refresh rotanti da 30 giorni legati al consenso, revoca
Conformance	la capability statement dichiara il servizio di sicurezza SMART; il gruppo "Standalone Launch" del kit di test Inferno SMART App Launch STU2 supera 22 test su 22 (esecuzione del 28 settembre 2026); gli altri gruppi e kit di test Inferno non sono stati eseguiti

La scrittura funziona allo stesso modo: scrivere scope (patient/Observation.c, .u, .d) consente alla tua applicazione di creare, aggiornare o eliminare all'interno del record. Tutto ciò che viene scritto porta la tua applicazione come autore, i tentativi con una chiave di idempotenza non duplicano mai una misurazione e le eliminazioni sono "soft" e mantengono la cronologia (Medical data API).

Cosa non è ancora disponibile

EHR launch (l'applicazione aperta dall'interno di un sistema ospedaliero con un contesto di lancio).
system/ scope per servizi backend; le organizzazioni utilizzano invece API key.
Bulk Data export ($export); $everything su un paziente è disponibile.

Questi sono elencati con il resto in Versioning e deprecazione, e la capability statement è sempre la fonte autorevole.

Domande frequenti

Cos'è SMART on FHIR?

Uno standard aperto, basato su OAuth 2.0/2.1 e OpenID Connect, che definisce come un'applicazione richiede l'accesso a un record FHIR, quali ambiti descrivono tale accesso e come il server pubblicizza i propri endpoint. Qualsiasi libreria client compatibile con SMART può utilizzare qualsiasi server compatibile con SMART.

Ho bisogno di PKCE?

Sì. Anpheros richiede PKCE con S256 per ogni flusso di codice di autorizzazione, sia per client pubblici che confidenziali. Impedisce che un codice di autorizzazione intercettato venga utilizzato da chiunque altro.

Cosa succede se la persona dice di no?

Vengono reindirizzati al tuo URI di reindirizzamento con error=access_denied e il tuo state, e nessun codice. Spiega di cosa ha bisogno la funzionalità e lascia che riprovino; le chiamate al di fuori di una concessione rispondono sempre 403.

Un genitore può dare il consenso per un bambino?

Sì. Nella schermata di consenso una persona può scegliere un record a cui tiene, come quello di un bambino, se è collegato al proprio account. La concessione si applica solo a quel record.

Correlati

Autenticazione e OAuth: chiavi API, token e durate in dettaglio
API Sanitaria con consenso del paziente: come il consenso modifica la progettazione della tua applicazione
Modello di consenso e accesso
Piattaforma FHIR
Creare un'app sanitaria

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