|
| 1 | +--- |
| 2 | +title: SMART on FHIR - Azure Health Data Services |
| 3 | +description: This tutorial describes how to use a proxy to enable SMART on FHIR applications with the FHIR service. |
| 4 | +services: healthcare-apis |
| 5 | +ms.service: healthcare-apis |
| 6 | +ms.subservice: fhir |
| 7 | +ms.topic: tutorial |
| 8 | +ms.author: kesheth |
| 9 | +author: expekesheth |
| 10 | +ms.date: 11/10/2022 |
| 11 | +--- |
| 12 | + |
| 13 | +# SMART on FHIR |
| 14 | + |
| 15 | +[SMART on FHIR](https://docs.smarthealthit.org/) is a set of open specifications to integrate partner applications with FHIR servers and electronic medical records systems that have Fast Healthcare Interoperability Resources (FHIR®) interfaces. One of the main purposes of the specifications is to describe how an application should discover authentication endpoints for an FHIR server and start an authentication sequence. |
| 16 | + |
| 17 | +Authentication is based on OAuth2. But because SMART on FHIR uses parameter naming conventions that aren’t immediately compatible with Azure Active Directory (Azure AD), the Azure API for FHIR has a built-in Azure AD SMART on FHIR proxy that enables a subset of the SMART on FHIR launch sequences. Specifically, the proxy enables the [EHR launch sequence](https://hl7.org/fhir/smart-app-launch/#ehr-launch-sequence). |
| 18 | + |
| 19 | +This tutorial describes how to use the proxy to enable SMART on FHIR applications with FHIR Service. |
| 20 | + |
| 21 | +## Prerequisites |
| 22 | + |
| 23 | +- An instance of the FHIR Service |
| 24 | +- [.NET Core 2.2](https://dotnet.microsoft.com/download/dotnet-core/2.2) |
| 25 | + |
| 26 | +## Configure Azure AD registrations |
| 27 | + |
| 28 | +SMART on FHIR requires that `Audience` has an identifier URI equal to the URI of the FHIR service. The standard configuration of the FHIR service uses an `Audience` value of `https://azurehealthcareapis.com`. However, you can also set a value matching the specific URL of your FHIR service (for example `https://MYFHIRAPI.fhir.azurehealthcareapis.com`). This is required when working with the SMART on FHIR proxy. |
| 29 | + |
| 30 | +You'll also need a client application registration. Most SMART on FHIR applications are single-page JavaScript applications. So you should follow the instructions for configuring a [public client application in Azure AD](register-public-azure-ad-client-app.md). |
| 31 | + |
| 32 | +After you complete these steps, you should have: |
| 33 | + |
| 34 | +- A FHIR server with the audience set to `https://MYFHIRAPI.fhir.azurehealthcareapis.com`, where `MYFHIRAPI` is the name of your FHIR service instance. |
| 35 | +- A public client application registration. Make a note of the application ID for this client application. |
| 36 | + |
| 37 | +### Set admin consent for your app |
| 38 | + |
| 39 | +To use SMART on FHIR, you must first authenticate and authorize the app. The first time you use SMART on FHIR, you also must get administrative consent to let the app access your FHIR resources. |
| 40 | + |
| 41 | +If you don't have an ownership role in the app, contact the app owner and ask them to grant admin consent for you in the app. |
| 42 | + |
| 43 | +If you do have administrative privileges, complete the following steps to grant admin consent to yourself directly. (You also can grant admin consent to yourself later when you're prompted in the app.) You can complete the same steps to add other users as owners, so they can view and edit this app registration. |
| 44 | + |
| 45 | +To add yourself or another user as owner of an app: |
| 46 | + |
| 47 | +1. In the Azure portal, go to Azure Active Directory. |
| 48 | +2. In the left menu, select **App Registration**. |
| 49 | +3. Search for the app registration you created, and then select it. |
| 50 | +4. In the left menu, under **Manage**, select **Owners**. |
| 51 | +5. Select **Add owners**, and then add yourself or the user you want to have admin consent. |
| 52 | +6. Select **Save**. |
| 53 | + |
| 54 | +## Enable the SMART on FHIR proxy |
| 55 | + |
| 56 | +Enable the SMART on FHIR proxy in the **Authentication** settings for your FHIR instance by selecting the **SMART on FHIR proxy** check box. |
| 57 | +Enable CORS : Because most SMART on FHIR applications are single-page JavaScript apps, you need to [enable cross-origin resource sharing (CORS)](configure-cross-origin-resource-sharing.md) |
| 58 | +Configure the reply URL: The SMART on FHIR proxy acts as an intermediary between the SMART on FHIR app and Azure AD. The authentication reply (the authentication code) must go to the SMART on FHIR proxy instead of the app itself. The proxy then forwards the reply to the app. |
| 59 | + |
| 60 | +Because of this two-step relay of the authentication code, you need to set the reply URL (callback) for your Azure AD client application to a URL that is a combination of the reply URL for the SMART on FHIR proxy and the reply URL for the SMART on FHIR app. The combined reply URL takes this form: |
| 61 | + |
| 62 | +```http |
| 63 | +https://MYFHIRAPI.azurehealthcareapis.com/AadSmartOnFhirProxy/callback/aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA |
| 64 | +``` |
| 65 | + |
| 66 | +In that reply, `aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA` is a URL-safe, base64-encoded version of the reply URL for the SMART on FHIR app. For the SMART on FHIR app launcher, when the app is running locally, the reply URL is `https://localhost:5001/sampleapp/index.html`. |
| 67 | + |
| 68 | +You can generate the combined reply URL by using a script like this: |
| 69 | + |
| 70 | +```PowerShell |
| 71 | +$replyUrl = "https://localhost:5001/sampleapp/index.html" |
| 72 | +$fhirServerUrl = "https://MYFHIRAPI.azurewebsites.net" |
| 73 | +$bytes = [System.Text.Encoding]::UTF8.GetBytes($ReplyUrl) |
| 74 | +$encodedText = [Convert]::ToBase64String($bytes) |
| 75 | +$encodedText = $encodedText.TrimEnd('='); |
| 76 | +$encodedText = $encodedText.Replace('/','_'); |
| 77 | +$encodedText = $encodedText.Replace('+','-'); |
| 78 | +
|
| 79 | +$newReplyUrl = $FhirServerUrl.TrimEnd('/') + "/AadSmartOnFhirProxy/callback/" + $encodedText |
| 80 | +``` |
| 81 | + |
| 82 | +Add the reply URL to the public client application that you created earlier for Azure AD |
| 83 | + |
| 84 | +<!------> |
| 85 | + |
| 86 | +## Get a test patient |
| 87 | + |
| 88 | +To test the FHIR service and the SMART on FHIR proxy, you'll need to have at least one patient in the database. If you've not interacted with the API yet, and you don't have data in the database, see [Access the FHIR service using Postman](./../fhir/use-postman.md) to load a patient. Make a note of the ID of a specific patient. |
| 89 | + |
| 90 | +## Download the SMART on FHIR app launcher |
| 91 | + |
| 92 | +The open-source [FHIR Server for Azure repository](https://github.com/Microsoft/fhir-server) includes a simple SMART on FHIR app launcher and a sample SMART on FHIR app. In this tutorial, use this SMART on FHIR launcher locally to test the setup. |
| 93 | + |
| 94 | +You can clone the GitHub repository and go to the application by using these commands: |
| 95 | + |
| 96 | +```PowerShell |
| 97 | +git clone https://github.com/Microsoft/fhir-server |
| 98 | +cd fhir-server/samples/apps/SmartLauncher |
| 99 | +``` |
| 100 | + |
| 101 | +The application needs a few configuration settings, which you can set in `appsettings.json`: |
| 102 | + |
| 103 | +```json |
| 104 | +{ |
| 105 | + "FhirServerUrl": "https://MYFHIRAPI.fhir.azurehealthcareapis.com", |
| 106 | + "ClientId": "APP-ID", |
| 107 | + "DefaultSmartAppUrl": "/sampleapp/launch.html" |
| 108 | +} |
| 109 | +``` |
| 110 | + |
| 111 | +We recommend that you use the `dotnet user-secrets` feature: |
| 112 | + |
| 113 | +```PowerShell |
| 114 | +dotnet user-secrets set FhirServerUrl https://MYFHIRAPI.fhir.azurehealthcareapis.com |
| 115 | +dotnet user-secrets set ClientId <APP-ID> |
| 116 | +``` |
| 117 | + |
| 118 | +Use this command to run the application: |
| 119 | + |
| 120 | +```PowerShell |
| 121 | +dotnet run |
| 122 | +``` |
| 123 | + |
| 124 | +## Test the SMART on FHIR proxy |
| 125 | + |
| 126 | +After you start the SMART on FHIR app launcher, you can point your browser to `https://localhost:5001`, where you should see the following screen: |
| 127 | + |
| 128 | + |
| 129 | + |
| 130 | +When you enter **Patient**, **Encounter**, or **Practitioner** information, you'll notice that the **Launch context** is updated. When you're using the FHIR service, the launch context is simply a JSON document that contains information about patient, practitioner, and more. This launch context is base64 encoded and passed to the SMART on FHIR app as the `launch` query parameter. According to the SMART on FHIR specification, this variable is opaque to the SMART on FHIR app and passed on to the identity provider. |
| 131 | + |
| 132 | +The SMART on FHIR proxy uses this information to populate fields in the token response. The SMART on FHIR app *can* use these fields to control which patient it requests data for and how it renders the application on the screen. The SMART on FHIR proxy supports the following fields: |
| 133 | + |
| 134 | +* `patient` |
| 135 | +* `encounter` |
| 136 | +* `practitioner` |
| 137 | +* `need_patient_banner` |
| 138 | +* `smart_style_url` |
| 139 | + |
| 140 | +These fields are meant to provide guidance to the app, but they don't convey any security information. A SMART on FHIR application can ignore them. |
| 141 | + |
| 142 | +Notice that the SMART on FHIR app launcher updates the **Launch URL** information at the bottom of the page. Select **Launch** to start the sample app, and you should see something like this sample: |
| 143 | + |
| 144 | + |
| 145 | + |
| 146 | +Inspect the token response to see how the launch context fields are passed on to the app. |
| 147 | + |
| 148 | + |
| 149 | +FHIR® is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7. |
0 commit comments