Integrate Azure Front Door with Azure API Management
Published Aug 17 2021 12:33 AM 29.5K Views


Azure Front Door is a global, scalable entry-point that uses the Microsoft global edge network to create fast, secure, and widely scalable web applications.


Azure Front Door supports dynamic site acceleration (DSA), TLS/SSL offloading and end to end TLS, Web Application Firewall, cookie-based session affinity, url path-based routing, free certificates and multiple domain management, and others. For a full list of supported features, see Overview of Azure Front Door. It provides built-in DDoS protection and application layer security and caching.


This article demonstrates detailed steps to setup Azure Front Door in front of Azure API Management and the steps to restrict APIM accept traffic only from Azure Front Door.




Azure Front Door needs a public VIP or a publicly available DNS name to route the traffic to.


So, if you want to integrate Azure Front Door directly with APIM, APIM should be deployed in public internet or deployed as external VNet mode. The APIM instance should be accessible from external load balancer.


Part 1. Create an APIM instance from Azure Portal

Readers of this article should be quite familiar with APIM, so I am not going to write too much in this part. Please refer to this documentation for detailed steps:


The only thing we need to pay attention to is that we should choose None or External for the Virtual Network Type when creating APIM instance (we can also switch the type later after the creation as well).




Part 2. Create a Front Door from Azure Portal

Here is the official documentation we can follow to create one Azure Front Door:


Step 1. Basics

From the home page or the Azure menu, select Create a resource. Select Networking > See All > Front Door.

In the Basics tab of Create a Front Door page, enter or select the following information, and then select Next: Configuration.



Please note that Azure Front Door is a global service and is not tied to any specific Azure region. The only location you need to specify while creating a Front Door is the resource group location, which is basically specifying where the metadata for the resource group will be stored. Front Door resource itself is created as a global resource and the configuration is deployed globally to all edge locations.


Step 2. Configuration

Configuring Front Door happens in three steps: Adding a frontend host, configuring your backends in a backend pool and finally a routing rule that connects your frontend to the backend pool.



  1. In Frontends/domains, select + to open Add a frontend host.
  2. For Host name, enter a globally unique hostname. Then Select Add.



The hostname here is the default hostname you can use to access Azure Front Door after you publish it. You can also configure Session Affinity or associate Web Application Firewall Policy in this part.


Backend pools

Backend pools can be composed of Storage, Web App, Kubernetes instances, or any other custom hostname that has public connectivity. Azure Front Door requires that the backends are defined either via a public IP or a publicly resolvable DNS hostname. Members of backend pools can be across zones, regions, or even outside of Azure as long as they have public connectivity.

  1. Still in Create a Front Door, in Backend pools, select + to open Add a backend pool.
  2. For Name, enter APIMBackend, then select Add a backend.
  3. In the Backend host type dropdown, chose API Management. Select the APIM instance you want to expose via AFD in your subscription.


*Leave all other fields default.


4. Please note if you use public IP address for the Backend host name, by default you will get 503 error response code from Azure Front door as it thinks the backend certificate common name mismatches.

