Connettiti alle applicazioni utilizzando SMART on FHIR

Questa pagina descrive come utilizzare lo standard SMART (Substitutable Medical Applications, Reusable Technologies) on FHIR v1.1.0 per accedere ai dati nei datastore FHIR nell'API Cloud Healthcare.

Panoramica

SMART on FHIR è uno standard di dati che consente alle applicazioni di accedere alle informazioni nei sistemi di cartelle cliniche elettroniche (EHR). Uno sviluppatore di applicazioni può scrivere una singola applicazione che si connette a qualsiasi sistema di EPR che ha adottato lo standard.

Ad esempio, se hai dati dei pazienti archiviati in un archivio FHIR nell'API Cloud Healthcare, puoi sviluppare un'applicazione che:

  1. Esegue l'autenticazione nell'archivio FHIR.
  2. Recupera i dati del paziente.
  3. Mostra i dati del paziente in un'interfaccia utente.

SMART on FHIR supporta i modelli di autorizzazione OpenID e OAuth 2.0 per l'autorizzazione e l'autenticazione.

Framework di lancio di app SMART, ambiti e contesto di lancio

L'API Cloud Healthcare supporta il framework di lancio delle app SMART, gli ambiti e il contesto di lancio come segue:

SMART App Launch Framework

L'API Cloud Healthcare supporta la sequenza di lancio autonoma del framework di lancio delle app SMART.

Un'app può essere avviata da un sistema EHR esistente o da una sessione del portale per i pazienti, entrambi chiamati "avvio EHR", oppure come app autonoma.

Ambiti

Gli ambiti dei dati clinici definiscono le autorizzazioni di lettura e scrittura per l'accesso a livello di utente e per dati specifici del paziente. L'API Cloud Healthcare supporta i seguenti ambiti dei dati definiti in Ambiti per la richiesta di dati clinici:

  • patient
  • user
  • system
Contesto di lancio

Descrive il paziente, l'incontro o un altro contesto corrente in cui viene effettuata la richiesta. L'API Cloud Healthcare supporta il contesto di lancio del paziente da Ampi dello spazio per la richiesta di dati di contesto.

Configura il server di autorizzazione per SMART on FHIR

L'API Cloud Healthcare fornisce il supporto integrato per l'applicazione dell'accesso a SMART su FHIR in base agli ambiti di autorizzazione SMART e al contesto del paziente inseriti. Gli amministratori degli archivi FHIR creano e configurano un server di autorizzazione esterno all'API Cloud Healthcare che concede ambiti di autorizzazione SMART e contesto del paziente.

Se un'applicazione client ottiene un token di accesso che rappresenta gli scopi di autorizzazione SMART e il contesto del paziente concessi, l'API Cloud Healthcare non specifica quale flusso di lavoro di lancio l'applicazione client deve utilizzare con il server di autorizzazione esterno.

Impostare e convalidare gli ambiti di autorizzazione SMART

Se utilizzi SMARTProxy, puoi saltare questa sezione. SMARTProxy imposta e convalida automaticamente gli ambiti di autorizzazione SMART.

Gli ambiti di autorizzazione SMART utilizzano il seguente formato:

( 'patient' | 'user' | 'system') '/' ( resourceType | '*' ) '.' ( 'read' | 'write' | '*' )

Gli ambiti di autorizzazione SMART e i contesti dei pazienti vengono trasmessi all'API Cloud Healthcare utilizzando le intestazioni HTTP X-Authorization-. L'API Cloud Healthcare utilizza queste intestazioni per applicare controllo dell'accesso ai dati negli archivi FHIR.

Il server di autorizzazione concede gli ambiti di autorizzazione SMART e il contesto del paziente e li codifica in un token di accesso. Il proxy legge quindi le informazioni nel token di accesso e le passa alle intestazioni delle richieste FHIR.

Se non disponi di un server di autorizzazione, puoi utilizzare l'acceleratore di interoperabilità basato su Apigee HealthAPIx su Apigee.

