Use Microsoft Entra External ID to grant access to the FHIR service

1. Use Connect-AzAccount to sign in to Azure. After you sign in, use Get-AzContext to verify the subscription and tenant you want to use. Change the subscription and tenant if needed.

2. Create a new resource group (or use an existing one) by skipping the "create resource group" step, or commenting out the line starting with New-AzResourceGroup.

### 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(don't include .onmicrosoft.com)"

### 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/samples/fhir-aad-entra-external/entra-external-arm-template.json -directoryName $directoryName

1. Use az login to sign in to Azure. After you sign in, use az account show --output table to verify the subscription and tenant you want to use. Change the subscription and tenant if needed.

2. Create a new resource group (or use an existing one) by skipping the "create resource group" step or commenting out the line starting with az group create.

# variables
tenantid="your tenant id"
subscriptionid="your subscription id"
resourceGroupName="your resource group name"
region="your desired region"
directoryName="your directory name"

# login to azure
az login
az account show --output table
az account set --subscription $subscriptionid

# create resource group
az group create --name $resourceGroupName --location $region

# deploy the resource
az deployment group create --resource-group $resourceGroupName --template-uri https://raw.githubusercontent.com/Azure-Samples/azure-health-data-and-ai-samples/samples/fhir-aad-entra-external/entra-external-arm-template.json  --parameters directoryName=$directoryName

Add a test user to the Microsoft Entra External ID tenant

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 in the top menu to switch to your external tenant from the Directories + subscriptions menu. Here you will be asked for MFA setup.

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

   

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

   

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

Link an Entra External ID user with the fhirUser custom user attribute

The fhirUser custom user attribute is used to link a user in Microsoft Entra External ID with a corresponding patient resource in the FHIR service. In this example, a user named Test Patient1 is created in the Entra External ID tenant. In a later step, a patient resource is created in the FHIR service. The Test Patient1 user is associated 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 Entra External ID.

1. Search for External Identities

2. Navigate to Custom user attributes,

3. Choose + Add.

4. In the Add custom attribute pane:

   • In the Name field, Enter fhirUser (case-sensitive)

   • From the Data Type dropdown list, select String.

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

   • Choose Create.

   

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, a user flow is defined so that when a user signs in and the access token provided includes the fhirUser claim. For more information, see Create user flows and custom policies in Microsoft Entra External ID.

1. On the External Identities page in the left pane, choose User flows.

2. Choose + New user flow.

   

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

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

   

5. On the Create a user flow page Select Show more to view additional attributes.

6. Under Collect attribute,

7. Select the fhirUser claim.

8. Choose Ok.

9. Choose Create.

Create an 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, navigate to Applications > App registrations.

2. Choose + New registration.

   

3. In the Register an application pane:

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

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

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

  

Configure API permissions for the app

1. On the App registrations page in the left pane, choose Manifest.

2. Scroll until you find the oauth2PermissionScopes array in Microsoft Graph App Manifest (New) tab. Replace the array with one or more values in the oauth2Permissions.json file. 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 obtain an access token with that API permission. If a permission level isn't appropriate for all users, do not include it in the permission array.

3. After the oauth2PermissionScopes array is populated

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

5. choose Save.

   

Expose the web API and assign an application ID URI

1. On the App registrations page in the left pane, choose Expose an API.

2. Choose Add.

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

4. Choose Save.

   

5. On the App registrations page in the left pane, choose API permissions.

6. Choose + Add a permission.

   

7. On the Request API permissions pane, select APIs my organization uses.

8. Select the resource application from the list.

   

9. On the Request API permissions pane 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. Choose Add permissions.

    

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

    

Configure Single sign-on (Preview) for the app

1. On the Enterprise apps page in the left pane, choose All applications.

2. Select your registered application from the list.

   

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

4. Select Edit to configure the single sign-on settings.

   

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

   

6. Configure the new claim:

   • Name: fhirUser

   • Source: Select Directory schema extension

   • Source attribute: Select b2c-extensions-app

   

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

   

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

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

   

10. select save

    

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

