Configure local RBAC for FHIR
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.
This article explains how to configure the Azure API for FHIR® to use a secondary Microsoft Entra tenant for data access. Use this mode only if it isn't possible for you to use the Microsoft Entra tenant associated with your subscription.
Note
If your FHIR service is configured to use your primary Microsoft Entra tenant associated with your subscription, use Azure RBAC to assign data plane roles.
Add a new service principal or use an existing one
Local role-based access control (RBAC) allows you to use a service principal in the secondary Microsoft Entra tenant with your FHIR server. You can create a new service principal through the Azure portal, PowerShell or CLI commands, or use an existing service principal. The process is also known as application registration. You can review and modify the service principals through Microsoft Entra ID from the portal or using scripts.
The following PowerShell and CLI scripts, which are tested and validated in Visual Studio Code, create a new service principal (or client application), and add a client secret. The service principal ID is used for local RBAC and the application ID and client secret is used to access the FHIR service later.
You can use the Az PowerShell module:
$appname="xxx"
$sp= New-AzADServicePrincipal -DisplayName $appname
$clientappid=sp.ApplicationId
$spid=$sp.Id
#Get client secret which is not visible from the portal
$clientsecret=ConvertFrom-SecureString -SecureString $sp.Secret -AsPlainText
or you can use Azure CLI:
appname=xxx
clientappid=$(az ad app create --display-name $appname --query appId --output tsv)
spid=$(az ad sp create --id $appid --query objectId --output tsv)
#Add client secret with expiration. The default is one year.
clientsecretname=mycert2
clientsecretduration=2
clientsecret=$(az ad app credential reset --id $appid --append --credential-description $clientsecretname --years $clientsecretduration --query password --output tsv)
Configure local RBAC
You can configure the Azure API for FHIR to use a secondary Microsoft Entra tenant in the Authentication blade.
In the authority box, enter a valid secondary Microsoft Entra tenant. Once the tenant is validated, the Allowed object IDs box should be activated and you can enter one or a list of Microsoft Entra service principal object IDs. These IDs can be the identity object IDs of:
- A Microsoft Entra user.
- A Microsoft Entra service principal.
- A Microsoft Entra security group.
You can read the article on how to find identity object IDs for more details.
After entering the required Microsoft Entra object IDs, select Save and wait for changes to be saved before trying to access the data plane using the assigned users, service principals, or groups. The object IDs are granted with all permissions, an equivalent of the "FHIR Data Contributor" role.
The local RBAC setting is only visible from the authentication blade; it isn't visible from the Access Control (IAM) blade.
Note
Only a single tenant is supported for RBAC or local RBAC. To disable the local RBAC function, you can change it back to the valid tenant (or primary tenant) associated with your subscription, and remove all Microsoft Entra object IDs in the "Allowed object IDs" box.
Caching behavior
The Azure API for FHIR caches decisions for up to 5 minutes. If you grant a user access to the FHIR server by adding them to the list of allowed object IDs, or you remove them from the list, you should expect it to take up to five minutes for changes in permissions to propagate.
Next steps
In this article, you learned how to assign FHIR data plane access using an external (secondary) Microsoft Entra tenant. Next learn about additional settings for the Azure API for FHIR.
Note
FHIR® is a registered trademark of HL7 and is used with the permission of HL7.