The workaround is to go to resource explorer(, navigate to your frontDoor resource, then change the enforceCertificateNameCheck as Disabled. (It would take some time to take effect)




5. Back to Backend Pool page, we also need to change the default Health Probes settings. Set the Path with the health probe path for gateway endpoint: “/status-0123456789abcdef” and change the Probe method to GET. This URL always returns 200 OK if APIM service is up and running healthy.




You can also use the custom domain of APIM instance in the Backend host name field. But please note if you are going to route traffic using HTTPS via port 443, only certificates from valid Certificate Authorities can be used at the backend with Front Door. Certificates from internal CAs or self-signed certificates aren't allowed. The certificate must have a complete certificate chain with leaf and intermediate certificates, and root CA must be part of the Microsoft Trusted CA List. Otherwise the HTTPS traffic might fail. Please ensure that you use the valid CA signed certificate for your custom domain.


Routing rules

Next, add a routing rule. A routing rule maps your frontend host to the backend pool. We are going to Route All traffic from this specific Front Door host to APIM instance.

  1. Still in Create a Front Door, in Routing rules, select + to configure a routing rule.
  2. In Add a rule, for Name, enter APIMDirectRule. Accept all the default values, then select Add to add the routing rule.



Azure Front Door supports TLS/SSL offload, and end to end TLS, which re-encrypts the traffic to the backend. In fact, since the connections to the APIM happen over its public IP, it is recommended that you configure your Front Door to use HTTPS as the forwarding protocol.


Final Step

Finally, Select Review + Create, and then Create.



Part 3. Test Integration

Once the provision complete, your request will automatically get routed to the APIM instance configured in Backend Pool. We can use Postman to test the integration.


First, test with calling APIM instance directly. We use the default sample API in APIM (Echo API). We can get 200 OK back successfully.



Then replace the host domain from “” to “” then test again in Postman. We can see the request is forwarded to APIM, and we can get 200 OK back successfully as well.



We can observe that in Http Response header ‘X-Forwarded-For’, the value after the comma is the IP used by AFD to forward request to APIM. In APIM the IP “” is treated as client incoming IP.


Part 4. Restrict Incoming Traffic

Next, how can we ensure our APIM instance only accept requests from Azure Front Door so that all traffic is protected/filtered by Azure Front Door first?


As mentioned in the official document:,  to lock down APIM to accept traffic only from specific Front Door, we will need to set up IP ACLs for APIM instance and then restrict the traffic to the specific value of the header 'X-Azure-FDID' sent by Front Door.


Step 1: Restrict Inbound IP

Restrict Inbound IP to accept traffic from Azure Front Door's backend IP address space and Azure's infrastructure services only.


External Virtual Network Type APIM

For APIM instance deployed as external VNet mode, we can simply restrict the incoming IP using inbound rule in the network security groups of your APIM subnet.

  • Allow service tag AzureFrontDoor.Backend in inbound rule for port 443.




None Virtual Network Type APIM

If your APIM service isn’t deployed into Vnet (None for the Virtual Network type), then there’s nowhere you can put the inbound rule in. But you can still leverage APIM IP restriction policy to achieve this goal. See policy doc here:

  • Allow Azure Front Door Backend Ips. Refer AzureFrontDoor.Backend section in Azure IP Ranges and Service Tags for Front Door's IPv4 backend IP address range.



Please find sample policy below:  

<ip-filter action="allow">

<address> </address>


<address-range from="" to="" />

<address-range from="" to="" />



I didn’t list all IP rules in the policy, please supplement as needed. Please put the policy in API inbound policy part.


When callers access APIM gateway endpoint with client IP which is not in the allowed IP list, they will get 403 forbidden response back. While requests go through Front Door will always get 200 OK.






Step 2: Filter HTTP Request Header

You can also filter incoming request based on one HTTP request header named 'X-Azure-FDID'. Azure Front Door will send this header to APIM with its unique Front Door ID.


You can find the Front Door ID value under the Overview section from Front Door portal page.


This can ensure only your own specific Front Door instance is allowed by APIM service. (because the IP ranges above are shared with other Front Door instances of other customers).


We can leverage APIM check-header policy to achieve this. See policy doc here:


See sample policy below:

        <check-header name="X-Azure-FDID" failed-check-httpcode="403" failed-check-error-message="frontdoorID mismatch" ignore-case="false">

           <value>{Frontdoor ID}</value>




AFD 503 Errors

There are many times when users can connect to the AFD on HTTP but get a 503 when connecting over HTTPS. This is almost always an issue with the certificate on the backend.

Invalid Certificate:

Common Scenarios

  1. Backend Pool is an IP address

    a. The EnforceCertificateNameCheck must be disabled. (Please find detailed instructions in Backend Pools section above)

  2. Backend Server is returning a certificate that does not match the FQDN of the AFD backend Pool

    a. To resolve will either need the certificate returned to match the FQDN

    b. The EnforceCertificateNameCheck must be disabled

  3. Backend Server is using a self-signed certificate or a cert issued by internal CA.

    a. This scenario is not Supported, it will not work. (Also has been mentioned in Backend Pools section)

  4. Backend Server is returning Expired Certificate

    a. Must update certificate.


Common Scenarios

Scenario 1


If user configures Azure Front Door in front of APIM service for developer portal endpoint, when trying to get OAuth token before sending test request, user may get the error "AADSTS500112: The reply address 'https://<apimservicename><settingname>' does not match the reply address 'https://<custom domain>/signin-oauth/code/callback/<settingname>' provided when requesting Authorization code" on developer portal.



  • You have checked and confirmed the AAD app registration and APIM OAuth configuration are appropriate.
  • You have custom domain configured for APIM developer portal and it is pointing to Azure Front Door.



  • As described by above diagram, there are two steps involved during AAD auth code flow.
  •  Step 1: get authorization code from /oauth2/v2.0/authorize, send back to return-url.

   Step 2: get access token from /oauth2/v2.0/token using authorization code and other necessary info, send back to return-url.

  • The return-url for Step 1 will actually hit to Azure Front Door, then Front door will forward request to APIM.
  • The issue would happen when Azure Front Door side is using different domain for configured developer portal endpoint.
  • For example, if Azure Front Door configured APIM default domain for the backend setting, but both AAD app registration and APIM OAuth configuration uses custom domain, then when APIM setting return URL for step 2, it will use the domain sent from Front Door directly, which will cause inconsistency issue.


  • Change the host name or host header setting for APIM developer portal endpoint to match the return host inside AAD app registration and APIM OAuth configuration.



There are still some more topics worth to check which are not listed in this article. Like how to setup WAF (Web Application Firewall) in Azure Front Door, how to add custom domain to Azure Front Door, and the Load Balancing in Azure Front Door.

Below listed some related official documentations for above topics for your reference:


1 Comment
Version history
Last update:
‎Nov 09 2023 11:10 AM
Updated by: