Uredi

Use Microsoft Entra External ID to access the FHIR service

Healthcare organizations can use Microsoft Entra External ID with the FHIR® service in Azure Health Data Services to grant access to their applications and users.

Create a Microsoft Entra External ID tenant for the FHIR service

Creating a Microsoft Entra External ID tenant for the FHIR service sets up a secure infrastructure for managing user identities in your healthcare applications.

If you already created a Microsoft Entra External ID tenant, you can skip to Add a test user to the Microsoft Entra External ID tenant.

Use PowerShell or Azure CLI to deploy the ARM template to deploy a Microsoft Entra external ID tenant programmatically to an Azure subscription. For more information about syntax, properties, and usage of the template, see Deploy an instance of Microsoft Entra External ID.

Run the code in Azure Cloud Shell, or locally in PowerShell, Azure CLI, or Visual Studio Code to deploy the FHIR service to the Microsoft Entra External ID tenant.

Use the following PowerShell script to deploy a Microsoft Entra External ID tenant. Make sure to replace the variables in the script with your own values before running it. Don't include .onmicrosoft.com in the directoryName variable.

The following script signs in to Azure, creates a resource group, and deploys the ARM template that creates a Microsoft Entra External ID tenant. If you want to use an existing resource group, skip the "create resource group" step, or comment out the line starting with New-AzResourceGroup.

If you are using a locally stored ARM template, replace the -TemplateUri parameter with -TemplateFile and provide the local path to the ARM template JSON file.

Replace the <placeholder> values in the script with your actual Azure subscription details and desired configuration.

### variables
$tenantid="<your tenant id>"
$subscriptionid="<your subscription id>"
$resourceGroupName="<your resource group name>"
$location="<your desired location>"
$directoryName="<your entra external id tenant name>"

### login to azure
Connect-AzAccount -Tenant $tenantid -SubscriptionId $subscriptionid 

# create the resource group
New-AzResourceGroup -Name $resourceGroupName -Location $location

# deploy the resource
New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri https://raw.githubusercontent.com/Azure-Samples/azure-health-data-and-ai-samples/refs/heads/main/samples/fhir-aad-entra-external/entra-external-arm-template.json -directoryName $directoryName

Add a test user to the Microsoft Entra External ID tenant

Note

You're asked to set up multi-factor authentication (MFA) when signing in for the first time.

You need a test user in your Microsoft Entra External ID tenant to associate with a specific patient resource in the FHIR service and to verify that the authentication flow works as expected.

  1. Sign in to the Microsoft Entra admin center.

  2. If you have access to multiple tenants, use the Settings icon Admin center settings icon. in the top menu to switch to your external tenant from the Directories + subscriptions menu. Here you're asked for MFA setup.

  3. In the Users section of the Microsoft Entra admin center, select + New user, and then choose Create new user.

    Screenshot of the test user creation page in Microsoft Entra External ID.

  4. On the Basics tab, enter the User principal name and Display name, and then select Review + create.

    Screenshot of the Create new user pane in Microsoft Entra External ID.

  5. Review the information you entered to validate the input, and then select Create to create the user.

Use the fhirUser custom user attribute to link a user in Microsoft Entra External ID with a corresponding patient resource in the FHIR service. In this example, you create a user named Test Patient1 in the Microsoft Entra External ID tenant. In a later step, you create a patient resource in the FHIR service. You associate the Test Patient1 user with the patient resource by setting the fhirUser attribute to the patient's FHIR resource identifier. For more information about custom attributes in Microsoft Entra External ID, see
User flow custom attributes in Microsoft Entra External ID.

  1. In the Microsoft Entra admin center, go to Entra ID > External Identities in the left pane.

  2. Select Custom user attributes.

  3. Select + Add.

  4. In Add custom attribute:

    1. In the Name field, enter fhirUser (case-sensitive).

    2. From the Data Type dropdown list, select String.

    3. In the Description field, enter a description for the custom attribute. For example, "The fully qualified FHIR resource ID associated with the user. (for example, Patient Resource)".

    4. Select Create.

    Screenshot of the creation of fhirUser custom attribute in Microsoft Entra External ID.

Create a new user flow in Microsoft Entra External ID