Utilizza le seguenti intestazioni HTTP di SMART on FHIR quando invii richieste dal proxy. L'applicazione client non deve impostare queste intestazioni perché vengono solo comunicate dal proxy all'API Cloud Healthcare.

  • X-Authorization-Scope: uno o più ambiti di autorizzazione che utilizzano i formati standard degli ambiti di autorizzazione SMART. Ad esempio, impostare l'ambito di autorizzazione su user/Observation.read significa che una richiesta può leggere solo una risorsa Observation. L'API Cloud Healthcare applica questo controllo dell'accesso.
  • X-Authorization-Patient: il contesto del paziente della richiesta. Quando imposti questa intestazione, tutti i tipi di risorse nella richiesta idonei a essere in un alloggiamento del paziente devono appartenere all'alloggiamento del paziente dell'ID paziente fornito. L'API Cloud Healthcare applica questo controllo dell'accesso.
  • X-Authorization-Subject: un identificatore per l'utente finale che accede all'applicazione client di SMART su FHIR. L'API Cloud Healthcare registra l'oggetto negli audit log.
  • X-Authorization-Issuer: l'emittente del token di accesso SMART. L'API Cloud Healthcare registra l'emittente negli audit log.

Configura i token di accesso del server di autorizzazione

Per emettere un token JWT, devi configurare un server di autorizzazione. Il token JWT contiene gli ambiti di autorizzazione SMART e, facoltativamente, il contesto del paziente. L'API Cloud Healthcare non ha requisiti specifici per la modalità di conio del token JWT SMART da parte del server di autorizzazione. Ad esempio, la tua applicazione potrebbe essere registrata per un sottoinsieme di ambiti oppure potrebbe presentare un widget di selezione del paziente per impostare il contesto del paziente.

Se non disponi di un server di autorizzazione che configura i token JWT SMART, puoi utilizzare l'acceleratore di interoperabilità basato su Apigee HealthAPIx su Apigee per configurare un server di autenticazione che firmi i token JWT.

Token di accesso di esempio

L'esempio seguente mostra un token di accesso codificato in base64:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzM4NCJ9.eyJpc3MiOiJzbWFydC50b2tlbi5vcmciLCJpYXQiOjE2MTI4ODQwODUsImV4cCI6MTY0NDQyMDA4NSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiZG9jdG9yLmpvZUBleGFtcGxlLmNvbSIsInNjb3BlIjoidXNlci9QcmFjdGl0aW9uZXIucmVhZCBwYXRpZW50LyouKiIsInBhdGllbnQiOiJwYXRpZW50MTIzIn0.lC0ouNuXNcj7FxQ83NU_MInULWo0wvyiNuaMt2RbFzBOnnMP_IXJdCeNnw3SQzUV

Dopo la decodifica, il token di accesso contiene il seguente payload:

{
  "iss": "smart.token.org",
  "iat": 1612884085,
  "exp": 1644420085,
  "aud": "www.example.com",
  "sub": "doctor.gabriela@example.com",
  "scope": "user/Practitioner.read patient/*.*",
  "patient": "patient123"
}

Configurare SMART su FHIR nell'API Cloud Healthcare

Questa sezione descrive i passaggi da seguire per iniziare a utilizzare SMART on FHIR con i dati nell'API Cloud Healthcare.

Configurare SMARTProxy

Se utilizzi il tuo server di autorizzazione anziché SMARTProxy, salta questa sezione e vai a Configurare un account di servizio Google Cloud.

SMARTProxy è un proxy open source di Google che offre le seguenti funzionalità:

  • Consente all'API Cloud Healthcare di accettare e convalidare i token di accesso SMART.
  • Consente all'implementazione di FHIR nell'API Cloud Healthcare di includere i token di accesso SMART come parte del modello di gestione e autorizzazione dell'API.

Quando effettui una richiesta per recuperare i dati dall'API Cloud Healthcare tramite SMARTProxy, la richiesta segue questi passaggi:

  1. SMARTProxy accetta una richiesta contenente un token SMART da un client.
  2. SMARTProxy convalida il token SMART tramite il server di autorizzazione JWT.
  3. SMARTProxy legge gli ambiti e il contesto del paziente dal token SMART e li passa all'API Cloud Healthcare utilizzando quattro intestazioni HTTP.
  4. L'API Cloud Healthcare riceve le intestazioni e le convalida per applicare controllo dell'accesso alla richiesta. L'API Cloud Healthcare poi restituisce una risposta tramite SMARTProxy al client.

Configurare un account di servizio Google Cloud

Un proxy può avere un solo account di servizio Google Cloud. Se più client utilizzano lo stesso proxy, devono utilizzare lo stesso account servizio. Presta attenzione quando condividi un account di servizio con più client per i seguenti motivi:

  • Per leggere i dati FHIR nell'API Cloud Healthcare, l'account di servizio deve disporre di autorizzazioni di lettura e scrittura ampie.

  • L'indirizzo email principale dei log di controllo di Cloud è associato all'account di servizio.

    Ad esempio, se chiami l'API Cloud Healthcare utilizzando il tuo Account Google per l'autenticazione, Cloud Audit Logs registra il tuo indirizzo email come indirizzo email principale. Quando utilizzi un proxy per chiamare l'API Cloud Healthcare, il proxy utilizza il proprio account di servizio e l'indirizzo email dell'account di servizio è l'indirizzo email principale, pertanto l'utente chiamante originale viene oscurato. Per salvare l'utente finale nei metadati del log di controllo, passa l'indirizzo email dell'utente finale nel campo sub del token JWT.

