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.
Pre-requirements:
Before starting, you must setup the environment at first.
To set up a local development environment, you need to have:
- API Management instance in tier which supports VNet. (We can confirm this at https://azure.microsoft.com/en-us/pricing/details/api-management/ ) 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.
- A 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 management.minalinsky.top -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:
- apimnewportal.minalinsky.top for new developer portal endpoint
- apimlegacyportal.minalinsky.top for legacy developer portal endpoint
- apimmanagement.minalinsky.top for management endpoint
- apimgateway.minalinsky.top 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:
- Follow this document to build an custom DNS zone to resolve the API Management custom domain
- 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.)
- 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 setting
- 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
- 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.
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.
- 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.
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.
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:
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:
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 somethinglikeid.cloudapp.net. 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 cloudapp.net. Once it’s active, we should be able to visit our API Management from outside of Virtual Network.
Here is the example 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.
- 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).
Solution:
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.
Solution:
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.
Solution:
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.
Solution:
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.
Solution:
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 config.design.json 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.
Solution:
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.
Solution:
Change the configuration of Application Gateway WAF to disable the following rules:
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