FHIR is a standard for describing health care data format and elements. It helps defining how health data can be exchanged between different healthcare systems.
Azure API for FHIR is a PaaS offering in Microsoft cloud. So, you can create and deploy a FHIR service in minutes to leverage the elastic scale of the cloud.
I highly recommend that you should watch the this video by Michael Hansen to get the overview of Azure API for FHIR.
As per documentation these are few key benefits of Azure API for FHIR:
- Managed FHIR service, provisioned in the cloud in minutes
- Enterprise-grade, FHIR®-based endpoint in Azure for data access, and storage in FHIR® format
- High performance, low latency
- Secure management of Protected Health Data (PHI) in a compliant cloud environment
- SMART on FHIR for mobile and web implementations
- Control your own data at scale with Role-Based Access Control (RBAC)
- Audit log tracking for access, creation, modification, and reads within each data store
In this blog post we will explore
- How to create and deploy Azure API for FHIR?
- Authorization and access control overview
- Why do we need to register a client application?
- What are the ways to access Azure API for FHIR from Postman?
- Creating and managing FHIR resources using Postman
Create and deploy Azure API for FHIR
First, make sure Healthcare API service is enabled in your subscription. Login to your Azure subscription and choose the subscription in which you want to create Azure API for FHIR.
On the Subscription blade, choose Resource providers under settings and then look for Microsoft.HealthcareApis, click on register if not already registered.
Once the registration of Microsoft.HealthcareApis on your subscription is complete and you can go ahead and provision the Azure FHIR API.
Go to Home and search for “Azure API for FHIR”.
Click on Create button to create a new Azure API for FHIR account:
Populate the Resource group name and the Account name to be created. Next click on Review + create button.
Once provisioning is completed, you would see new FHIR API account listed under your Resource Group as shown below.
Click on the newly created Azure API for FHIR account i.e. healthdataonfhir to see the overview of it
You can use the FHIR metadata endpoint to validate the successful provision of new FHIR API account. The screenshot below shows the capability statement fetched in Postman using the url: https://healthdataonfhir.azurehealthcareapis.com/metadata
Now if you try to fetch a patient FHIR resource you would get an authentication error as shown below. We will talk about authentication and authorization in next section.
Access Control (Authentication & Authorization) overview for FHIR API
Healthcare data need to be secured and can be accessed only by authorized users or applications. The Azure API for FHIR is secured using OAuth 2.0 identity provider i.e. Azure Active Directory.
So, access token would be required for a client application to access Azure API for FHIR. It is important to note that Azure Active Directory is responsible for authentication of client applications / users and issuing an access token. Then access token gets validated by Azure API for FHIR to check if it is a valid one with appropriate claims.
Following are the four steps flow to access FHIR API using authorization code flow.
1. The client application sends the request to the /authorize endpoint of Azure AD and it will get redirected to a sign in page for user authentication. Upon successful authentication, an authorization code is returned to the client. The client application must be registered and configured with reply URL so that Azure AD can return the authorization code. We will discuss about the registration of a client application in the next section.
2. Next, the client application sends the request to the /token endpoint of Azure AD by providing the authorization code received in step 1. The client application may also have to provide a client secret (the applications password). See details on obtaining an access token
3. Now, the client application can use the token received in step 2 to make a call to Azure API for FHIR to get the resources, for example, GET /Patient to search all patients.
4. Azure API for FHIR would validate the token if it contains all the appropriate claims. If validation is successful it would return a FHIR bundle with results to the client.
Register a client application
Now that we have covered the overview of how authentication and authorization work for Azure API for FHIR, the next step would be to register a client application in Azure Active Directory. Client applications are registrations of the clients that will be requesting tokens.
To access the Azure API for FHIR from Postman, we would need to create a public client application.
Follow the steps below for app registration in Azure Portal.
1. Navigate to Azure Active Directory.
- Select App Registration –> New Registration
- Provide a name for your application and set up the redirect URI to https://www.getpostman.com/oauth2/callback. The redirect URI is where authentication codes will be returned to the client application. In our case it would be Postman.
- Click on Register.
Once your client application is registered, copy the Application (client) ID and the Directory (tenant) ID from the Overview Page. You will need these two values later when accessing the client.
Next step is to set the API Permission.
1. Select API permissions and click Add a permission.
2. Under APIs my organization uses, search for Azure Healthcare APIs.
3. Select user_impersonation and click add permissions.
Once you click Add permissions, you would see the message “You are editing permission(s) to your application, users will have to consent even if they’ve already done so previously.” as shown below.
Make sure you grant permission to access the Azure Healthcare APIs.
Now you are good to go ahead and start testing this client application to access FHIR API in Postman, which we will see in detail in next section.
If you also want to access the FHIR API from a C# console application, then you need to create a service client application.
Service client application is required to obtain an access token without interactive authentication of a user. An example would be an ingestion process of health data to FHIR. When using a service client, it is not necessary to start the process of getting a token with a call to the /authorize endpoint. A service client can go straight to the /token endpoint and present client ID and client secret to obtain a token.
Below is the code snippet example to access the by directly calling /token and passing client ID and client secret in a C# console app.
To set up the service client application, there would be one more step in addition to all the steps of public client application registration. As shown above in the code snippet, the service client needs a secret (password), which will be used to get tokens.
Select Certificates & secrets –> New client secret
Provide the duration of the secret.
Once secret is generated, make sure you copy and store it securely. It will only be displayed once in the portal.
Once the client app is registered successfully, you would need to Configure Azure RBAC for FHIR so that the client app has the access to Azure API for FHIR
Testing the Azure API for FHIR with Postman
In the previous steps, we deployed the Azure API for FHIR and registered the client application. Now it is time to test the Azure API for FHIR with Postman.
You can use either authorization code flow or client credentials flow to access the resource from Azure API for FHIR.
For authorization code flow refer this link.
In this post, I would go with client credential flow.
Use the URL shown below, and replace the {{tenantId}} variable with your Directory (tenant) ID
Under Authorization – select No Auth
Under Headers – Make sure you have the following keys.
Under Body – make sure you set the following keys. Replace {{resource}} variable value with https://healthdataonfhir.azurehealthcareapis.com
If everything you provided so far is correct, then you should get the token is response as shown below.
Now you can use the above token to create and manage FHIR resources in the Azure API for FHIR. For example, below is the screen shot of successfully Patient resource creation.
Summary:
This blog post provides step by step details for how to start working with Azure API for FHIR. It covers
- How to create and deploy Azure API for FHIR?
- Authorization and access control overview
- Why do we need to register a client application?
- What are the ways to access Azure API for FHIR from Postman?
- Creating and managing FHIR resources using Postman