Configurare un datastore FHIR

Non è necessario configurare l'archivio FHIR contenente i dati FHIR a cui accedi.

Effettuare richieste SMART su FHIR

Questa sezione fornisce una panoramica dei metodi SMART su FHIR supportati nell'API Cloud Healthcare e su come viene applicato l'accesso alle risorse quando viene effettuata una richiesta SMART su FHIR.

Quando effettui una richiesta, il tuo server di autorizzazione è responsabile della generazione di token di accesso con l'ambito di autorizzazione e il contesto di lancio SMART pertinenti.

Metodi supportati

L'API Cloud Healthcare supporta SMART su FHIR per tutti i metodi projects.locations.datasets.fhirStores.fhir, ad eccezione dei seguenti:

Applicazione dell'accesso alle risorse

Quando viene effettuata una richiesta SMART on FHIR a un archivio FHIR, controllo dell'accesso avviene nel seguente ordine:

  1. L'API Cloud Healthcare controlla le autorizzazioni dell'account di servizio Google Cloud configurato nel proxy. Se l'account di servizio dispone delle autorizzazioni IAM corrette per il datastore FHIR, la richiesta viene eseguita.
  2. L'API Cloud Healthcare verifica se il token SMART dispone delle autorizzazioni appropriate per accedere a ogni risorsa FHIR richiesta dalla richiesta.

Il comparto del paziente è fondamentale per la logica di applicazione dell'accesso nell'API Cloud Healthcare. SMART on FHIR contiene un elenco di tipi di risorse FHIR idonei per essere inclusi in un comparto del paziente. I tipi di risorse hanno anche i propri criteri di inclusione. Nel resto di questa sezione, i tipi di risorse idonee sono chiamati "tipi di risorse idonee per il comparto dei pazienti". I tipi di risorse non idonee sono chiamati "tipi di risorse non idonee per il comparto dei pazienti".

Le richieste SMART on FHIR a un archivio FHIR devono soddisfare i seguenti requisiti:

  • Fornisci il ruolo patient, user o system negli scopi di autorizzazione SMART. Se fornisci il ruolo patient, devi fornire un contesto del paziente. Il contesto del paziente è un ID logico della risorsa Patient. La risorsa Patient deve già esistere nell'archivio FHIR o essere creata dopo l'invio della richiesta, altrimenti l'API Cloud Healthcare la rifiuta.

  • Quando crei, leggi, aggiorni o elimini una risorsa, resourceType e il tipo di operazione (read o write) devono corrispondere, altrimenti l'API Cloud Healthcare rifiuta la richiesta.

  • Se fornisci un ambito patient contenente tipi di risorse non idonee per il comparto dei pazienti, ad esempio patient/Practitioner.*, il controllo di convalida dell'ambito non va a buon fine e l'API Cloud Healthcare lo rifiuta.

  • Puoi impostare tutti i tipi di risorse con l'ambito user. Se è presente un contesto del paziente con un ambito user, i tipi di risorse idonee per il comparto del paziente sono limitati al contesto del paziente. I tipi di risorse rimanenti ignorano il contesto del paziente.

  • La presenza di un contesto paziente limita i tipi di risorse idonee per il comparto del paziente al paziente in questione. Ad esempio, una risorsa Observation deve avere il subject campo che fa riferimento alla risorsa Patient specificata affinché l'osservazione sia accessibile. Consulta i tipi di accesso all'alloggiamento del paziente in Resource CompartmentDefinition - Content per un elenco dei campi in ogni tipo di risorsa dell'alloggiamento del paziente a cui deve essere fatto riferimento al paziente specificato affinché la risorsa sia considerata all'interno dell'alloggiamento del paziente.

  • Le richieste possono contenere sia gli ambiti patient sia user.

  • Non utilizzare l'ambito system con il contesto del paziente, altrimenti la richiesta non va a buon fine.

  • Non utilizzare l'ambito system con l'ambito patient o user.

  • Se chiami un metodo che accede a più risorse (ad esempio il metodo fhir.Patient-everything, fhir.executeBundle o fhir.search), il controllo dell'accesso si applica a ogni singola risorsa.