Condividi tramite

SMART on FHIR

  • Articolo

Applicazioni mediche sostituibili e tecnologie riutilizzabili (SMART on FHIR) è uno standard sanitario attraverso il quale le applicazioni possono accedere alle informazioni cliniche tramite un archivio dati. Aggiunge un livello di sicurezza basato su standard aperti, tra cui OAuth2 e OpenID Connect, alle interfacce FHIR® per abilitare l'integrazione con i sistemi EHR. L'uso di SMART on FHIR offre almeno tre vantaggi importanti:

  • Le applicazioni dispongono di un metodo noto per ottenere l'autenticazione/autorizzazione a un repository FHIR.
  • Gli utenti che accedono a un repository FHIR con SMART on FHIR hanno accesso solo alle risorse associate all'utente, invece di avere accesso a tutti i dati del repository.
  • Gli utenti hanno la possibilità di concedere alle applicazioni l'accesso a un set limitato di dati usando ambiti clinici SMART.

Le esercitazioni seguenti illustrano i passaggi per abilitare le applicazioni SMART on FHIR con il servizio FHIR.

Prerequisiti

SMART on FHIR con esempi di Servizi dati di Integrità di Azure (SMART on FHIR Avanzato)

Passaggio 1: configurare il ruolo utente FHIR SMART

Seguire i passaggi elencati nella sezione Gestire gli utenti: assegnare utenti al ruolo. Qualsiasi utente aggiunto a questo ruolo sarà in grado di accedere al servizio FHIR, purché le richieste siano conformi alla Guida all'implementazione di SMART on FHIR. L'accesso concesso agli utenti in questo ruolo sarà quindi limitato dalle risorse associate al raggruppamento fhirUser e dalle restrizioni negli ambiti clinici.

Nota

La Guida all'implementazione di SMART on FHIR definisce l'accesso ai tipi di risorse FHIR con ambiti. Questi ambiti influiscono sull'accesso di un'applicazione alle risorse FHIR. Un utente con il ruolo utente SMART ha accesso per eseguire interazioni API Lettura nel servizio FHIR. Il ruolo utente SMART non concede l'accesso in scrittura al servizio FHIR.

Passaggio 2: integrazione del server FHIR con esempi

Fare clic su questo collegamento per passare alla soluzione open source Azure Health Data and AI Samples (Esempi di intelligenza artificiale e dati di integrità di Azure). I passaggi elencati nel documento consentono l'integrazione del server FHIR con altri servizi di Azure, ad esempio Gestione API, Funzioni di Azure e altro ancora.

Nota

Gli esempi riguardano un codice open source ed è necessario esaminare le informazioni e le condizioni di licenza in GitHub prima di usarli. Non fanno parte del servizio dati di Integrità di Azure e non sono supportati dal supporto tecnico Microsoft. Questi esempi vengono usati per illustrare in che modo Azure Health Data Services (AHDS) e altri strumenti open source possono essere usati insieme per dimostrare la conformità all'API standardizzata §170.315(g)(10) sui criteri dei servizi ai pazienti e alla popolazione, usando Microsoft Entra ID come flusso di lavoro del provider di identità.

Proxy SMART on FHIR

Fare clic per espandere

Nota

Si tratta di un'altra opzione per SMART on FHIR (Avanzato) con gli esempi AHDS indicati in precedenza. Si consiglia di adottare SMART on FHIR (Avanzato). L'opzione proxy SMART on FHIR è un'opzione legacy. SMART on FHIR (Avanzato) offre funzionalità aggiuntive al proxy SMART on FHIR. SMART on FHIR (Avanzato) soddisfa i requisiti della Guida all'implementazione di SMART on FHIR (v 1.0.0) e dell'API standardizzata §170.315(g)(10) per i servizi ai pazienti e alla popolazione.

Per usare SMART on FHIR, è prima necessario eseguire l'autenticazione e autorizzare l'app. La prima volta che si usa SMART on FHIR, è necessario ottenere anche il consenso amministrativo per consentire all'app di accedere alle risorse FHIR.

Se non si ha un ruolo di proprietà nell'app, contattare il proprietario dell'app e chiedergli di concedere il consenso amministratore per l'utente nell'app.

Se si dispone di privilegi amministrativi, completare la procedura seguente per concedere direttamente il consenso dell'amministratore. È anche possibile concedere il consenso amministratore a se stessi in un secondo momento quando richiesto nell'app. È possibile usare questi stessi passaggi per aggiungere altri utenti come proprietari, in modo che possano visualizzare e modificare la registrazione dell'app.

