Edit

Register the Microsoft Entra apps for Azure API for FHIR

  • Article

Important

Azure API for FHIR will be retired on September 30, 2026. Follow the migration strategies to transition to Azure Health Data Services FHIR service by that date. Due to the retirement of Azure API for FHIR, new deployments won't be allowed beginning April 1, 2025. Azure Health Data Services FHIR service is the evolved version of Azure API for FHIR that enables customers to manage FHIR, DICOM, and MedTech services with integrations into other Azure services.

You have several configuration options to choose from when you're setting up the Azure API for FHIR or the FHIR Server for Azure (OSS). For open source, you'll need to create your own resource application registration. For Azure API for FHIR, this resource application is created automatically.

Application registrations

In order for an application to interact with Microsoft Entra ID, it needs to be registered. In the context of the FHIR server, there are two kinds of application registrations to discuss:

  1. Resource application registrations.
  2. Client application registrations.

Resource applications are representations in Microsoft Entra ID of an API or resource that is secured with Microsoft Entra ID, specifically it would be the Azure API for FHIR. A resource application for Azure API for FHIR will be created automatically when you provision the service, but if you're using the open-source server, you'll need to register a resource application in Microsoft Entra ID. This resource application will have an identifier URI. It's recommended that this URI be the same as the URI of the FHIR server. This URI should be used as the Audience for the FHIR server. A client application can request access to this FHIR server when it requests a token.

Client applications are registrations of the clients that will be requesting tokens. Often in OAuth 2.0, we distinguish between at least three different types of applications:

  1. Confidential clients, also known as web apps in Microsoft Entra ID. Confidential clients are applications that use authorization code flow to obtain a token on behalf of a signed in user presenting valid credentials. They're called confidential clients because they're able to hold a secret and will present this secret to Microsoft Entra ID when exchanging the authentication code for a token. Since confidential clients are able to authenticate themselves using the client secret, they're trusted more than public clients and can have longer lived tokens and be granted a refresh token. Read the details on how to register a confidential client. Note it's important to register the reply URL at which the client will be receiving the authorization code.
  2. Public clients. These are clients that can’t keep a secret. Typically this would be a mobile device application or a single page JavaScript application, where a secret in the client could be discovered by a user. Public clients also use authorization code flow, but they aren't allowed to present a secret when obtaining a token and they may have shorter lived tokens and no refresh token. Read the details on how to register a public client.
  3. Service clients. These clients obtain tokens on behalf of themselves (not on behalf of a user) using the client credentials flow. They typically represent applications that access the FHIR server in a non-interactive way. An example would be an ingestion process. When using a service client, it isn't 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. Read the details on how to register a service client

Next steps

In this overview, you've gone through the types of application registrations you may need in order to work with a FHIR API.

Based on your setup, refer to the how-to-guides to register your applications:

After you've registered your applications, you can deploy Azure API for FHIR.

Deploy Azure API for FHIR

FHIR® is a registered trademark of HL7 and is used with the permission of HL7.