Recently I had the need to setup Azure APIM with the following configuration:

  • API Management
  • Frontdoor sitting in front of APIM
  • APIM Developer portal also running through frontdoor
  • APIM Developer portal using Azure AD for authentication
  • Use a custom domain for both the API and Developer Portal

Your first question might be why you would want to configure the APIM to use frontdoor when APIM has a global capability if you need it. Well the main reason is that Frontdoor will move the WAF and DDos capabilities to the edge network and away from your APIM. This has a number of benefits, but it also allows you to provide some load balancing too so if you were not using APIM premium you could load balance across 2 standard instances which might be a significant cost saving for some. There are a few use cases where this is beneficial but mainly they will come back to security and load balancing benefits.

If you want to combine Azure APIM and Frontdoor for basic request routing and protection of your API then there are a couple of good articles below by Mikael Sand and Paolo Salvatori:

These articles will help you get your API calls to run through frontdoor but the extra steps about the developer portal take some additional configuration which isnt really documented so I thought id write down how we did it.


At the starting point I have already setup the basic setup of an APIM, a Frontdoor and I already have a domain setup. These are in their default configuration and the settings are as follows:

Custom Domain DNS Setup

I have setup 2 sub domains on my godaddy dns entries like shown below which will target my frontdoor instance. will be for traffic for my api calls. will be for my APIM developer portal.

There is no additional special configuration, just the 2 CNAME entries.

Frontdoor – Backends

On frontdoor I will start by registering 2 backends which will point to my APIM instance. One will be for the developer portal and the other for the api traffic.

Developer Portal Backend configuration looks like below and uses the address for the developer portal.

The api back end looks like below:

Frontdoor – Front Ends

Next I will configure the frontends in my frontdoor. I will add the 2 custom urls that I have available via my godaddy DNS as shown below.

In the case of both sub domains I am adding them and choosing the frontdoor managed certificate as shown below:

If you repeat the setup for both api-dev and api-portal-dev sub domains and add them both as frontends.

Frontdoor Routing Rules

In frontdoor I will setup 3 routing rules:

  • HTTP to HTTPS to redirect non https traffic to use https
  • API which will forward api calls to the APIM instance
  • API Portal which will forward the portal traffic to the APIM portal

HTTP to HTTPS Routing

The below configuration shows how to redirect http traffic to https on your frontdoor

The rule uses a redirect rule type and does a redirect as shown below.

API Routing Rule

The API routing rule subscribes to traffic from the api-dev frontend and will forward is to the APIM backend as shown below.

This rule will use the forward route type and send traffic to the APIM backend which is the main url for the APIM instance. Note that we are forwarding it to the default APIM url which Azure sets up by default and not the custom domain which you might have notices in the earlier screen shots.

API Portal Routing Rule

The routing rule for the APIM portal is pretty much the same except that it will use the APIM portal frontend and forward it to the APIM Portal backend.

Again note that on the backend we are using the default url for the APIM portal that Azure setup when we configured APIM. You will have seen this in the above picture.

Make sure you have saved your frontdoor configuration.

Where are we so far?

At this point we should now be able to route traffic for our API calls and access to the API developer portal via frontdoor. You could test this by calling the echo API from postman or something to route the traffic through frontdoor.

Setting up Azure AD Security for the Developer Portal

This is where things start to change a bit because we are using frontdoor. If you want to setup Azure AD authentication you need to consider that your redirect back from Azure to the portal needs to redirect to an Azure Frontdoor address and not direct to the APIM Portal address bypassing frontdoor. To do this you need to take the following steps.

You will need to setup the Active Directory authentication provider in your APIM using the menu shown below.

You will need to setup an App Registration in Azure Active Directory (not covered in this article but its just the default approach for creating an app registration) and setup a secret and then provide these details to the Azure APIM configuration screen as shown below.

You are then supposed to also copy the redirect url from the screen above and paste is as the redirect url for your Azure AD app registration as shown below. What you also need to do however which is specific to the use case of running the portal through frontdoor is add an additional redirect url for the frontdoor address. You can see 2 below.

Where are we at?

At this point you should now be able to access the APIM developer portal through frontdoor and login via Azure AD. This is good but there is another hurdle!

In the APIM developer portal any user will see the direct APIM url for trying out your API rather than the frontdoor address. We need to change this and we can add a custom domain to APIM to do this.

APIM Custom Domain

In APIM I can go to the custom domains menu as shown below and I can add a domain for the gateway. Note that if I add one for the gateway it will show up in the APIM Developer portal but I do not need to add a custom domain here for the developer portal because that is handled by Frontdoor.

To be honest, this bit is a little bit of a pain! The problem here is that when registering a custom domain with Azure APIM you need to upload a certificate or point to a certificate in a keyvault as shown below.

In frontdoor I had chosen to use the Azure Managed certificate so I had less management overhead. If your using a self-managed certificate this is fine because you can just point to the certificate but for my scenario I dont have a certificate so I cant upload one and as result cant add a custom domain.

To workaround this problem I chose to follow the approach recommended by Merry in her article about using Lets Encrypt with an Azure DevOps pipeline ( In this case I have a pipeline which refreshes a cert into keyvault on a monthly basis. This then allows me to point to the cert in keyvault when I setup the custom domain in APIM.

At this point I can now access the APIM Dev Portal and I will see my custom domain shown in the portal as shown below:

We are now able to use the developer portal to execute the API operation and the traffic from the Developer Portal will call out and route through Frontdoor and to the APIM Gateway and then execute our API.

You will also notice if you use the test feature in the Azure Portal it is now using the custom domain too so this traffic will route through Frontdoor.

Point to Note

One of the things I am not sure about is that in the custom domain setup in Azure APIM is that no traffic routes to APIM actually on the custom domain. Frontdoor always forwards to APIM on the original url setup my Azure. Therefore once the custom domain is registered with APIM I do not know if it matters if the certificate expires or not. I suspect it probably doesnt because you can register multiple domains with APIM so ill keep an eye on this and see what happens and worse case for now I can just leave the lets encrypt certificate renewing automatically. For the actual traffic im using the azure managed cert between any client and front door and between frontdoor and APIM it uses the APIM default cert from Microsoft.

Locking down APIM

The final step which you may have seen elsewhere is to lockdown your APIM to only accept traffic from Azure Frontdoor to prevent people bypassing your frontdoor. You can do this by adding ip restrictions for frontdoor or using a check of the X-Azure-FDID header for your unique frontdoor id, or both approaches.

<check-header name="X-Azure-FDID" 
    failed-check-error-message="Not authorized - request not from frontdoor" 
            <value>[Your Frontdoor ID]</value>

What id like to see Microsoft do to make this easier

Once id worked through the steps it was pretty straightforward to get this working so I hope this helps others, but I hope microsoft can do 2 things to help make this easier. The first would be that while the APIM policy ip restrictions are pretty easy to implement, other Azure services are able to use service tags in their networking configuration to help simplify network security. It would be really helpful if Microsoft can add service tag support to the policy for this use case or add a specific policy called something like limit-access-to-frontdoor where you just add your frontdoor address and the policy handles it for you. The 2nd thing id like to see would be a way to have APIM aware that my domain is managed by frontdoor in some way so that I could setup the custom domain without needing to supply a certificate.


Buy Me A Coffee