Självstudie: Azure Active Directory SMART på FHIR-proxy

Artikel
10/20/2021
5 minuter för att läsa

SMART on FHIR är en uppsättning öppna specifikationer för att integrera partnerprogram med FHIR-servrar och elektroniska journalsystem som har FHIR-gränssnitt. Ett av de huvudsakliga syftena med specifikationerna är att beskriva hur ett program ska identifiera autentiseringsslutpunkter för en FHIR-server och starta en autentiseringssekvens.

Autentiseringen baseras på OAuth2. Men eftersom SMART på FHIR använder namngivningskonventioner för parametrar som inte omedelbart är kompatibla med Azure Active Directory (Azure AD) har Azure API for FHIR en inbyggd Azure AD SMART på FHIR-proxy som möjliggör en delmängd av SMART vid FHIR-startsekvenser. Mer specifikt aktiverar proxyn UPPSTRÖMS-startsekvensen.

Den här självstudien beskriver hur du använder proxyn för att aktivera SMART på FHIR-program med Azure API for FHIR.

Förutsättningar

En instans av Azure API for FHIR
.NET Core 2.2

Konfigurera Azure AD-registreringar

SMART på FHIR kräver att Audience har en identifierar-URI som motsvarar URI för FHIR-tjänsten. Standardkonfigurationen för Azure API for FHIR använder Audience värdet https://azurehealthcareapis.com . Du kan dock också ange ett värde som matchar den specifika URL:en för din FHIR-tjänst (till exempel https://MYFHIRAPI.azurehealthcareapis.com ). Detta krävs när du arbetar med SMART på FHIR-proxyn.

Du behöver också en klientprogramregistrering. De flesta SMART på FHIR-program är javaScript-program med en enda sida. Därför bör du följa anvisningarna för att konfigurera ett offentligt klientprogram i Azure AD.

När du har slutfört de här stegen bör du ha:

En FHIR-server med målgruppen inställd https://MYFHIRAPI.azurehealthcareapis.com på , där är namnet på din MYFHIRAPI Azure API for FHIR instans.
En offentlig klientprogramregistrering. Anteckna program-ID:t för det här klientprogrammet.

Om du vill använda SMART på FHIR måste du först autentisera och auktorisera appen. Första gången du använder SMART på FHIR måste du också få administratörsmedgivande för att ge appen åtkomst till dina FHIR-resurser.

Om du inte har någon ägarskapsroll i appen kontaktar du appens ägare och ber dem att ge administratörsmedgivande åt dig i appen.

Om du har administratörsbehörighet slutför du följande steg för att bevilja administratörsmedgivande till dig själv direkt. (Du kan också ge administratörsmedgivande till dig själv senare när du uppmanas att göra det i appen.) Du kan utföra samma steg för att lägga till andra användare som ägare, så att de kan visa och redigera den här appregistreringen.

Så här lägger du till dig själv eller en annan användare som ägare till en app:

Gå till Azure Active Directory i Azure-portalen.
I den vänstra menyn väljer du Appregistrering.
Sök efter appregistreringen som du skapade och välj den sedan.
I den vänstra menyn under Hantera väljer du Ägare.
Välj Lägg till ägare och lägg sedan till dig själv eller den användare som du vill ge administratörsmedgivande.
Välj Spara.

Aktivera SMART på FHIR-proxyn

Aktivera SMART på FHIR-proxyn i autentiseringsinställningarna för din Azure API for FHIR instans genom att markera kryssrutan SMART på FHIR-proxy:

Val för att aktivera SMART på FHIR-proxyn

Aktivera CORS

Eftersom de flesta SMART på FHIR-program är JavaScript-appar med en sida måste du aktivera CORS (Cross-Origin Resource Sharing) för Azure API for FHIR:

Val för att aktivera CORS

Konfigurera svars-URL:en

