Condividi tramite

Panoramica di SMART on FHIR

  • Articolo

Importante

L'API di Azure per FHIR verrà ritirata il 30 settembre 2026. Seguire le strategie di migrazione per passare al servizio FHIR® di Servizi per i dati sanitari di Azure entro tale data. A causa del ritiro dell'API di Azure per FHIR, le nuove distribuzioni non saranno consentite a partire dal 1° aprile 2025. Il servizio FHIR di Servizi per i dati sanitari di Azure è la versione evoluta dell'API di Azure per FHIR che consente ai clienti di gestire i servizi FHIR, DICOM e MedTech con integrazioni in altri servizi di Azure.

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 importanti vantaggi, tra cui:

  • 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 descrivono i passaggi per abilitare le applicazioni SMART on FHIR con il servizio FHIR.

Prerequisiti

SMART on FHIR con software open source di esempio (SMART on FHIR(Enhanced))

Passaggio 1: configurare il ruolo utente FHIR SMART

Seguire i passaggi elencati in Gestisci utenti: Assegnare utenti al ruolo. Qualsiasi utente aggiunto al ruolo : "FHIR SMART User" è in grado di accedere al servizio FHIR se le richieste sono conformi alla Guida all'implementazione di SMART on FHIR, ad esempio richiedere un token di accesso, che include un'attestazione fhirUser e un'attestazione di ambito clinico. L'accesso concesso agli utenti in questo ruolo sarà limitato dalle risorse associate al loro fhirUser raggruppamento e dalle restrizioni negli ambiti clinici.

Passaggio 2: integrazione del server FHIR con esempi

Seguire i passaggi disponibili in Azure Health Data and AI Samples OSS (Esempi di intelligenza artificiale e dati di Integrità di Azure). Ciò consente 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 da supporto tecnico Microsoft. Questi esempi possono essere usati per illustrare in che modo Servizi dati di integrità di Azure e altri strumenti open source possono essere usati insieme per dimostrare la conformità ONC (g)(10) usando Microsoft Entra ID come flusso di lavoro del provider di identità.

SMART nel proxy FHIR

Fare clic per espandere

Nota

Si tratta di un altro percorso per SMART on FHIR (Enhanced) come indicato. L'opzione proxy SMART on FHIR abilita solo una sequenza di avvio EHR.

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 viene richiesto nell'app. È possibile completare gli 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

Passaggio 2: 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 dell'API di Azure per FHIR usa un valore https://azurehealthcareapis.com per Audience. Tuttavia, è anche possibile impostare un valore corrispondente all'URL specifico del servizio FHIR, ad esempio https://MYFHIRAPI.azurehealthcareapis.com. Questa operazione è necessaria quando si usa il proxy SMART on FHIR.

Per abilitare il proxy SMART on FHIR nelle impostazioni di autenticazione per l'istanza dell'API di Azure per FHIR, selezionare la casella di controllo PROXY SMART on FHIR.

Screenshot che mostra l'abilitazione del 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.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.

Screenshot che mostra come configurare l'URL di risposta per il client pubblico.

Passaggio 3: ottenere un paziente di prova

Per testare l'API di Azure per FHIR e il proxy SMART on FHIR, è necessario avere almeno un paziente nel database. Se non si è ancora interagito con l'API 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.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

È consigliabile usare la dotnet user-secrets funzionalità .

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

Usare questo comando per eseguire l'applicazione.

dotnet run

Passaggio 5: testare il proxy SMART on FHIR

Dopo aver avviato l'utilità di avvio dell'app SMART on FHIR, è possibile puntare il browser a https://localhost:5001, dove dovrebbe essere visualizzata la schermata seguente.

Screenshot dell'icona di avvio delle app SMART on FHIR.

Quando si immettono informazioni paziente, incontro o operatore , si noti che il contesto di lancio viene aggiornato. Quando si usa l'API di Azure per FHIR, il contesto di avvio è semplicemente un documento JSON che contiene informazioni su pazienti, medici 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.

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.