Configure private link

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.

Private link enables you to access Azure API for FHIR® over a private endpoint, which is a network interface that connects you privately and securely using a private IP address from your virtual network. With private link, you can access our services securely from your virtual network as a first party service without having to go through a public Domain Name System (DNS). This article describes how to create, test, and manage your private endpoint for Azure API for FHIR.

Note

Neither Private Link nor Azure API for FHIR can be moved from one resource group or subscription to another once Private Link is enabled. To make a move, delete the Private Link first, then move Azure API for FHIR. Create a new Private Link once the move is complete. Assess potential security ramifications before deleting Private Link.

If exporting audit logs and metrics is enabled for Azure API for FHIR, update the export setting through Diagnostic Settings from the portal.

Prerequisites

Before creating a private endpoint, you need to create Azure resources that first.

• Resource Group – The Azure resource group that contains the virtual network and private endpoint.
• Azure API for FHIR – The FHIR resource you would like to put behind a private endpoint.
• Virtual Network (VNet) – The VNet to which your client services and Private Endpoint will be connected.

For more information, see Private Link Documentation.

Create private endpoint

To create a private endpoint, a developer with role-based access control (RBAC) permissions on the FHIR resource can use the Azure portal, Azure PowerShell, or Azure CLI. This article guides you through the steps on using Azure portal. Azure portal is recommended as it automates the creation and configuration of the Private DNS Zone. For more information, see Private Link Quick Start Guides.

There are two ways to create a private endpoint. Auto Approval flow allows a user that has RBAC permissions on the FHIR resource to create a private endpoint without a need for approval. Manual Approval flow allows a user without permissions on the FHIR resource to request a private endpoint to be approved by owners of the FHIR resource.

Note

When an approved private endpoint is created for Azure API for FHIR, public traffic to it is automatically disabled.

Auto approval

Ensure the region for the new private endpoint is the same as the region for your virtual network. The region for your FHIR resource can be different.

For the resource type, search and select Microsoft.HealthcareApis/services. For the resource, select the FHIR resource. For target subresource, select FHIR.

If you don't have an existing Private DNS Zone set up, select (New)privatelink.azurehealthcareapis.com. If you already have your Private DNS Zone configured, you can select it from the list. It must be in the format of privatelink.azurehealthcareapis.com.

After the deployment is complete, you can go back to Private endpoint connections tab of which you'll notice Approved as the connection state.

Manual Approval

For manual approval, select the second option under Resource, "Connect to an Azure resource by resource ID or alias". For Target subresource, enter "fhir" as in Auto Approval.

After the deployment is complete, you can go back to "Private endpoint connections" tab, on which you can Approve, Reject, or Remove your connection.

VNet Peering

With Private Link configured, you can access the FHIR server in the same VNet or a different VNet that is peered to the VNet for the FHIR server. Use the following steps to configure VNet peering and Private Link DNS zone configuration.

Configure VNet Peering

You can configure VNet peering from the portal or using PowerShell, CLI scripts, and an Azure Resource Manager (ARM) template. The second VNet can be in the same or different subscriptions, and in the same or different regions. Make sure that you grant the Network contributor role. For more information on VNet Peering, see Create a virtual network peering.

Add VNet link to the private link zone

In the Azure portal, select the resource group of the FHIR server. Select and open the Private DNS zone, privatelink.azurehealthcareapis.com. Select Virtual network links under the settings section. Select the Add button to add your second VNet to the private DNS zone. Enter the link name of your choice, select the subscription and the VNet you created. Optionally, you can enter the resource ID for the second VNet. Select Enable auto registration, which automatically adds a DNS record for your VM connected to the second VNet. When you delete a VNet link, the DNS record for the VM is also deleted.

For more information on how a private link DNS zone resolves the private endpoint IP address to the fully qualified domain name (FQDN) of the resource, such as the FHIR server, see Azure Private Endpoint DNS configuration.

You can add more VNet links if needed, and view all VNet links you added from the portal.

From the Overview blade you can view the private IP addresses of the FHIR server and the VMs connected to peered virtual networks.

Manage private endpoint

View

Private endpoints and the associated network interface controller (NIC) are visible in Azure portal from the resource group they were created in.

Delete

Private endpoints can only be deleted from the Azure portal from the Overview blade or by selecting the Remove option under the Networking Private endpoint connections tab. Selecting Remove deletes the private endpoint and the associated NIC. If you delete all private endpoints to the FHIR resource and the public network, access is disabled and no request will make it to your FHIR server.

Test and troubleshoot private link and VNet peering

To ensure that your FHIR server isn't receiving public traffic after disabling public network access, select the /metadata endpoint for your server from your computer. You should receive a 403 Forbidden.

Note

It can take up to 5 minutes after updating the public network access flag before public traffic is blocked.

Create and use a VM

To ensure your private endpoint can send traffic to your server:

1. Create a virtual machine (VM) that is connected to the virtual network and subnet your private endpoint is configured on. To ensure your traffic from the VM is only using the private network, disable the outbound internet traffic using the network security group (NSG) rule.
2. RDP into the VM.
3. Access your FHIR server’s /metadata endpoint from the VM. You should receive the capability statement as a response.

Use nslookup

You can use the nslookup tool to verify connectivity. If the private link is configured properly, you should see the FHIR server URL resolves to the valid private IP address, as follows. Note that the IP address 168.63.129.16 is a virtual public IP address used in Azure. For more information, see What is IP address 168.63.129.16.

C:\Users\testuser>nslookup fhirserverxxx.azurehealthcareapis.com
Server:  UnKnown
Address:  168.63.129.16

Non-authoritative answer:
Name:    fhirserverxxx.privatelink.azurehealthcareapis.com
Address:  172.21.0.4
Aliases:  fhirserverxxx.azurehealthcareapis.com

If the private link isn't configured properly, you may instead see the public IP address and a few aliases including the Traffic Manager endpoint. This indicates that the private link DNS zone can’t resolve to the valid private IP address of the FHIR server. When VNet peering is configured, one possible reason is that the second peered VNet hasn't been added to the private link DNS zone. As a result, you see the HTTP error 403, "Access to xxx was denied", when trying to access the /metadata endpoint of the FHIR server.

C:\Users\testuser>nslookup fhirserverxxx.azurehealthcareapis.com
Server:  UnKnown
Address:  168.63.129.16

Non-authoritative answer:
Name:    xxx.cloudapp.azure.com
Address:  52.xxx.xxx.xxx
Aliases:  fhirserverxxx.azurehealthcareapis.com
          fhirserverxxx.privatelink.azurehealthcareapis.com
          xxx.trafficmanager.net

For more information, see Troubleshoot Azure Private Link connectivity problems.

Next steps

In this article, you learned how to configure the private link and VNet peering. You also learned how to troubleshoot the private link and VNet configurations.

Based on your private link setup, and for more information about registering your applications, refer to the following.

• Register a resource application
• Register a confidential client application
• Register a public client application
• Register a service application

Note

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