Integrating API Management with App Gateway V2

 

Integrating Application Gateway (v2) with API Management service in Internal Virtual network

 

Use Case

API Management service can be configured in Internal Virtual Network mode which makes it accessible only from within the Virtual Network. Using Application Gateway provides users the ability to protect the API Management service from OWASP vulnerabilities. Application gateway is a reverse proxy service which has a 7-layer load balancer and provides Web Application Firewall (WAF) as one of the services in this use case.

Internal Routing

In this configuration, all the calls that hit the APIM Service pass through the Application Gateway. A blocker here could be that Application Gateway routes the calls using IP address; However, APIM works on the basis of host names. Since there is only one private IP designated to all the endpoints of APIM service, we need to configure Application Gateway in such a manner that the respective host name is supplied to the APIM internal load balancer as per the call that needs to be routed to the designated endpoint (portal, management, proxy, et cetera)

Configuring the APIM

1. Create an APIM Service following the steps explained in the below article : https://docs.microsoft.com/en-us/azure/api-management/get-started-create-service-instance
2. Create a Virtual network under your Azure Subscription in the same location as that of APIM. Use this same VNet to deploy the APIM service in Internal VNet mode.
3. Once configured, you would observe a Private IP for your APIM service on the Overview blade of the APIM Azure Portal. In this case, the private IP is 10.1.1.5

APIM in Private Vnet

4. When the APIM service is in Internal VNet mode and the associated subnet has an NSG configured, there are certain network configurations that you need to add to the NSG associated to the subnet within which the APIM service resides.
5. The following public documentation highlights these in detail and specifies all the ports that you would need to set in order to enable accessibility to the APIM service:

https://docs.microsoft.com/en-us/azure/api-management/api-management-using-with-vnet#-common-network-configuration-issues

 

Setting up Custom Domains

When you create an Azure APIM service, Azure assigns it a subdomain of azure-api.net (for example, apim-service-name.azure-api.net). However, you can also expose your APIM endpoints using your own custom domain name, such as xyz.com

 

1. Under the Settings section, navigate to the Custom Domains blade on your API Management service.
2. As you click the Add button, a new window would allow you to choose the type of endpoint along with the custom domain name you would like to configure.
3. For this setup, I have used the management, proxy and portal endpoints of the APIM service to be invoked with the highlighted host name. Please be cautious to use new portal endpoint for configuration ( not legacy one)

   Setting up Custom Domains

4. As observed, when you add a custom domain with the preferred host name, you would need to furnish it with a valid .pfx certificate associated to the host name.
5. The certificate to be used need to be different if you are using Application gateway version V1 or V2, this document explains in detail about the difference in certificates to be used : https://docs.microsoft.com/en-us/azure/application-gateway/certificates-for-backend-authentication#export-trusted-root-certificate-for-v2-sku
6. Wrapping it up as a  reference to above screenshot, Since I have been using hostnames for 3 different endpoints , V2 version would expect me to use 3 different certificates in .pfx format
7. You can use any of the tools  like open ssl to create self-signed certificates. If you would like to do it using PowerShell, here is a sample script that can come handy :

 

# Create the root certificate for the self-signed certificate

$param1 = @{

  Subject = "CN=xyz, C=US"

  KeyLength = 2048

  KeyAlgorithm = 'RSA'

  HashAlgorithm = 'SHA256'

  KeyExportPolicy = 'Exportable'

  NotAfter = (Get-Date).AddYears(5)

  CertStoreLocation = 'Cert:\LocalMachine\My'

  KeyUsage = 'CertSign','CRLSign'

}

$rootCA = New-SelfSignedCertificate @param1

 

 

# Grab the thumbprint of the root certificate

$thumb = $rootCA.Thumbprint

$root = Get-Item -Path Cert:\LocalMachine\My\$($thumb)

#This is a path you want to download the .cer of the root certificate.

$path = "<add your local path here>"

 

 

# Export the root certificate in a Base64 encoded X.509 to the path created above

$base64certificate = @"

-----BEGIN CERTIFICATE-----

$([Convert]::ToBase64String($root.Export('Cert'), [System.Base64FormattingOptions]::InsertLineBreaks)))

-----END CERTIFICATE-----

"@

Set-Content -Path $path -Value $base64certificate

 

 

# Import the root certificate of the self-signed certificate to the local machine trusted root store

Import-Certificate -CertStoreLocation 'Cert:\CurrentUser\My' -FilePath "<update file path here>"

 

 

# Create a new self-signed certificate and then link the root and the self-signed certificate

$param2 = @{

    DnsName = '*.azure-apim.net'

    Subject = "management.azure-apim.net"

    Signer = $rootCA

    KeyLength = 2048

    KeyAlgorithm = 'RSA'

    HashAlgorithm = 'SHA256'

    KeyExportPolicy = 'Exportable'

    CertStoreLocation = 'Cert:\LocalMachine\My'

    NotAfter = (Get-date).AddYears(2)

}

$selfCert = New-SelfSignedCertificate @param2

 

 

# Export the certificate in .pfx format for the application gateway listener and ASE ILB Cert.

Export-PfxCertificate -Cert $selfCert -FilePath "<update file path>" -Password (ConvertTo-SecureString -AsPlainText '< choose password>' -Force)`

 

 

 

1. As highlighted in the PowerShell script, you would have to make the changes as per your local environment.  A sample file path that you could provide would look something like this: “C:\Users\kwill\management.pfx”
2. The subject part of the endpoint should change as per the endpoint you are using the certificate for. In this case, I have used the management endpoint since I would use this certificate for creating custom domain for my management endpoint.
3. Run this script for all the endpoints that you wish to be mapped. This should yield you different certificates associated to the host names.
4. Another thing worth mentioning is that if an APIM is configured to be in Internal VNet mode, it is expected to be running on its own custom DNS servers, and not Azure DNS.

Solving the issue for custom DNS

• To mimic the custom DNS servers, we would be using the Azure Private DNS Zone offering.
• Here are the steps that you could follow to create Private DNS zone: https://docs.microsoft.com/en-us/azure/dns/private-dns-getstarted-portal
• The A records for the private DNS zones constitute the three endpoints of the APIM service pointing to the private IP of the service.

Configuring Private DNS zones

 

• One key point to remember is the Private DNS zone name should be a part of the FQDN for the host name.
• In the above example. I have used the name as azure-apim.net , so that we can use all the endpoints as A records for the APIM Private IP.
• Navigate to the Virtual Network Links blade of the private DNS Zone and link the Virtual Network. This would complete the setup for private DNS zones.

At this point of time, your APIM service has been configured to run inside a Virtual Network along with the custom domains.

Setting up App Gateway

1. You can create the App Gateway using the steps explained in the below documentation:

2. This article assumes that you have configured v2 version for the App Gateway as we move along with the setup ahead.
3. As highlighted in the public documentation above, App Gateway has certain mandatory components that needs to be configured when we create it. We would be covering the details of the same below:

 

• Backend Pool: App Gateway needs at least one backend pool to be configured during creation. Use the custom domain hostname of the API Management instance to be configured in the backend pool section.

 

Backend Pool Configuration

 

• As a reference, we would be starting with the management endpoint configuration for now. You can repeat the same steps for Proxy or Portal endpoints.
• We would be using three different backend pools for all the custom domains that we had configured earlier.
• Use the custom domain hostname to be used as an FQDN in the backend pool. Let us call it managementbackend.

 

• HttpSettings: These are the settings which include the protocols and probes configuration that the Application Gateway would be using to connect to the backend host names of APIM service.

 

Adding Http Settings

 

• To sync with the managementbackend(backend pool) highlighted in the previous step, we would go ahead and configure http settings called managementhttp

 

• Important point to note here is that the certificate to be added here has to be the root certificate (in .cer fomat) of the .pfx certificate that we created while creating the custom domains.
• In a nutshell, I would use the management endpoint .pfx certificate and export it to .cer format. Later, we would need the root certificate of the exported certificate (in .cer format) to whitelist the management endpoint.
• Kindly follow this documentation which contains a step-by-step demo for setting up certificates for v2 version Application Gateway:

https://docs.microsoft.com/en-us/azure/application-gateway/certificates-for-backend-authentication#export-trusted-root-certificate-for-v2-sku . This step is crucial, and not having a valid root certificate may result in Internal Server Errors while deploying the Application Gateway.

• As we scroll down, we need to select Yes for Override with new host name and Click on Pick host name from backend target (since hostname has already been specified in the backend pool)

 

 

• This would associate the Http settings to the backend pool that we created for the management endpoint.
• We would need to configure different Http settings for different backend pools that we create (in case we need to add proxy and portal endpoint).

 

• Health Probes: These are the probes that would constantly keep checking the connection between the Application Gateway and the APIM service and would set the backend health value as per the configuration

 

• As observed, there would be multiple probes configured for multiple Http settings which would indicate the backend health for all the endpoints.
• In case of proxy probe, /status 0123456789abcdef is a common health endpoint for the APIM service.

 

• Listeners: We would be configuring different Listeners for different hostnames which are to be used in the Application Gateway

 

 

• Each of the listener would have a rule configured along with the hostname that we would associate it to.
• Running through the managementlistener in this case, which has been setup to cater to the management hostname:

 

• Please note that the certificate should be the same certificate in .pfx format that we had used earlier to create the management endpoint custom domain in APIM instance.
• Since API management supports multiple endpoints, use a multi-site listener and add the associated hostname (which is the management hostname in this case)

 

• Rules: We need to add routing rules that would be associated to the listeners and would have the configuration of the backend pool.

 

 

• Add the backend targets with the backend pool and the Http settings that we had created earlier for the management endpoint.

 

• Backend health: Backend health blade helps us verify whether the setup is working as expected. It would yield the results based on the probing checks of the health probes that we had previously configured for different end points.

 

 

• A Healthy status in the backend health indicates that the App Gateway is able to talk to the API management service.

Validating the setup

1. To ensure that the setup is working as expected, we can try to browse any of the configured endpoints from the local machine.
2. Update the host file from this location (C:\Windows\System32\drivers\etc) on the local machine with the following additional entries as per the required configuration

• As observed, we need to map the public IP of the App Gateway to the hostname of the custom domains.
• When you attempt to browse any of these endpoints from the local machine, you should be able to successfully hit the APIM instance.

 

COMMON TROUBLESHOOTING SCENARIOS:

We would be covering some of the common Troubleshooting scenarios that might arise when we integrate an APIM service with an Application Gateway.

1. Unknown backend health

Quite often, we might have observed the backend health to be stuck in an Unknown state after completing the setup. The primary bottleneck could be the NSG associated with the subnet within which the App Gateway is setup.

If your requirement needs one of more NSGs to be in place then, you need to follow certain guidelines as documented below:

https://docs.microsoft.com/en-us/azure/application-gateway/configuration-overview#network-security-groups-on-the-application-gateway-subnet

 

Other possible areas to check for Unknown backend health have been documented in another article:

https://docs.microsoft.com/en-us/azure/application-gateway/application-gateway-backend-health-troubleshooting#backend-health-status-unknown

 

2.  Isolating the issue in the pipeline

Since there are multiple components involved in this configuration, it is always a good practice to narrow down any issue faced to the specific component that is not working as expected.

• One easy way of doing this would be using a Jump Box VM.
• Create a sample Azure VM in the same VNet as that of the APIM.
• For a quick test, we can update the VM’s host file with the private IP and the endpoints for the APIM Service.
• If the APIM service is accessible from this VM which is a part of the same VNet, we would be able to narrow the issue down to App Gateway and DNS configuration.

 

FREQUENTLY ASKED QUESTIONS (FAQs)

 

• Is it mandatory to have NSGs in place running with the subnet of either the APIM or App Gateway in the setup?

This depends on your business requirement. If your organization needs to have NSG(s) enabled, you will need to whitelist the IP addresses as specified in the documentation above. There are no restrictions from Azure end while creating a setup without NSG.

• Can we use standalone certificates in the deployment?

No, since we would need the root certificate out of the chain ( in .cer format ) for the app gateway configuration.

 

• Can the subnet hosting the APIM service be used for hosting other services?

No. The subnet within which the APIM service is deployed has to be a dedicated subnet. No other resource can share the same subnet. This is because, if the APIM service has to be scaled out in the future, the subnet should be able to have sufficient IP addresses reserved for the new instances of the APIM service.

• Why are the links to my Developer Portal and the Publisher Portal of the APIM instance grayed out on the Azure Portal?

Since you have deployed the APIM service within an Internal Virtual Network, it is no longer accessible over the public internet. You can successfully browse the same links from any local machine which has the Application Gateway Public IP mapped to the APIM custom domain names or has a custom DNS working as expected.

 

             

Happy Learning!