Risposta breve: SMART App Launch (SMART on FHIR) è la specifica di HL7 su come un'app ottiene un accesso autorizzato a un server FHIR per conto di un utente. Si tratta di OAuth 2.0 e OpenID Connect con convenzioni specifiche per FHIR: un documento di discovery in .well-known/smart-configuration; due modalità di lancio (lancio EHR, in cui l'EHR apre l'app nel contesto del paziente corrente, e lancio standalone, in cui l'utente apre l'app e sceglie un paziente); scope in una sintassi consapevole di FHIR (patient/Observation.rs significa lettura e ricerca delle Osservazioni del paziente nel contesto); contesto di lancio restituito con il token (quale paziente, quale incontro); e servizi backend per l'accesso da sistema a sistema con autenticazione client JWT firmata. SMART v2 (dal 2021) ha reso PKCE obbligatorio, aggiunto scope granulari e autenticazione client asimmetrica, ed è la versione richiesta dai programmi nazionali.
Fase 1: discovery
La scoperta di SMART App Launch inizia con l'app che recupera il documento .well-known/smart-configuration del server FHIR, che elenca gli endpoint di autorizzazione e token, le funzionalità supportate (lancio EHR, lancio standalone, client pubblici e confidenziali, OpenID Connect, permessi paziente e utente), gli scope supportati, i metodi di sfida del codice PKCE e i tipi di concessione, in modo che l'app sappia dove inviare l'utente.
GET https://fhir.example-hospital.org/.well-known/smart-configuration
{
"issuer": "https://auth.example-hospital.org",
"authorization_endpoint": "https://auth.example-hospital.org/authorize",
"token_endpoint": "https://auth.example-hospital.org/token",
"introspection_endpoint": "https://auth.example-hospital.org/introspect",
"capabilities": ["launch-ehr", "launch-standalone", "client-public", "client-confidential-asymmetric", "sso-openid-connect", "context-ehr-patient", "context-standalone-patient", "permission-patient", "permission-user", "permission-v2", "permission-offline"],
"scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "patient/*.rs", "user/*.rs", "offline_access"],
"code_challenge_methods_supported": ["S256"],
"grant_types_supported": ["authorization_code", "client_credentials"]
}
L'app scopre dove inviare l'utente e cosa supporta il server.
Fase 2: lancio
SMART App Launch ha due modalità di lancio. In un lancio EHR, il medico apre l'app all'interno dell'EHR, che passa un parametro iss (il server FHIR) e un token di lancio opaco che codifica il paziente e l'incontro corrente. In un lancio standalone, l'utente apre l'app direttamente e il server di autorizzazione chiede di selezionare o confermare un paziente.
Lancio EHR. Il medico clicca sull'app all'interno dell'EHR; l'EHR apre l'URL di lancio dell'app con due parametri: iss (il server FHIR) e launch (un token opaco che codifica il paziente e l'incontro correnti). L'app deve ripetere launch nella sua richiesta di autorizzazione con lo scope launch.
Lancio standalone. L'utente apre l'app direttamente; l'app conosce il server FHIR (scelto o configurato) e richiede il contesto con launch/patient; il server di autorizzazione chiede all'utente di scegliere o confermare un paziente.
Fase 3: codice di autorizzazione con PKCE
Il passaggio di autorizzazione SMART è il flusso di codice di autorizzazione OAuth 2.0 con PKCE: l'app invia l'utente all'endpoint di autorizzazione con i suoi scope, l'aud del server FHIR e una sfida di codice; l'utente si autentica e approva; l'app scambia il codice restituito e il verificatore di codice per un token di accesso che arriva insieme al contesto di lancio.
GET https://auth.example-hospital.org/authorize?
response_type=code&client_id=my-app&redirect_uri=https://app.example.org/cb
&scope=openid%20fhirUser%20launch%20patient/Observation.rs%20patient/Condition.rs%20offline_access
&state=af0ifjsldkj&aud=https://fhir.example-hospital.org
&launch=xyz123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
L'utente si autentica (con il provider di identità dell'ospedale) e approva gli scope; il server reindirizza indietro con un code; l'app lo scambia:
POST https://auth.example-hospital.org/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=...&redirect_uri=https://app.example.org/cb&client_id=my-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "openid fhirUser launch patient/Observation.rs patient/Condition.rs offline_access",
"refresh_token": "a8c3...",
"id_token": "eyJhbGciOi...",
"patient": "Patient/123",
"encounter": "Encounter/456",
"fhirUser": "Practitioner/42",
"need_patient_banner": true,
"smart_style_url": "https://ehr.example.org/styles/smart.json"
}
Il contesto di lancio (patient, encounter, fhirUser) arriva insieme al token. I client pubblici (app mobili e browser) utilizzano PKCE e nessun client secret; i client confidenziali si autenticano con un secret o, preferibilmente, con un JWT firmato (private_key_jwt) secondo il metodo asimmetrico.
Scope
Gli scope di SMART on FHIR v2 utilizzano la sintassi contesto/risorsa.permessi, dove contesto è paziente, utente o sistema e permessi combinano c, r, u, d e s per creare, leggere, aggiornare, eliminare e cercare, come in paziente/Observation.rs. Gli scope granulari aggiungono un filtro, openid e fhirUser forniscono l'identità dell'utente, gli scope di lancio richiedono il contesto e offline_access richiede un token di aggiornamento.
Sintassi SMART v2: <contesto>/<risorsa>.<permessi> dove il contesto è patient (il paziente nel contesto), user (ciò che l'utente può vedere) o system (backend), e i permessi sono qualsiasi di c create, r read, u update, d delete, s search, in quest'ordine: patient/Observation.rs, user/Patient.rs, system/*.cruds. Gli scope granulari aggiungono un filtro: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser forniscono un ID token e l'identità FHIR dell'utente; launch, launch/patient, launch/encounter richiedono il contesto; offline_access un token di aggiornamento da utilizzare quando l'utente è assente, online_access uno valido solo durante la sessione. La sintassi v1 (patient/Observation.read) è ancora accettata da molti server.
Servizi backend
Per un sistema che agisce senza utente (un'esportazione notturna, un motore di integrazione), SMART Backend Services utilizza client_credentials con un'asserzione JWT firmata (le chiavi pubbliche del client pubblicate su un URL JWKS) e scope system/. Nessun utente, nessun contesto di lancio, registrazione rigorosa.
Esecuzione in sicurezza
Eseguire SMART App Launch in modo sicuro significa registrare URI di reindirizzamento esatti, non utilizzare mai il flusso implicito, archiviare e ruotare i token di aggiornamento in modo sicuro, convalidare lo stato e l'aud dei token ID, verificare i token ad ogni chiamata API, applicare sia gli scope che il contesto del paziente a livello di dati in modo che un token per un paziente non legga mai un altro, e registrare ogni accesso.
Registrare URI di reindirizzamento esatti; non utilizzare mai il flusso implicito; archiviare i token di aggiornamento in modo sicuro e ruotarli; convalidare state; controllare aud degli ID token; verificare i token ad ogni chiamata API (introspezione o validazione JWT) e applicare gli scope e il contesto del paziente a livello di dati, perché un token per Patient/123 non deve mai leggere Patient/124; registrare ogni accesso (Sicurezza e identità: la mappa). SMART definisce anche Patient Access Brands, un modo per le app di mostrare agli utenti a quali organizzazioni possono connettersi, e si interfacccia con SMART Health Links per la condivisione avviata dal paziente.
Dove è richiesto
Le regole di accesso ai pazienti negli Stati Uniti richiedono che gli EHR certificati supportino SMART App Launch e Backend Services; i programmi nazionali in Europa lo adottano per l'accesso alle app (MedMij dei Paesi Bassi utilizza OAuth 2.0 con convenzioni equivalenti); l'IPS e molte guide di implementazione lo presuppongono. Vedere TEFCA e Cartelle cliniche elettroniche nazionali.
In Anpheros
Anpheros Platform utilizza OAuth 2.0 con PKCE per le app e autenticazione client JWT firmata per i backend, con scope derivati dal consenso della persona e dal contesto del paziente applicato ad ogni richiesta. Il sito per sviluppatori documenta l'autenticazione e il pattern backend SMART on FHIR per costruirci sopra.
Pagine correlate
- Sicurezza e identità nelle app sanitarie: la mappa
- Piattaforma di consenso del paziente
- SMART Health Links spiegati
- CDS Hooks spiegati
- Ricerca FHIR spiegata
- SMART on FHIR backend (sito per sviluppatori)
- Autenticazione (sito per sviluppatori)
Fonti
- HL7 SMART App Launch (STU 2.2)
- HL7 SMART App Launch: scope e contesto di lancio
- HL7 SMART App Launch: Backend Services
- IETF RFC 7636: PKCE
- IETF RFC 6749: OAuth 2.0
- OpenID Connect Core 1.0
Domande frequenti
SMART on FHIR è la stessa cosa di OAuth 2.0?
È OAuth 2.0 e OpenID Connect con aggiunte specifiche per FHIR: discovery, contesto di lancio, sintassi degli scope e servizi backend. Qualsiasi libreria OAuth funziona; le convenzioni SMART sono ciò che rende un'app portatile tra i server FHIR.
Ho bisogno di PKCE per un'app lato server?
In SMART v2, sì, per tutti i client che utilizzano il flusso del codice di autorizzazione. I client confidenziali aggiungono l'autenticazione client (un secret o un JWT firmato) sopra.
Qual è la differenza tra gli scope patient/ e user/?
patient/ limita l'accesso al singolo paziente nel contesto di lancio; user/ concede ciò che l'utente autenticato è autorizzato a vedere, indipendentemente dai pazienti. Le app rivolte ai pazienti utilizzano patient/; le app per medici utilizzano spesso user/ con contesto.
Un'app SMART può scrivere nel record?
Se le sono stati concessi i permessi di creazione o aggiornamento (c, u) nei suoi scope e il server lo consente. Molte implementazioni concedono alle app per pazienti solo lettura e ricerca, e instradano le scritture attraverso risorse specifiche come QuestionnaireResponse.
Provalo gratis nella sandbox
La tua prima chiamata FHIR in 5 minuti. Un'API HL7 FHIR R4 con il consenso del paziente integrato: provala nella sandbox, poi collega la tua app o il sistema della tua clinica.
Gratis · 30 pazienti sintetici · senza carta
Anpheros sviluppa una cartella clinica che il paziente controlla e può condividere con qualsiasi studio medico, su una piattaforma HL7 FHIR R4, con sede in UE. Queste guide ti aiutano a comprendere e organizzare la tua salute; non sostituiscono il tuo medico.
Chi siamo →