Edit

Use Azure Active Directory B2C to grant access to the FHIR service

  • Article

Healthcare organizations can use Azure Active Directory B2C (Azure AD B2C) with the FHIR® service in Azure Health Data Services to grant access to their applications and users.

Create an Azure AD B2C tenant for the FHIR service

Creating an Azure AD B2C tenant for the FHIR service sets up a secure infrastructure for managing user identities in your healthcare applications.

If you already created an Azure AD B2C tenant, you can skip to Deploy the FHIR service with Azure AD B2C.

Deploy an Azure AD B2C tenant by using an ARM template

Use PowerShell or Azure CLI to deploy the ARM template programmatically to an Azure subscription. For more information about syntax, properties, and usage of the template, see Deploy an instance of Azure Active Directory B2C.

Run the code in Azure Cloud Shell or in PowerShell locally in Visual Studio Code to deploy the FHIR service to the Azure AD B2C tenant.

  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 step or commenting out the line starting with New-AzResourceGroup.

### variables
$tenantid="your tenant id"
$subscriptionid="your subscription id"
$resourcegroupname="your resource group name"
$b2cName="your b2c tenant name"

### login to azure
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/main/samples/fhir-aad-b2c/b2c-arm-template.json -b2cName $b2cNa

Add a test B2C user to the Azure AD B2C tenant

You need a test B2C user to associate with a specific patient resource in the FHIR service, and to verify that the authentication flow works as expected.

  1. In the Azure portal, go to the B2C resource. Choose Open B2C Tenant.

    Screenshot showing a B2C resource.

  2. On the left pane, choose Users.

    Screenshot showing home user.

  3. Choose + New user.

    Screenshot showing adding new user.

The fhirUser custom user attribute is used to link a B2C user with a user resource in the FHIR service. In this example, a user named Test Patient1 is created in the B2C tenant, and in a later step a patient resource is created in the FHIR service. The Test Patient1 user is linked to the patient resource by setting the fhirUser attribute value to the patient resource identifier. For more information about custom user attributes, see User flow custom attributes in Azure Active Directory B2C.

  1. On the Azure AD B2C page in the left pane, choose User attributes.

  2. Choose + Add.

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

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

  5. Choose Create.

    Screenshot showing B2C attribute.

Create a new B2C user flow

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, the access token provided includes the fhirUser claim. For more information, see Create user flows and custom policies in Azure Active Directory B2C.

  1. On the Azure AD B2C page in the left pane, choose User flows.

  2. Choose + New user flow.

    Screenshot showing B2C user flow.

  3. Give the user flow a name unique to the B2C 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. Make sure Email signin is enabled for local accounts so that the test user can sign in and obtain an access token for the FHIR service.

    Screenshot showing B2C user flow configuration.

  5. On the Create a user flow page, scroll to section 5. Application Claims, and then select Show more... to show a list of all available claims.

  6. Select the fhirUser claim.

  7. Choose Ok.

  8. Choose Create.

    Screenshot showing B2C user flow configuration with FHIR user claim.

Create a new B2C resource application

The B2C resource application handles authentication requests from your healthcare application to Azure Active Directory B2C.

  1. On the Azure AD B2C page in the left pane, choose App registrations.

  2. Choose + New registration.

    Screenshot showing B2C new application.

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

  4. In the Supported account types list, choose Accounts in any identity provider or organizational directory (for authenticating users with user flows).

  5. In the Redirect URI (recommended) drop-down list, select *Public client/native (mobile & desktop). Populate the value with the Postman callback URI https://oauth.pstmn.io/v1/callback. The callback URI is for testing purposes.

  6. In the Permissions section, select Grant admin consent to openid and offline_access permissions.

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

    Screenshot showing B2C application register.

Configure API permissions for the app

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

  2. Scroll until you find the oauth2Permissions array. 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 B2C tenant can obtain an access token with the API permission. If a level of access isn't appropriate for a user within the B2C tenant, don't add to the array because there isn't a way to limit permissions to a subset of users.

  3. After the oauth2Permissions array is populated, choose Save.

    Screenshot showing B2C application manifest.

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. In this example, the value is fhir.

  4. Choose Save.

    Screenshot showing B2C application API.

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

  6. Choose + Add a permission.

    Screenshot showing B2C API permission.

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

  8. Select the resource application from the list.

    Screenshot showing B2C API permissions with APIs used.

  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.

    Screenshot showing B2C API permissions with permissions added.

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

    Screenshot showing B2C API permissions for admin consent.

Deploy the FHIR service with Azure Active Directory B2C as the identity provider

Deploying the FHIR service with Azure Active Directory B2C as the identity provider allows the FHIR service to authenticate users based on their Azure AD B2C credentials, ensuring that only authorized users can access sensitive patient information

