This article is contributed. See the original author and article here.

When API Management is with internal Virtual Network, the connection to this API Management will be blocked from outside.To be able to call the API or visit the developer portal of such API Management, Application Gateway will be a good choice for you. 


By using Application Gateway, the request sent to API Management will be automatically routed. And the Application Gateway can also help user to monitor whether the API Management is still in a healthy status. 



Before startingyou must setup the environment at first.   

To set up a local development environment, you need to have:  

  • API Management instance. If you don’t have one, follow this tutorial.  

  • Configure the API Management instance with internal Virtual Network. If you don’t know how, please follow this tutorial. 

  • usable domain name 

  • Some  SSL certificates of above domain name. It’s no matter self-signed or not. If we need to self-sign one, please use following scripts in PowerShell command line and remember to replace the domain name and output path as you want.








$cert = New-SelfSignedCertificate -DnsName -CertStoreLocation "D:" -KeyLength 2048 -KeySpec "KeyExchange" 

$password = ConvertTo-SecureString -String "your-password" -Force -AsPlainText 

Export-PfxCertificate -Cert $cert -FilePath ".management.pfx" -Password $password 

Export-Certificate -Type CERT -Cert $cert -FilePath .management.cer 








  • An Application Gateway with Tier WAF or Standard. Please follow this document to create. 

  • The Network Security Group added on the subnet where API Management is. Follow this post to create this Network Security Group and add the security rule as mentioned here. 


Some points to explain before starting: 

  • The custom domain setting in API Management can be customized by yourself. In this example, the used domain names are as following: 

    1. for new developer portal endpoint 

    2. for legacy developer portal endpoint 

    3. for management endpoint 

    4. for proxy endpoint 

  • In this example, the purpose is to build an environment for visiting the developer portal and calling API from outside of Virtual Network. If you also want to do this from the inside of Virtual Network, here are two options: 

    1. Follow this document to build an custom DNS zone to resolve the API Management custom domain 

    2. Follow this document to create a Azure Virtual Machine with Windows Server 2019 as operation system and follow this article to configure custom DNS server by yourself. Then modify the custom DNS setting in Virtual Network page in Azure Portal with the private IP address of the created Virtual Machine. 


Steps to implement:  

Once you are done with the above preparations, you can follow these steps to link the API Management with Application Gateway. Please remember that if you want to be able to visit the new developer portal of the API Management, you’ll also need to enable the new developer portal endpoint and management endpoint at the same time. This is due to the design of the new developer portal. (In this example, we’re using HTTPS protocol because the HTTP protocol setting is almost the same only without some certificate configuration.) 

  1. Follow this tutorial to configure the custom domain of the endpoints which you want to visit from outside of Virtual Network. And pay attention to which endpoint is marked as Default SSL binding. This is important in the later steps. It’s normally recommended to use the gateway endpoint as the Default SSL binding one. 

    API Management custom domain settingAPI Management custom domain setting

  2. For the Network Security Group which is used on the subnet where Application Gateway is deployed, add an inbound security rule with following parameters:

    • Port: 443, 65503-65534 (If with HTTP protocol, also open 80 port here)

    • Protocol: Any

    • Source: Internet

    • Destination: VirtualNetwork

    • Action: Allow

  3. In Application Gateway, create a new backend pool. And in the backend targets part, create a new backend target with the private IP address of our API Management.

API Management overview page - private IPAPI Management overview page – private IPApplication Gateway page - Backend pool labelApplication Gateway page – Backend pool labelApplication Gateway backend pool settingApplication Gateway backend pool setting

4. Then, create one Health probe for each API Management endpoint which you want to visit. Put your own custom domain name in the Host part, fill the Path part as following table and configure the other configuration as you want. The detailed information about how Application Gateway health probe is working can be found in our official document.

  • Gateway endpoint:   /status-0123456789abcdef 

  • New developer portal endpoint:  /signin 

  • Legacy developer portal endpoint:  /signin 

  • Management endpoint:  /servicestatus 

The following is an example health probe of legacy developer portal endpoint.

Application Gateway page - Health Probe labelApplication Gateway page – Health Probe labelApplication Gateway Health Probe settingApplication Gateway Health Probe setting

  1. Next step is to create one listener for every API Management endpoint. With HTTPS protocol, you’ll be required to upload the certificate. The certificate here must match the certificate used in API Management custom domain configuration of the same endpoint. If we are creating a listener for the management endpoint, we cannot upload the certificate of the other three endpoints. 

    In Additional settings, choose Multi site as listener type and input your own custom domain URL configured in API Management. 

    The detailed information about how Application Gateway listener is working can be found in our official document. 

    Here is an example listener configuration of legacy developer portal endpoint. 

Application Gateway page - Listener labelApplication Gateway page – Listener labelApplication Gateway Listener settingApplication Gateway Listener setting

6. It’s time to configure the most important thing, the HTTP settings. In Application Gateway, you’ll also need to create one HTTP setting for each endpoint of API Management. For HTTPS protocol, you’ll be asked to upload the certificate again as the previous step. But here, please upload the certificate used in the custom domain configuration of API Management of the Default SSL Binding one. For the HTTP settings of all endpoints, the uploaded and used certificate will be always the same one!
In the Host name part, select Override with specific domain name and input your own custom domain. Then select the health probe which you created in step 4 for Custom probe option.
Here is an example HTTP setting of the gateway endpoint.
About how the HTTP setting is working in Application Gateway, we can learn more from here.

Application Gateway page - Http Settings labelApplication Gateway page – Http Settings label

Application Gateway Http Settings pageApplication Gateway Http Settings page

Application Gateway Http Setting page 2Application Gateway Http Setting page 2

7. When you’ve finished above steps, you need to create one Rule in Application Gateway for each API Management endpoint. It’s quite easy. You only need to select the created Listener, Backend pool and HTTP setting together.
Here is an example rule of my new developer portal endpoint:

Application Gateway page - Rules labelApplication Gateway page – Rules label

Application Gateway Rules pageApplication Gateway Rules page

Application Gateway Rules page 2Application Gateway Rules page 2

8. Here we need to take a break and check whether the previous steps are good. If everything is going well, when we click the Backend Health blade in Azure Portal, we’ll be able to see that the backend server is healthy as:

Application Gateway page - Backend Health labelApplication Gateway page – Backend Health label

Application Gateway Backend Health pageApplication Gateway Backend Health page

9. Finally, the last step is to make a CNAME record in your own domain DNS setting. In the overview page of Application Gateway, you’ll be able to find a domain name like Please create a CNAME record of the custom domain which you configured in API Management custom domain part and in Application Gateway to this domain name ending with Once it’s active, we should be able to visit our API Management from outside of Virtual Network.
Here is the example DNS setting:

Custom domain DNS settingCustom domain DNS setting


Common problems when using Application Gateway with API Management:  

When you use the Application Gateway with API Management, you maybe will meet some common issues like being unable to visit developer portal or the request sent to API Management or developer portal returns error code such as 502, 503 etc. Here is a summary of the common problems and possible solution. If this cannot resolve the issue, please create support ticket and our technical support engineer will be glad to assist. 

  1. When trying to call API or visit developer portal, 502 error code is returned.

For this scenario, there are 4 possible common reasons:

a. The backend health status is not healthy in Application Gateway Backend Health page (step 8 in previous part). 


1. Check the Network Security Group configuration to make sure that all necessary ports are open. 

2. Create a Virtual Machine in the same Virtual Network and visit the developer portal or call API from Virtual Machine to verify the API Management corresponding endpoint is healthy. 

b. The certificate uploaded in HTTP settings in Application Gateway doesn’t match the certificate used in the custom domain configuration in API Management. 


Upload the correct matching certificate in HTTP settings in Application Gateway. (Step 6 in previous part)

c. The timeout setting of HTTP settings in Application Gateway is too short. 


Reset the timeout setting of HTTP settings in Application Gateway (Step 6 in previous part)

d. The certificate used in Application Gateway or API Management expires.


Update both the timeout setting in API Management and Application Gateway


2. When trying to call API or visit developer portal, 503 error code is returned. 

For this scenario, there is 1 possible common reason: 

The custom domain name used in Application Gateway configuration and API Management custom domain configuration doesn’t match. 


Reconfigure the setting to make sure that the 2 custom domain names are the same one. 


3. When trying to visit new developer portal from Azure Portal “Overview” blade, the developer portal doesn’t open and show following message: 

Unable to start the portal 

Check if the settings specified in the configuration file are correct or refer to the frequently asked questions 

For this scenario, there is 1 possible common reason but we need one more step to verify whether it’s this situation:

Follow this document to capture the browser trace when opening developer portal and check whether there is a failed call to https://<management-endpoint-hostman>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview

If it’s true that there is such a failed call, then the reason is that user only enables the new developer portal endpoint in Application Gateway but doesn’t enable the management endpoint. 


Follow this blog to enable the management endpoint in Application Gateway.


4. When trying to visit new developer portal, the developer portal doesn’t open and show following message:

Oops, something went wrong.
We are unable to complete your operation this time. Please try again later.

For this scenario, there is 1 possible common reason but we need one more step to verify whether it’s this situation:

Follow this document to capture the browser trace when opening developer portal and check whether there is a failed call to https://<management-endpoint-hostman>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems?$orderby=en_us/title&$filter=en_us/permalink%20eq%20%27/%27&api-version=2018-06-01-preview with 403 error code

If it’s true that there is such a failed call, then the reason is that the Application Gateway Web Application Firewall is enabled in Prevention mode and this WAF blocked the requests. 


Change the configuration of Application Gateway WAF to disable the following rules:

Application Gateway WAF pageApplication Gateway WAF page

Application Gateway WAF rule pageApplication Gateway WAF rule page

1. For administrative mode of developer portal:

920330, 9331130, 942100, 942110, 942180, 942200, 942260,  942370, 949110, 980130 

2. For published portal:

942200, 942260, 942370, 942430, 942440 


Brought to you by Dr. Ware, Microsoft Office 365 Silver Partner, Charleston SC.