Deploying the FHIR service with Entra External ID as the identity provider allows the FHIR service to authenticate users based on their Entra External ID credentials, ensuring that only authorized users can access sensitive patient information

Obtain the Entra External ID authority and client ID

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

1. Create the authority string by using the name of the Entra External ID tenant and the name of the user flow.

   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 Entra External ID tenant name and Entra External ID tenant ID are correct.

   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.

   

Deploy the FHIR service by using ARM Template

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

Run the code in Azure Cloud Shell or in PowerShell locally using Visual Studio Code to deploy the FHIR service with Microsoft Entra External ID as the identity provider.

1. Use Connect-AzAccount to sign in to Azure. Use Get-AzContext to verify the subscription and tenant you want to use. Change the subscription and tenant if needed.

2. Create a new resource group (or use an existing one) by skipping the "create resource group" step, or commenting out the line starting with New-AzResourceGroup.

### 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 (from previous step)"
$smartClientId="your client id (from previous step)"

### Login to Azure
Connect-AzAccount

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

### 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/main/samples/fhir-aad-b2c/fhir-service-arm-template.json -tenantid $tenantid -region $region -workspaceName $workspacename -fhirServiceName $fhirservicename -smartAuthorityUrl $smartAuthorityUrl -smartClientId $smartClientId

1. Use az login to sign in to Azure. Use az account show --output table to verify the subscription and tenant you want to use. Change the subscription and tenant if needed.

2. Create a new resource group (or use an existing one) by skipping the "create resource group" step, or commenting out the line starting with az group create.

### 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 (from previous step)
smartClientId=your client id (from previous step)

### login to azure
az login
az account show --output table
az account set --subscription $subscriptionid

### create resource group
az group create --name $resourcegroupname --location $region

### deploy the resource
az deployment group create --resource-group $resourcegroupname --template-uri https://raw.githubusercontent.com/Azure-Samples/azure-health-data-and-ai-samples/main/samples/fhir-aad-b2c/fhir-service-arm-template.json --parameters tenantid=$tenantid region=$region workspaceName=$workspacename fhirServiceName=$fhirservicename smartAuthorityUrl=$smartAuthorityUrl smartClientId=$smartClientId

Validate Microsoft Entra External ID Users are able to 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

It's important to note that users in the Microsoft Entra External ID tenant aren't able to read any resources until the user (such as a patient or practitioner) is linked 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"
            ]
        }
    ]
} 

2. 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.

Link the patient resource to Microsoft Entra External ID User.

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 Entra External ID.

1. Go to the 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.

   

4. Note the Application (client) ID value.

   

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

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

   

7. Note the Object 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.)

   

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

   

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

    

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_EXTENSION_APP_ID_NO_HYPHENS}_fhirUser and the value is the fully qualified FHIR resource ID for the patient https://{YOUR_FHIR_SERVICE}.azurehealthcareapis.com/Patient/1".

    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 Entra External ID tenant is linked to the patient resource in the FHIR service.

    

Configuration to obtain an access token for Entra External ID users

Obtain an access token to test the authentication flow.

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. This value is configured when the Entra External ID resource application is created.

   • Auth URL. This value can be created using the name of the Entra External ID tenant and the Entra External ID tenant ID.

     https://{YOUR_EXTERNAL_ID_TENANT_NAME}.ciamlogin.com/{YOUR_EXTERNAL_ID_TENANT_ID}/oauth2/v2.0/authorize
     

   • Access Token URL. This value can be created using the name of the Entra External ID tenant and the Entra External ID tenant ID.

     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 Entra External resource application.

     {YOUR_APPLICATION_ID}
     

   • Scope. This value is defined in the 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 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 the authorization configuration is set up to launch the Microsoft Entra External ID user flow, choose 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.

Follow the steps in the Get the FHIR patient data guide to fetch the patient resource:

1. Set the HTTP method to GET, enter the fully qualified FHIR service URL, and append the path /Patient.

2. Use the fetched token in the authorization header.

3. Choose Send Request.

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

Next steps

Configure multiple identity providers

Troubleshoot identity provider configuration