SMART på FHIR-proxyn fungerar som en mellanhand mellan SMART på FHIR-appen och Azure AD. Autentiseringssvaret (autentiseringskoden) måste gå till SMART på FHIR-proxyn i stället för själva appen. Proxyn vidarebefordrar sedan svaret till appen.

På grund av det här tvåstegsreläet för autentiseringskoden måste du ange svars-URL:en (återanrop) för azure AD-klientprogrammet till en URL som är en kombination av svars-URL:en för SMART på FHIR-proxyn och svars-URL:en för SMART på FHIR-appen. Den kombinerade svars-URL:en har följande format:

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

I det svaret är aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA en URL-säker base64-kodad version av svars-URL:en för SMART på FHIR-appen. När appen körs lokalt för smart på FHIR-appstartaren är svars-URL:en https://localhost:5001/sampleapp/index.html .

Du kan generera den kombinerade svars-URL:en med hjälp av ett skript så här:

$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

Lägg till svars-URL:en till det offentliga klientprogrammet som du skapade tidigare för Azure AD:

Svars-URL konfigurerad för den offentliga klienten

Skaffa en test patient

Om du Azure API for FHIR och SMART på FHIR-proxyn måste du ha minst en patient i databasen. Om du inte har interagerat med API:et än och du inte har data i databasen kan du läsa Access the FHIR service using Postman to load a patient (Få åtkomst till FHIR-tjänsten med Postman för att läsa in en patient). Anteckna ID:t för en specifik patient.

Ladda ned SMART on FHIR-appstartaren

FHIR-servern med öppen källkod för Azure-lagringsplatsen innehåller en enkel SMART på FHIR-appstartaren och ett exempel på SMART på FHIR-app. I den här självstudien använder du den här SMART på FHIR-startprogrammet lokalt för att testa konfigurationen.

Du kan klona GitHub och gå till programmet med hjälp av följande kommandon:

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

Programmet behöver några konfigurationsinställningar som du kan ange i appsettings.json :

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

Vi rekommenderar att du använder dotnet user-secrets funktionen:

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

Använd det här kommandot för att köra programmet:

dotnet run

Testa SMART på FHIR-proxyn

När du startar SMART på FHIR-appstartaren kan du peka webbläsaren på https://localhost:5001 , där du bör se följande skärm:

SMART på FHIR-appstartaren

När du anger patient-, påträffar- eller utövare-information ser du att startkontexten uppdateras. När du använder Azure API for FHIR är startkontexten helt enkelt ett JSON-dokument som innehåller information om patient, utövare med mera. Den här startkontexten är base64-kodad och skickas till SMART på FHIR-appen som launch frågeparameter. Enligt specifikationen SMART på FHIR är den här variabeln täckande för SMART på FHIR-appen och skickas vidare till identitetsprovidern.

SMART på FHIR-proxyn använder den här informationen för att fylla i fält i tokensvaret. SMART på FHIR-appen kan använda dessa fält för att kontrollera vilken patient den begär data för och hur den återger programmet på skärmen. SMART på FHIR-proxyn stöder följande fält:

patient
encounter
practitioner
need_patient_banner
smart_style_url

De här fälten är avsedda att ge vägledning till appen, men de förmedlar inte någon säkerhetsinformation. Ett SMART på FHIR-program kan ignorera dem.

Observera att startprogrammet SMART på FHIR uppdaterar informationen om start-URL längst ned på sidan. Välj Starta för att starta exempelappen så bör du se något som liknar det här exemplet:

SMART på FHIR-app

Granska tokensvaret för att se hur startkontextfälten skickas till appen.

Nästa steg

I den här självstudien har du konfigurerat Azure Active Directory SMART på FHIR-proxyn. Om du vill utforska användningen av SMART på FHIR-program med Azure API for FHIR och FHIR-servern med öppen källkod för Azure går du till lagringsplatsen för FHIR-serverexempel på GitHub:

FHIR-serverexempel