Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Azure Private Link Service enables you to access Azure Services (for example, Managed HSM, Azure Storage, and Azure Cosmos DB etc.) and Azure hosted customer/partner services over a Private Endpoint in your virtual network.
An Azure Private Endpoint is a network interface that connects you privately and securely to a service powered by Azure Private Link. The private endpoint uses a private IP address from your VNet, effectively bringing the service into your VNet. All traffic to the service can be routed through the private endpoint, so no gateways, NAT devices, ExpressRoute or VPN connections, or public IP addresses are needed. Traffic between your virtual network and the service traverses over the Microsoft backbone network, eliminating exposure from the public Internet. You can connect to an instance of an Azure resource, giving you the highest level of granularity in access control.
For more information, see What is Azure Private Link?
Note
Managed HSM does not support Virtual Network Service Endpoints
Prerequisites
To integrate a managed HSM with Azure Private Link, you need:
- A Managed HSM. For more information, see Provision and activate a managed HSM using Azure CLI.
- An Azure virtual network.
- A subnet in the virtual network.
- Owner or contributor permissions for both the managed HSM and the virtual network.
- The Azure CLI version 2.46.0 or later. To configure IP firewall rules, use version 2.78.0 or later. Run
az --versionto find the version. If you need to install or upgrade, see Install the Azure CLI.
Your private endpoint and virtual network must be in the same region. When you select a region for the private endpoint using the portal, it automatically filters only virtual networks that are in that region. Your HSM can be in a different region.
Your private endpoint uses a private IP address in your virtual network.
Establish a private link connection to Managed HSM using CLI (Initial Setup)
Important
Create and approve the private endpoint, configure private DNS, and verify data plane connectivity before you disable public network access. Restricting access before the private connection works can interrupt data plane connectivity.
az login # Login to Azure CLI
az account set --subscription <subscription-id> # Select your Azure Subscription
az group create -n <resource-group> -l <region> # Create a new Resource Group
az provider register -n Microsoft.KeyVault # Register KeyVault as a provider
az network vnet create -g <resource-group> -n <vnet-name> --location <region> # Create a Virtual Network
# Create a Subnet
az network vnet subnet create -g <resource-group> --vnet-name <vnet-name> --name <subnet-name> --address-prefixes <address-prefix>
# Disable Virtual Network Policies
az network vnet subnet update --name <subnet-name> --resource-group <resource-group> --vnet-name <vnet-name> --disable-private-endpoint-network-policies true
# Create a Private DNS Zone
az network private-dns zone create --resource-group <resource-group> --name privatelink.managedhsm.azure.net
# Link the Private DNS Zone to the Virtual Network
az network private-dns link vnet create --resource-group <resource-group> --virtual-network <vnet-name> --zone-name privatelink.managedhsm.azure.net --name <dns-zone-link-name> --registration-enabled true
Create a Private Endpoint (Automatically Approve)
az network private-endpoint create --resource-group <resource-group> --vnet-name <vnet-name> --subnet <subnet-name> --name <private-endpoint-name> --private-connection-resource-id "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/managedHSMs/<hsm-name>" --group-id managedhsm --connection-name <private-link-connection-name> --location <region>
Note
If you delete this HSM the private endpoint stops working. If your recover (undelete) this HSM later, you must re-create a new private endpoint.
Create a Private Endpoint (Manually Request Approval)
az network private-endpoint create --resource-group <resource-group> --vnet-name <vnet-name> --subnet <subnet-name> --name <private-endpoint-name> --private-connection-resource-id "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/managedHSMs/<hsm-name>" --group-id managedhsm --connection-name <private-link-connection-name> --location <region> --manual-request
Manage Private Link Connections
# Show Connection Status
az network private-endpoint show --resource-group <resource-group> --name <private-endpoint-name>
# Approve a Private Link Connection Request
az keyvault private-endpoint-connection approve --description "<description>" --resource-group <resource-group> --hsm-name <hsm-name> --name <private-link-connection-name>
# Deny a Private Link Connection Request
az keyvault private-endpoint-connection reject --description "<description>" --resource-group <resource-group> --hsm-name <hsm-name> --name <private-link-connection-name>
# Delete a Private Link Connection Request
az keyvault private-endpoint-connection delete --resource-group <resource-group> --hsm-name <hsm-name> --name <private-link-connection-name>
Add Private DNS Records
# Determine the Private Endpoint IP address
az network private-endpoint show -g <resource-group> -n <private-endpoint-name> # look for the property networkInterfaces then id; the value must be placed on <private-endpoint-nic> below.
az network nic show --ids <private-endpoint-nic> # look for the property ipConfigurations then privateIpAddress; the value must be placed on <nic-ip> below.
# https://learn.microsoft.com/azure/dns/private-dns-getstarted-cli#create-an-additional-dns-record
az network private-dns zone list -g <resource-group>
az network private-dns record-set a add-record -g <resource-group> -z "privatelink.managedhsm.azure.net" -n <hsm-name> -a <nic-ip>
az network private-dns record-set list -g <resource-group> -z "privatelink.managedhsm.azure.net"
# From home/public network, you wil get a public IP. If inside a vnet with private zone, nslookup will resolve to the private ip.
nslookup <hsm-name>.managedhsm.azure.net
nslookup <hsm-name>.privatelink.managedhsm.azure.net
Validate that the private link connection works
Confirm that the private endpoint provisioning state is Succeeded and the private link connection state is Approved before you test connectivity. For a manually requested connection, complete the approval in Manage Private Link Connections.
You should validate that the resources within the same subnet of the private endpoint resource are connecting to your HSM over a private IP address, and that they have the correct private DNS zone integration.
First, create a virtual machine by following the steps in Create a Windows virtual machine in the Azure portal
In the "Networking" tab:
- Specify Virtual network and Subnet. You can create a new virtual network or select an existing one. If selecting an existing one, make sure the region matches.
- Specify a Public IP resource.
- In the "NIC network security group", select "None".
- In the "Load balancing", select "No".
Open the command line and run the following command:
nslookup <hsm-name>.managedhsm.azure.net
If you run the nslookup command to resolve the IP address of a managed HSM over a public endpoint, you see a result that looks like this:
c:\ >nslookup <hsm-name>.managedhsm.azure.net
Non-authoritative answer:
Name:
Address: (public IP address)
Aliases: <hsm-name>.managedhsm.azure.net
If you run the nslookup command to resolve the IP address of a managed HSM over a private endpoint, you see a result that looks like this:
c:\ >nslookup <hsm-name>.managedhsm.azure.net
Non-authoritative answer:
Name:
Address: 10.1.0.5 (private IP address)
Aliases: <hsm-name>.managed.azure.net
<hsm-name>.privatelink.managedhsm.azure.net
After the HSM hostname resolves to the private endpoint's IP address, verify a data plane operation from the virtual machine. Sign in to Azure CLI with an identity that has Managed HSM local RBAC permissions to list keys, and run:
az keyvault key list --hsm-name <hsm-name> --output table
Confirm that the command succeeds, even if the HSM has no keys. A DNS lookup alone doesn't verify data plane connectivity. Resolve any DNS, connectivity, authentication, or authorization errors before you disable public network access.
Disable public network access
Important
Managed HSM rejects requests to disable public network access while IP firewall rules are configured. If some clients still need IP firewall rules, keep public network access enabled and skip the remaining steps in this section. The rules restrict public access to the allowed IP addresses.
After you provision and approve the private endpoint and successfully verify data plane connectivity, disable public network access and remove any IP firewall rules in a single update:
az keyvault update-hsm --hsm-name <hsm-name> -g <resource-group> --default-action deny --public-network-access Disabled --bypass None --set "properties.networkAcls.ipRules=[]"
Setting --default-action deny alone doesn't block public access when no IP firewall rules are configured. Include --public-network-access Disabled to block public network access. The --bypass None option disables the trusted services exception for private endpoint-only access. The --set "properties.networkAcls.ipRules=[]" argument removes all IP firewall rules in the same update. Removing the rules in a separate, earlier step can temporarily allow requests from public networks until you disable public network access.
Run the key-list command again from the same virtual machine to confirm that data plane access through the private endpoint still succeeds. From a client outside the private network, with no route to the private endpoint, use the same authorized identity to run the same command against the public endpoint. Confirm that the HSM rejects the request because of its network restrictions. A DNS resolution failure, timeout, or authentication or authorization error doesn't by itself verify that public network access is disabled.
Allow trusted services to access Managed HSM (optional)
For private endpoint-only access, skip this section. If your scenario requires supported trusted Microsoft services to access the HSM without a private endpoint, explicitly enable the trusted services exception:
az keyvault update-hsm --hsm-name <hsm-name> -g <resource-group> --bypass AzureServices
This exception remains effective when public network access is disabled, so this configuration isn't private endpoint-only. The individual entities, such as an Azure Storage account or an Azure SQL Server, still need specific role assignments to access a key.
Note
Only specific trusted services usage scenarios are supported. For more information, see the list of trusted services usage scenarios and Managed HSM network security considerations.
Troubleshooting guide
Check that the private endpoint is in the approved state.
Use the
az keyvault private-endpoint-connection showsubcommand to see the status of a private endpoint connection.Make sure the connection state is Approved and the provisioning state is Succeeded.
Make sure the virtual network matches the one you're using.
Check to make sure you have a Private DNS Zone resource.
- You must have a Private DNS Zone resource with the exact name: privatelink.managedhsm.azure.net.
- To learn how to set this up, see the following link. Private DNS Zones
Check to make sure the Private DNS Zone is linked to the Virtual Network. This may be the issue if you are still getting the public IP address returned.
- If the Private Zone DNS is not linked to the virtual network, the DNS query originating from the virtual network returns the public IP address of the HSM.
- Navigate to the Private DNS Zone resource in the Azure portal and select the virtual network links option.
- The virtual network that performs calls to the HSM must be listed.
- If it's not there, add it.
- For detailed steps, see the following document Link Virtual Network to Private DNS Zone
Check to make sure the Private DNS Zone is not missing an A record for the HSM.
- Navigate to the Private DNS Zone page.
- Select Overview and check if there is an A record with the simple name of your HSM. Do not specify any suffix.
- Make sure you check the spelling, and either create or fix the A record. You can use a TTL of 3600 (1 hour).
- Make sure you specify the correct private IP address.
Check to make sure the A record has the correct IP Address.
- You can confirm the IP address by opening the Private Endpoint resource in Azure portal.
- Navigate to the Microsoft.Network/privateEndpoints resource, in the Azure portal
- In the overview page, look for Network interface and select that link.
- The link shows the Overview of the NIC resource, which contains the property Private IP address.
- Verify that the correct IP address is specified in the A record.
Limitations and Design Considerations
Note
The number of managed HSMs with private endpoints enabled per subscription is an adjustable limit. The limit shown as "Maximum Number of Private Endpoints per Managed HSM" is the default limit. If you would like to request a limit increase for your subscription, create an Azure support ticket. We approve these requests on a case by case basis.
Pricing: For pricing information, see Azure Private Link pricing.
Maximum Number of Private Endpoints per Managed HSM: 64.
Default Number of Managed HSM with Private Endpoints per Subscription: 400.
For more, see Azure Private Link service: Limitations
Next Steps
- Learn more about Azure Private Link
- Learn more about Managed HSM