Connect privately to API Management using an inbound private endpoint
Availability
Important
This feature is available in the Premium, Standard, Basic, and Developer tiers of API Management.
You can configure an inbound private endpoint for your API Management instance to allow clients in your private network to securely access the instance over Azure Private Link.
The private endpoint uses an IP address from an Azure VNet in which it's hosted.
Network traffic between a client on your private network and API Management traverses over the VNet and a Private Link on the Microsoft backbone network, eliminating exposure from the public internet.
Configure custom DNS settings or an Azure DNS private zone to map the API Management hostname to the endpoint's private IP address.
With a private endpoint and Private Link, you can:
Create multiple Private Link connections to an API Management instance.
Use the private endpoint to send inbound traffic on a secure connection.
Use policy to distinguish traffic that comes from the private endpoint.
Limit incoming traffic only to private endpoints, preventing data exfiltration.
Important
You can only configure a private endpoint connection for inbound traffic to the API Management instance. Currently, outbound traffic isn't supported.
You can use the external or internal virtual network model to establish outbound connectivity to private endpoints from your API Management instance.
To enable private endpoints, the API Management instance can't already be configured with an external or internal virtual network.
Limitations
- Only the API Management instance's Gateway endpoint supports inbound Private Link connections.
- Each API Management instance supports at most 100 Private Link connections.
- Connections aren't supported on the self-hosted gateway.
Prerequisites
- An existing API Management instance. Create one if you haven't already.
- The API Management instance must be hosted on the
stv2
compute platform. For example, create a new instance or, if you already have an instance in the Premium service tier, enable zone redundancy. - Do not deploy (inject) the instance into an external or internal virtual network.
- The API Management instance must be hosted on the
- A virtual network and subnet to host the private endpoint. The subnet may contain other Azure resources.
- (Recommended) A virtual machine in the same or a different subnet in the virtual network, to test the private endpoint.
Approval method for private endpoint
Typically, a network administrator creates a private endpoint. Depending on your Azure role-based access control (RBAC) permissions, a private endpoint that you create is either automatically approved to send traffic to the API Management instance, or requires the resource owner to manually approve the connection.
Approval method | Minimum RBAC permissions |
---|---|
Automatic | Microsoft.Network/virtualNetworks/** Microsoft.Network/virtualNetworks/subnets/** Microsoft.Network/privateEndpoints/** Microsoft.Network/networkinterfaces/** Microsoft.Network/locations/availablePrivateEndpointTypes/read Microsoft.ApiManagement/service/** Microsoft.ApiManagement/service/privateEndpointConnections/** |
Manual | Microsoft.Network/virtualNetworks/** Microsoft.Network/virtualNetworks/subnets/** Microsoft.Network/privateEndpoints/** Microsoft.Network/networkinterfaces/** Microsoft.Network/locations/availablePrivateEndpointTypes/read |
Steps to configure private endpoint
- Get available private endpoint types in subscription
- Disable network policies in subnet
- Create private endpoint - portal
- List private endpoint connections to the instance
- Approve pending private endpoint connections
- Optionally disable public network access
Get available private endpoint types in subscription
Verify that the API Management private endpoint type is available in your subscription and location. In the portal, find this information by going to the Private Link Center. Select Supported resources.
You can also find this information by using the Available Private Endpoint Types - List REST API.
GET https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/providers/Microsoft.Network/locations/{region}/availablePrivateEndpointTypes?api-version=2021-03-01
Output should include the Microsoft.ApiManagement.service
endpoint type:
[...]
"name": "Microsoft.ApiManagement.service",
"id": "/subscriptions/{subscriptionId}/providers/Microsoft.Network/AvailablePrivateEndpointTypes/Microsoft.ApiManagement.service",
"type": "Microsoft.Network/AvailablePrivateEndpointTypes",
"resourceName": "Microsoft.ApiManagement/service",
"displayName": "Microsoft.ApiManagement/service",
"apiVersion": "2021-04-01-preview"
}
[...]
Disable network policies in subnet
Network policies such as network security groups must be disabled in the subnet used for the private endpoint.
If you use tools such as Azure PowerShell, the Azure CLI, or REST API to configure private endpoints, update the subnet configuration manually. For examples, see Manage network policies for private endpoints.
When you use the Azure portal to create a private endpoint, as shown in the next section, network policies are disabled automatically as part of the creation process
Create private endpoint - portal
Navigate to your API Management service in the Azure portal.
In the left-hand menu, select Network.
Select Inbound private endpoint connections > + Add endpoint.
In the Basics tab of Create a private endpoint, enter or select the following information:
Setting Value Project details Subscription Select your subscription. Resource group Select an existing resource group, or create a new one. It must be in the same region as your virtual network. Instance details Name Enter a name for the endpoint such as myPrivateEndpoint. Network Interface Name Enter a name for the network interface, such as myInterface Region Select a location for the private endpoint. It must be in the same region as your virtual network. It may differ from the region where your API Management instance is hosted. Select the Resource tab or the Next: Resource button at the bottom of the page. The following information about your API Management instance is already populated:
- Subscription
- Resource group
- Resource name
In Resource, in Target sub-resource, select Gateway.
Select the Virtual Network tab or the Next: Virtual Network button at the bottom of the screen.
In Networking, enter or select this information:
Setting Value Virtual network Select your virtual network. Subnet Select your subnet. Private IP configuration In most cases, select Dynamically allocate IP address. Application security group Optionally select an application security group. Select the DNS tab or the Next: DNS button at the bottom of the screen.
In Private DNS integration, enter or select this information:
Setting Value Integrate with private DNS zone Leave the default of Yes. Subscription Select your subscription. Resource group Select your resource group. Private DNS zones The default value is displayed: (new) privatelink.azure-api.cn. Select the Tags tab or the Next: Tabs button at the bottom of the screen. If you desire, enter tags to organize your Azure resources.
Select Review + create.
Select Create.
List private endpoint connections to the instance
After the private endpoint is created, it appears in the list on the API Management instance's Inbound private endpoint connections page in the portal.
You can also use the Private Endpoint Connection - List By Service REST API to list private endpoint connections to the service instance.
Note the endpoint's Connection status:
- Approved indicates that the API Management resource automatically approved the connection.
- Pending indicates that the connection must be manually approved by the resource owner.
Approve pending private endpoint connections
If a private endpoint connection is in pending status, an owner of the API Management instance must manually approve it before it can be used.
If you have sufficient permissions, approve a private endpoint connection on the API Management instance's Private endpoint connections page in the portal.
You can also use the API Management Private Endpoint Connection - Create Or Update REST API.
PUT https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{apimServiceName}privateEndpointConnections/{privateEndpointConnectionName}?api-version=2021-08-01
Optionally disable public network access
To optionally limit incoming traffic to the API Management instance only to private endpoints, disable public network access. Use the API Management Service - Create Or Update REST API to set the publicNetworkAccess
property to Disabled
.
Note
The publicNetworkAccess
property can only be used to disable public access to API Management instances configured with a private endpoint, not with other networking configurations such as VNet injection.
PUT https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{apimServiceName}?api-version=2021-08-01
Authorization: Bearer {{authToken.response.body.access_token}}
Content-Type: application/json
Use the following JSON body:
{
[...]
"properties": {
"publicNetworkAccess": "Disabled"
}
}
Validate private endpoint connection
After the private endpoint is created, confirm its DNS settings in the portal:
Navigate to your API Management service in the Azure portal.
In the left-hand menu, select Network > Inbound private endpoint connections, and select the private endpoint you created.
In the left-hand navigation, select DNS configuration.
Review the DNS records and IP address of the private endpoint. The IP address is a private address in the address space of the subnet where the private endpoint is configured.
Test in virtual network
Connect to a virtual machine you set up in the virtual network.
Run a utility such as nslookup
or dig
to look up the IP address of your default Gateway endpoint over Private Link. For example:
nslookup my-apim-service.azure-api.cn
Output should include the private IP address associated with the private endpoint.
API calls initiated within the virtual network to the default Gateway endpoint should succeed.
Test from internet
From outside the private endpoint path, attempt to call the API Management instance's default Gateway endpoint. If public access is disabled, output will include an error with status code 403
and a message similar to:
Request originated from client public IP address xxx.xxx.xxx.xxx, public network access on this 'Microsoft.ApiManagement/service/my-apim-service' is disabled.
To connect to 'Microsoft.ApiManagement/service/my-apim-service', please use the Private Endpoint from inside your virtual network.
Next steps
- Use policy expressions with the
context.request
variable to identify traffic from the private endpoint. - Learn more about private endpoints and Private Link, including Private Link pricing.
- Learn more about managing private endpoint connections.
- Troubleshoot Azure private endpoint connectivity problems.
- Use a Resource Manager template to create an API Management instance and a private endpoint with private DNS integration.