User flows define the sequence of steps users must follow to sign in. In this example, you define a user flow so that when a user signs in, the access token includes the fhirUser claim. For more information, see Create user flows and custom policies in Microsoft Entra External ID.

  1. On Entra ID > External Identities, select User flows.

  2. Select + New user flow.

    Screenshot of the creation of a new user flow in Microsoft Entra External ID.

  3. Enter a name for the user flow that's unique to the Microsoft Entra External ID tenant. The name doesn't need to be globally unique. In this example, the user flow name is USER_FLOW_1. Make note of the name.

  4. Under Identity providers, keep Email with password selected (default).

    Screenshot of Microsoft Entra External ID user flow configuration.

  5. Under User attributes, select Show more to view more attributes.

  6. Select fhirUser.

  7. Select Ok.

    Screenshot of user flow configuration and selection of fhirUser attribute in Microsoft Entra External ID.

  8. Select Create.

Create a Microsoft Entra External Resource Application

The Microsoft Entra External ID resource application handles authentication requests from your healthcare application to Microsoft Entra External ID.

  1. In the Microsoft Entra admin center, go to Entra ID > App registrations.

  2. Select + New registration.

    Screenshot of Microsoft Entra External ID new application.

  3. In Register an application:

    • Enter a display name. This example uses FHIR Service.

    • In the Redirect URI (recommended) drop-down list, select Public client/native (mobile & desktop). Enter the callback URI. This callback URI is for testing purposes.

    • Select Register. Wait for the application registration to complete. The browser automatically navigates to the application Overview page.

    Screenshot of the application registration page in Microsoft Entra External ID.

Configure API permissions for the app

  1. In the left pane, select App registrations, select the application you registered, and then select Manifest.

  2. Scroll until you find the oauth2PermissionScopes array in the json code in Microsoft Graph App Manifest (New). Replace the array with one or more values from the oauth2Permissions.json file. You can copy the entire array or individual permissions.

If you add a permission to the list, any user in the Microsoft Entra External ID tenant can get an access token with that API permission.

If a permission level isn't appropriate for all users, don't include it in the permission array. For example, the patient.all.read permission grants read access to all patient resources in the FHIR service. If you don't want all users to have this level of access, don't include patient.all.read in the oauth2PermissionScopes array.

  1. In the same manifest, set the acceptMappedClaims property to true. This setting enables the app to receive custom claims, like fhirUser in the token.

  2. Select Save.

    Screenshot of the oauth2PermissionScopes array being edited in the app manifest.

Expose the web API and assign an application ID URI

  1. On App registrations select the application you registered, and then select Expose an API.

  2. For the Application ID URI section, select Add.

  3. By default, the Application ID URI field is populated with the application (client) ID. Change the value if desired.

  4. Select Save.

    Screenshot of the Application ID URI being set in Microsoft Entra External ID.

  5. Select API permissions and then select + Add a permission.

    Screenshot of Microsoft Entra External ID API permission.

  6. On Request API permissions, select APIs my organization uses.

  7. Select the resource application from the list. For this example, select the application you registered in the previous section with the name FHIR Service.

    Screenshot of Microsoft Entra External ID API permissions with APIs used.

  8. Enter Patient in the search box to filter the permissions list to show only permissions related to patient resources in the FHIR service.

  9. In the Patient section, select at least one permission. In this example, the permission patient.all.read is selected, which means a user that requests an access token with the scope patient.all.read has Read privileges (patient.all.read) for all FHIR resources (patient.all.read) in the Patient compartment (patient.all.read) For more information, see Patient compartment.

  10. Select Add permissions.

    Screenshot of Microsoft Entra External ID API permissions with permissions added.

  11. On API permissions in the Configured permissions section, select Grant admin consent.

    Screenshot of Microsoft Entra External ID API permissions for admin consent.

Configure Single sign-on (Preview) for the app

  1. Go to Entra External ID > Enterprise apps.

  2. Select your registered application from the list.

    Screenshot of the Enterprise applications page in Microsoft Entra External ID.

  3. In your application’s pane, under Manage, select Single sign-on (Preview).

  4. In the Attributes & Claims section, select Edit to configure the single sign-on settings.

    Screenshot of the Single sign-on (Preview) configuration page in Microsoft Entra External ID.

  5. Under Attributes & Claims, select + Add new claim.

    Screenshot of the Add new claim page in Microsoft Entra External ID.

  6. Configure the new claim:

    1. Name: fhirUser

    2. Source: Select Directory schema extension

    3. Source attribute: Select b2c-extensions-app

    Screenshot of the manage claim configuration in Microsoft Entra External ID.

  7. Select Select. This action opens the Add Extension Attributes window.

    Screenshot of the select application configuration in Microsoft Entra External ID.

  8. In the list, select the user.fhirUser attribute.

  9. Select Add to include the attribute in the claim.

    Screenshot of selection of the user.fhirUser attribute during claim configuration in Microsoft Entra External ID.

  10. Select Save.

    Screenshot of the saved fhirUser claim in the directory extension schema.

Deploy the FHIR service with Microsoft Entra External ID as the identity provider

When you deploy the FHIR service with Microsoft Entra External ID as the identity provider, the FHIR service authenticates users by using their Microsoft Entra External ID credentials. This authentication method ensures that only authorized users can access sensitive patient information.

Get the Microsoft Entra External ID authority and client ID

Use the authority and client ID (or application ID) parameters to configure the FHIR service to use a Microsoft Entra External ID tenant as an identity provider.

  1. Create the authority string by using the name of the Microsoft Entra External ID tenant and the name of the user flow. Replace your tenant name and tenant ID in the following URL.

    https://<your-external-id-tenant-name>.ciamlogin.com/<your-external-id-tenant-id>/v2.0

  2. Test the authority string by making a request to the .well-known/openid-configuration endpoint. Enter the string into a browser to confirm it navigates to the OpenId Configuration JSON file. If the OpenId Configuration JSON fails to load, make sure the Microsoft Entra External ID tenant name and Microsoft Entra External ID tenant ID are correct. Replace your tenant name and tenant ID in the following URL.

    https://<your-external-id-tenant-name>.ciamlogin.com/<your-external-id-tenant-id>/v2.0/.well-known/openid-configuration

  3. Retrieve the client ID from the resource application overview page.

    Screenshot of the Application (client) ID overview page.

Deploy the FHIR service by using an ARM template

To simplify deploying the FHIR service, use an ARM template. Use PowerShell or Azure CLI to deploy the ARM template to your Azure subscription.

Use the following PowerShell script to deploy the FHIR service with Microsoft Entra External ID as the identity provider. Set the $smartAuthorityUrl variable to the authority string you created in the previous section, and set the $smartClientId variable to the client ID of the resource application you created in your external ID tenant.

The following script signs in to Azure, creates a resource group, and deploys the ARM template that creates the FHIR service with Microsoft Entra External ID as the identity provider. If you want to use an existing resource group, skip the "create resource group" step, or comment out the line starting with New-AzResourceGroup.

If you are using a locally stored ARM template, replace the -TemplateUri parameter with -TemplateFile and provide the local path to the ARM template JSON file.

Replace the <placeholder> values in the script with your actual Azure subscription details and desired configuration for the FHIR service deployment.

### variables
$tenantid="<your tenant id>"
$subscriptionid="<your subscription id>"
$resourcegroupname="<your resource group name>"
$region="<your desired region>"
$workspacename="<your workspace name>"
$fhirServiceName="<your fhir service name>"
$smartAuthorityUrl="<your authority>"
$smartClientId="<your client id>"

### Login to Azure
Connect-AzAccount

#Connect-AzAccount SubscriptionId $subscriptionid
Set-AzContext -Subscription $subscriptionid
Connect-AzAccount -Tenant $tenantid -SubscriptionId $subscriptionid

### create resource group
New-AzResourceGroup -Name $resourcegroupname -Location $region

### deploy the resource
New-AzResourceGroupDeployment -ResourceGroupName $resourcegroupname -TemplateUri https://raw.githubusercontent.com/Azure-Samples/azure-health-data-and-ai-samples/refs/heads/main/samples/fhir-aad-b2c/fhir-service-arm-template.json -tenantid $tenantid -region $region -workspaceName $workspacename -fhirServiceName $fhirservicename -smartAuthorityUrl $smartAuthorityUrl -smartClientId $smartClientId

Validate Microsoft Entra External ID users can access FHIR resources

The validation process involves creating a patient resource in the FHIR service, linking the patient resource to the Microsoft Entra External ID user, and configuring REST Client to get an access token for External ID users. After the validation process is complete, you can fetch the patient resource by using the External ID test user.

Use REST Client to get an access token

For steps to obtain the proper access to the FHIR service, see Access the FHIR service using REST Client.

When you follow the steps in the Get the FHIR patient data section, the request returns an empty response because the FHIR service is new and doesn't have any patient resources.

Create a patient resource in the FHIR service

Users in the Microsoft Entra External ID tenant can't read any resources until you link the user (such as a patient or practitioner) to a FHIR resource. A user with the FhirDataWriter or FhirDataContributor role in the Microsoft Entra ID where the FHIR service is tenanted must perform this step.

  1. Create a patient with a specific identifier by changing the method to PUT and executing a request to {{fhirurl}}/Patient/1 with this body:
{
    "resourceType": "Patient",
    "id": "1",
    "name": [
        {
            "family": "Patient1",
            "given": [
                "Test"
            ]
        }
    ]
}
  1. Verify the patient is created by changing the method back to GET and verifying that a request to {{fhirurl}}/Patient returns the newly created patient.

Create an explicit link between the test user in the Microsoft Entra External ID tenant and the resource in the FHIR service. Use extension attributes in Microsoft Graph to define this link. For more information, see Create custom user attributes in Microsoft Entra External ID.

  1. Go to the Microsoft Entra External ID tenant. On the left pane, choose App registrations.

  2. Select All applications.

  3. Select the application with the prefix b2c-extensions-app.

    Screenshot of Microsoft Entra External ID app list.

  4. Note the Application (client) ID value.

    Screenshot of Microsoft Entra External ID extensions app.

  5. Navigate back to the Microsoft Entra External ID tenant home page, on the left pane select Users.

  6. Under Users > All users, select Test Patient1.

    Screenshot of Microsoft Entra External ID user list.

  7. Note the Object ID.

    Screenshot of Microsoft Entra External ID user ID.

  8. Open Microsoft Graph Explorer Sign in with a user assigned to the Global Administrator role for the Microsoft Entra External ID tenant. (It's a good idea to create a new admin user in the Microsoft Entra tenant to manage users.)

    Screenshot of Graph sign in.

  9. Select the avatar for the user, and then choose Consent to permissions.

    Screenshot of Graph consent for test user.

  10. Scroll to User. Consent to User.ReadWrite.All. This permission allows you to update the Test Patient1 user with the fhirUser claim value.

    Screenshot of Graph consent for fhirUser claim.

  11. After the consent process completes, update the user. You need the b2c-extensions-app application (client) ID and the user Object ID.

    • Change the method to PATCH.

    • Change the URL to https://graph.microsoft.com/v1.0/users/{USER_OBJECT_ID}.

    • Create the PATCH body. A PATCH body is a single key-value-pair, where the key format is extension_<B2C-extensions-app-id>_fhirUser and the value is the fully qualified FHIR resource ID for the patient https://<your-fhir-service>.azurehealthcareapis.com/Patient/Patient1". Remove the hyphens from the b2c-extensions-app application (client) ID when you create the key.

    For example:

    {
  "extension_00001111aaaa2222bbbb3333cccc4444_fhirUser": "https://myworkspace-myfhirservice.fhir.azurehealthcareapis.com/Patient/Patient1"
}

    For more information, see Manage extension attributes through Microsoft Graph.

  12. After the request is formatted, choose Run query. Wait for a successful response that confirms the user in the Microsoft Entra External ID tenant is linked to the patient resource in the FHIR service.

    Screenshot of Graph patch.

Configuration to get an access token for Microsoft Entra External ID users

Get an access token to test the authentication flow.

Note

The grant_type of authorization_code is used to get an access token. Online tools are available that offer intuitive interfaces for API testing and development.

  1. Launch the API testing application.

  2. Select the Authorization tab in the tool.

  3. In the Type dropdown list, select OAuth 2.0.

  4. Enter the following values.

    • Callback URL. You configure this value when you create the Microsoft Entra External ID resource application.

    • Auth URL. Create this value by using the name of the Microsoft Entra External ID tenant and the Microsoft Entra External ID tenant ID. Replace your tenant name and tenant ID in the following URL.

      https://<your-external-id-tenant-name>.ciamlogin.com/<your-external-id-tenant-id>/oauth2/v2.0/authorize

    • Access Token URL. Create this value by using the name of the Microsoft Entra External ID tenant and the Microsoft Entra External ID tenant ID. Replace your tenant name and tenant ID in the following URL.

      https://<your-external-id-tenant-name>.ciamlogin.com/<your-external-id-tenant-id>/oauth2/v2.0/token

    • Client ID: This value is the application (client) ID of the Microsoft Entra External resource application.

    • Scope. Define this value in the Microsoft Entra External ID resource application in the Expose an API section. The scope granted permission is patient.all.read. The scope request must be a fully qualified URL, for example, https://testentraexternal.onmicrosoft.com/fhir/patient.all.read.

    • Copy the fully qualified scope from the Expose an API section of the Microsoft Entra External resource application. Example: your-application-id-uri/patient.all.read

Fetch the patient resource by using the Microsoft Entra External ID user

Verify that Microsoft Entra External ID users can access FHIR resources.

  1. When you set up the authorization configuration to launch the Microsoft Entra External ID user flow, select Get New Access Token to get an access token.

  2. Use the Test Patient credentials to sign in.

  3. Copy the access token and use it in fetching the Patient data.

To fetch the patient resource, follow the steps in the Get the FHIR patient data guide:

  1. Select Send Request.

  2. Verify that the response contains the single patient resource.

Next steps

Configure multiple identity providers

Note

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

  • Last updated on