Obtain the B2C authority and client ID

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

  1. Create the authority string by using the name of the B2C tenant and the name of the user flow.

    https://<YOUR_B2C_TENANT_NAME>.b2clogin.com/<YOUR_B2C_TENANT_NAME>.onmicrosoft.com/<YOUR_USER_FLOW_NAME>/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 B2C tenant name and user flow name are correct.

    https://<YOUR_B2C_TENANT_NAME>.b2clogin.com/<YOUR_B2C_TENANT_NAME>.onmicrosoft.com/<YOUR_USER_FLOW_NAME>/v2.0/.well-known/openid-configuration

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

    Screenshot showing B2C application overview page.

Deploy the FHIR service by using an 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 in Visual Studio Code to deploy the FHIR service to the Azure AD B2C tenant.

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

Validate Azure AD B2C 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 Azure AD B2C user, and configuring Postman to get an access token for B2C users. After the validation process is complete, you can fetch the patient resource by using the B2C test user.

Run Postman to get an access token

Run the Postman application locally or in a web browser. For steps to obtain the proper access to the FHIR service, see Access the FHIR service using Postman.

When you follow the steps to GET FHIR resource 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 B2C tenant aren't able to read any resources until the user is linked to a FHIR resource, for example as patient or practitioner. 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.

You need to create an explicit link between the test user in the B2C tenant and the resource in the FHIR service. Create the link by using Extension Attributes in Microsoft Graph. For more information, see Define custom attributes in Azure Active Directory B2C.

  1. Go to the B2C tenant. On the left pane, choose App registrations.

  2. Select All applications.

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

    Screenshot showing B2C app list.

  4. Note the Application (client) ID value.

    Screenshot showing B2C extensions app.

  5. Navigate back to the B2C tenant home page, on the left pane select Users.

    Screenshot showing B2C home user.

  6. Select Test Patient1.

    Screenshot showing B2C user list.

  7. Note the Object ID value.

    Screenshot showing B2C user ID.

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

    Screenshot showing Graph login.

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

    Screenshot showing 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 showing 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_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 B2C tenant is linked to the patient resource in the FHIR service.

    Screenshot showing Graph patch.

Configure Postman to obtain an access token for B2C users

Obtain an access token to test the authentication flow.

  1. Launch the Postman application, and then create a new Blank collection. In this example, the collection is named FHIR Patient.

    Screenshot showing Postman new collection.

  2. Select the Authorization tab in the collection overview.

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

    Screenshot showing Postman auth.

  4. Scroll to the Configure New Token section and enter these values:

    • Callback URL. This value is configured when the B2C resource application is created.

      https://oauth.pstmn.io/v1/callback

    • Auth URL. This value can be created using the name of the B2C tenant and the name of the user flow.

      https://{YOUR_B2C_TENANT_NAME}.b2clogin.com/{YOUR_B2C_TENANT_NAME}.onmicrosoft.com/{YOUR_USER_FLOW_NAME}/oauth2/v2.0/authorize

    • Access Token URL. This value can be created using the name of the B2C tenant and the name of the user flow.

      https://{YOUR_B2C_TENANT_NAME}.b2clogin.com/{YOUR_B2C_TENANT_NAME}.onmicrosoft.com/{YOUR_USER_FLOW_NAME}/oauth2/v2.0/token

    • Client ID. This value is the application (client) ID of the B2C resource application.

      {YOUR_APPLICATION_ID}

    • Scope. This value is defined in the B2C 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://testb2c.onmicrosoft.com/fhir/patient.all.read.

  5. Copy the fully qualified scope from the Expose an API section of the B2C resource application.

    {YOUR_APPLICATION_ID_URI}/patient.all.read

    Screenshot showing Postman URLs.

Fetch the patient resource by using the B2C user

Verify that Azure AD B2C users can access FHIR resources.

  1. When the authorization configuration in Postman is set up to launch the B2C user flow, choose Get New Access Token to get an access token.

    Screenshot showing Postman get access token.

  2. Use the Test Patient credentials to sign in.

    Screenshot showing Postman get token.

  3. Choose Use Token to use the access token for any requests in the collection.

    Screenshot showing Postman use token.

  4. Create a new request to search for patient resources in the FHIR service. Select the ellipsis button (...) next to the name of the collection, and then choose Add request.

    Screenshot showing Postman request added.

  5. Set the method to GET, enter the fully qualified FHIR service URL, and then add the path /Patient.

  6. Choose Send.

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

    Screenshot showing Postman request response.

Next steps

Configure multiple identity providers

Troubleshoot identity provider configuration

Note

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