Per aggiungere se stessi o un altro utente come proprietario di un'app:

  1. Nel portale di Azure passare a Microsoft Entra ID.
  2. Nel menu a sinistra selezionare Registrazione app.
  3. Cercare la registrazione dell'app creata e quindi selezionarla.
  4. Nel menu a sinistra, in Gestisci, selezionare Proprietari.
  5. Selezionare Aggiungi proprietari e quindi aggiungere se stessi o l'utente a cui si vuole concedere il consenso amministratore.
  6. Seleziona Salva

Abilitare il proxy SMART on FHIR

SMART on FHIR richiede che Audience abbia un URI identificatore uguale all'URI del servizio FHIR. La configurazione standard del servizio FHIR usa un valore Audience di https://fhir.azurehealthcareapis.com. Tuttavia, è anche possibile impostare un valore corrispondente all'URL specifico del servizio FHIR, ad esempio https://MYFHIRAPI.fhir.azurehealthcareapis.com. Questa operazione è necessaria quando si usa il proxy SMART on FHIR.

Abilitare il proxy SMART on FHIR nelle impostazioni di Autenticazione dell'istanza dell'API di Azure per FHIR selezionando la casella di controllo Proxy SMART on FHIR.

Il proxy SMART on FHIR funge da intermediario tra l'app SMART on FHIR e Microsoft Entra ID. La risposta di autenticazione (codice di autenticazione) deve essere inviata al proxy SMART on FHIR invece che all'app stessa. Il proxy quindi la inoltra all'app.

A causa di questo inoltro in due passaggi del codice di autenticazione, è necessario impostare l'URL di risposta (callback) per l'applicazione client Microsoft Entra su un URL costituito da una combinazione dell'URL di risposta per il proxy SMART on FHIR e dell'URL di risposta per l'app SMART on FHIR. L'URL di risposta combinato ha il formato seguente.

https://MYFHIRAPI.azurehealthcareapis.com/AadSmartOnFhirProxy/callback/aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA

In questa risposta, aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA è una versione con codifica Base64 URL-safe dell'URL per l'app SMART on FHIR. Per l'utilità di avvio di app SMART on FHIR, quando l'app viene eseguita localmente, l'URL di risposta è https://localhost:5001/sampleapp/index.html.

È possibile generare l'URL di risposta combinato usando uno script simile al seguente.

$replyUrl = "https://localhost:5001/sampleapp/index.html"
$fhirServerUrl = "https://MYFHIRAPI.fhir.azurewebsites.net"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($ReplyUrl)
$encodedText = [Convert]::ToBase64String($bytes)
$encodedText = $encodedText.TrimEnd('=');
$encodedText = $encodedText.Replace('/','_');
$encodedText = $encodedText.Replace('+','-');

$newReplyUrl = $FhirServerUrl.TrimEnd('/') + "/AadSmartOnFhirProxy/callback/" + $encodedText

Aggiungere l'URL di risposta all'applicazione client pubblica creata in precedenza per Microsoft Entra ID.

Passaggio 3: ottenere un paziente di prova

Per testare il servizio FHIR e il proxy SMART on FHIR, è necessario avere almeno un paziente nel database. Se l'API non è ancora stata usata e non si dispone di dati nel database, vedere Accedere al servizio FHIR usando Postman per caricare un paziente. Prendere nota dell'ID di un paziente specifico.

Passaggio 4: scaricare l'utilità di avvio di app SMART on FHIR

Il repository del server FHIR per Azure open source include una semplice utilità di avvio di app SMART on FHIR e un'app SMART on FHIR di esempio. In questa esercitazione usare l'utilità di avvio di SMART on FHIR localmente per testare la configurazione.

È possibile clonare il repository GitHub e passare all'applicazione usando i comandi seguenti.

git clone https://github.com/Microsoft/fhir-server
cd fhir-server/samples/apps/SmartLauncher

Per l'applicazione sono necessarie alcune impostazioni di configurazione, che è possibile specificare in appsettings.json:

{
    "FhirServerUrl": "https://MYFHIRAPI.fhir.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

È consigliabile usare la funzionalità dotnet user-secrets:

dotnet user-secrets set FhirServerUrl https://MYFHIRAPI.fhir.azurehealthcareapis.com
dotnet user-secrets set ClientId <APP-ID>

Usare il seguente comando per eseguire l'applicazione:

dotnet run

Passaggio 5: testare il proxy SMART on FHIR

Dopo aver avviato l'utilità di avvio di app SMART on FHIR, è possibile puntare il browser all'indirizzo https://localhost:5001, dove verrà visualizzato il contenuto seguente:

Screenshot che mostra l'utilità di avvio delle app SMART on FHIR.

Quando si immettono le informazioni per Patient (Paziente), Encounter (Primo contatto) o Practitioner (Medico), si nota che il contesto di avvio è stato aggiornato. Quando si usa il servizio FHIR, il contesto di avvio è semplicemente un documento JSON che contiene informazioni su paziente, medico e altro ancora. Questo contesto di avvio è codificato con Base64 e viene passato all'app SMART on FHIR come parametro di query launch. In base alla specifica SMART on FHIR, questa variabile è opaca per l'app SMART on FHIR e viene passata al provider di identità.

Il proxy SMART on FHIR usa queste informazioni per popolare i campi nella risposta del token. L'app SMART on FHIR può usare questi campi per controllare per quale paziente richiede i dati e come visualizza l'applicazione sullo schermo. Il proxy SMART on FHIR supporta i campi seguenti.

  • patient
  • encounter
  • practitioner
  • need_patient_banner
  • smart_style_url

Questi campi hanno lo scopo di fornire indicazioni all'app, ma non trasmettono informazioni di sicurezza. Un'applicazione SMART on FHIR può ignorarli.

Si noti che l'utilità di avvio di app SMART on FHIR aggiorna le informazioni sull'URL di avvio in fondo alla pagina. Selezionare Avvia per avviare l'app di esempio; verrà visualizzato un contenuto simile al seguente.

Screenshot che mostra l'app SMART on FHIR.

Esaminare la risposta del token per vedere come vengono passati i campi del contesto di avvio all'app.

Eseguire la migrazione da SMART on FHIR Proxy a SMART on FHIR (Avanzato)

Importante

Il proxy SMART on FHIR verrà ritirato nel mese di settembre 2026; passare a SMART on FHIR (Avanzato) entro tale data. A partire da settembre 2026, le applicazioni che si basano sul proxy SMART on FHIR segnaleranno errori durante l'accesso al servizio FHIR.

SMART on FHIR (Avanzato) offre più funzionalità rispetto al proxy SMART on FHIR. SMART on FHIR (Avanzato) può essere considerato conforme ai requisiti della Guida all'implementazione di SMART on FHIR (v 1.0.0) e dell'API standardizzata §170.315(g)(10) per i servizi ai pazienti e alla popolazione. La tabella seguente elenca la differenza tra il proxy SMART on FHIR e SMART on FHIR (Avanzato).

Funzionalità SMART on FHIR (Avanzato) SMART nel proxy FHIR
Supporta l'avvio autonomo Sì No
Supporta l'avvio EHR Sì Sì
Supporta restrizioni di ambito Sì No
Si basa su prodotti Azure di prima parte Sì, i prodotti Azure come Gestione API di Azure devono essere integrati No
Supporto tecnico Microsoft Supportato per il servizio FHIR. Il supporto di esempio open source deve essere segnalato e monitorato tramite GitHub Supportato per il servizio FHIR

Passaggi della migrazione

  • Passaggio 1: configurare il ruolo utente FHIR SMART. Seguire i passaggi elencati nella sezione Gestire utenti: assegnare utenti al ruolo. Qualsiasi utente aggiunto al ruolo utente SMART è in grado di accedere al servizio FHIR, se le richieste sono conformi alla Guida all'implementazione di SMART on FHIR.
  • Passaggio 2: distribuire l'esempio SMART on FHIR in Esempi di dati di Integrità di Azure e sistemi operativi di intelligenza artificiale
  • Passaggio 3: aggiornare l'endpoint dell'URL del servizio FHIR a '{{BASEURL_FROM_APIM}}/smart'.
  • Passaggio 4: deselezionare l'impostazione proxy SMART on FHIR nel pannello Autenticazione per il servizio FHIR.

Se hai domande, puoi ricevere risposte dagli esperti della community in Microsoft Q&A. Per il supporto tecnico, è anche possibile creare una richiesta di supporto.

Passaggi successivi

Dopo aver appreso come abilitare la funzionalità SMART on FHIR, vedere la pagina degli esempi di ricerca per informazioni dettagliate su come eseguire ricerche usando parametri di ricerca, modificatori e altri metodi di ricerca FHIR.

Esempi di ricerca FHIR

Nota

FHIR® è un marchio registrato di HL7 ed è usato con l'autorizzazione di HL7.