Connettiti alle applicazioni utilizzando SMART su FHIR

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

Panoramica

SMART su 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 connetta a qualsiasi sistema EHR che ha adottato lo standard.

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

  1. Esegue l'autenticazione nel datastore FHIR.
  2. Recupera i dati del paziente.
  3. Visualizza i dati del paziente in un'interfaccia utente.

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

Framework, ambiti e contesto del lancio di SMART App

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

Framework per il lancio di app SMART

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

Un'app può essere avviata all'interno di un sistema EHR esistente o di una sessione del Portale pazienti, entrambi chiamati "lancio EHR" o come app autonoma.

Ambiti

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

  • patient
  • user
  • system
Avvia contesto

Descrive il paziente, l'incontro o l'altro contesto in cui viene fatta la richiesta. L'API Cloud Healthcare supporta il contesto di lancio per i pazienti dagli Ambiti per la richiesta di dati di contesto.

Configura il server di autorizzazione per SMART su FHIR

L'API Cloud Healthcare fornisce supporto integrato per SMART sull'applicazione forzata dell'accesso FHIR in base agli ambiti di autorizzazione SMART di input e al contesto del paziente. Gli amministratori del datastore FHIR creano e configurano un server di autorizzazione esterno all'API Cloud Healthcare che concede ambiti di autorizzazione SMART e contesto paziente.

Se un'applicazione client ottiene un token di accesso che rappresenta gli ambiti di autorizzazione SMART concessi e il contesto paziente, l'API Cloud Healthcare non specifica il flusso di lavoro di avvio che 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 passati 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 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 il seguente SMART sulle intestazioni HTTP FHIR quando effettui richieste dal proxy. L'applicazione client non ha bisogno di impostare queste intestazioni perché vengono trasmesse solo 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, se imposti l'ambito di autorizzazione su user/Observation.read, una richiesta può leggere solo una risorsa di osservazione. 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 che possono essere inseriti in un compartimento paziente devono appartenere al compartimento paziente dell'ID paziente fornito. L'API Cloud Healthcare applica questo controllo dell'accesso.
  • X-Authorization-Subject: un identificatore dell'utente finale che accede a SMART sull'applicazione client FHIR. L'API Cloud Healthcare registra l'oggetto in Audit log.
  • X-Authorization-Issuer: l'emittente del token di accesso SMART. L'API Cloud Healthcare registra l'emittente in Audit log.

Configurare i token di accesso al 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 il modo in cui il server di autorizzazione registra il token SMART JWT. 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 SMART JWT, puoi utilizzare l'acceleratore di interoperabilità basato su Apigee HealthAPIx su Apigee per configurare un server di autenticazione che firmi i token JWT.

Esempio di token di accesso

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

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzM4NCJ9.eyJpc3MiOiJzbWFydC50b2tlbi5vcmciLCJpYXQiOjE2MTI4ODQwODUsImV4cCI6MTY0NDQyMDA4NSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiZG9jdG9yLmpvZUBleGFtcGxlLmNvbSIsInNjb3BlIjoidXNlci9QcmFjdGl0aW9uZXIucmVhZCBwYXRpZW50LyouKiIsInBhdGllbnQiOiJwYXRpZW50MTIzIn0.lC0ouNuXNcj7FxQ83NU_MInULWo0wvyiNuaMt2RbFzBOnnMP_IXJdCeNnw3SQzUV

Dopo la decodifica del token di accesso, il token 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"
}

Configura SMART su FHIR nell'API Cloud Healthcare

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

Configura SMARTProxy

Se utilizzi il tuo server di autorizzazione anziché SMARTProxy, salta questa sezione e continua 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 FHIR nell'API Cloud Healthcare di includere token di accesso SMART come parte della gestione delle API e del modello di autorizzazione.

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 attraverso il server di autorizzazione JWT.
  3. SMARTProxy legge gli ambiti e il contesto 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 restituisce quindi una risposta al client tramite SMARTProxy.

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, i client devono utilizzare lo stesso account di servizio. Fai 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 dispone di ampie autorizzazioni di lettura e scrittura.

  • L'indirizzo email principale di Cloud Audit Logs è collegato 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 si utilizza 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, quindi il chiamante originale è oscurato. Per salvare l'utente finale nei metadati dell'audit log, trasmetti l'indirizzo email dell'utente finale nel campo sub del token JWT.

Configura un datastore FHIR

Non è necessario configurare il datastore FHIR che contiene i dati FHIR a cui accedi.

Effettua SMART sulle richieste FHIR

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

Quando si effettua una richiesta, il server di autorizzazione è responsabile della generazione dei token di accesso con l'ambito di autorizzazione SMART pertinente e del contesto di avvio.

Metodi supportati

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

Applicazione forzata dell'accesso alle risorse

Quando si effettua una richiesta SMART su FHIR a un datastore FHIR, controllo dell'accesso avviene nel seguente ordine:

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

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

Le richieste SMART su FHIR a un datastore FHIR devono soddisfare i seguenti requisiti:

  • Specificare il ruolo patient, user o system negli ambiti di autorizzazione SMART. Se fornisci il ruolo patient, devi fornire un contesto relativo al paziente. Il contesto del paziente è un ID logico di una risorsa Paziente. La risorsa Patient deve già esistere nell'archivio FHIR o esistere dopo la richiesta, altrimenti l'API Cloud Healthcare rifiuta la richiesta.

  • 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 compartimento del paziente, come patient/Practitioner.*, il controllo di convalida dell'ambito non va a buon fine e l'API Cloud Healthcare rifiuta l'ambito.

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

  • La presenza di un contesto paziente limita i tipi di risorse idonei per l'alloggiamento del paziente al solo paziente. Ad esempio, una risorsa Osservazione deve avere il riferimento del campo subject alla risorsa Paziente specificata affinché l'osservazione sia accessibile. Controlla i tipi di accesso al compartimento del paziente in Resource CompartmentDefinition - Content per un elenco dei campi di ciascun tipo di risorsa del compartimento del paziente che devono essere indicati al solo paziente affinché la risorsa venga considerata all'interno del vano del paziente.

  • Le richieste possono contenere ambiti patient e user.

  • Non utilizzare l'ambito system con il contesto del paziente, altrimenti la richiesta non andrà 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, controllo dell'accesso si applica a ogni singola risorsa.