Securing External APIs with Azure Application Gateway and Azure API Management
Given the escalating web-based threats, it’s crucial to adopt a robust security strategy. A key element of this strategy is the Gateway Routing pattern, a powerful tool that not only fortifies network traffic protection but also empowers you with the ability to impose restrictions on traffic sources and quality, all while facilitating dynamic routing rules.
In this pattern, the API Management service takes centre stage, deployed within an internal virtual network for heightened security. It’s followed by the deployment of an Application Gateway, a protective layer that shields against OWASP vulnerabilities. This gateway provides load-balancing capabilities across seven layers and incorporates a Web Application Firewall (WAF), bolstering your security measures.
It is important to note that resources will be created through the Azure Portal for this lab. These resources are designed to provide a foundational understanding of the implementation of the Gateway Routing pattern, ensuring a comprehensive learning experience.
The resources for this lab were built on Window 11 as such the details in the Generate Self-Signed Certificates and Validating the Implementation sections will need to be altered if a different OS is being used.
High Level Deployment View
The following diagram provides a high-level view of the resources that are deployed as part of this implementation.
Resource Group
Since this is a lab environment for learning purposes, everything will be deployed as a single Resource Group for simplicity.
- Create Resource Group.
Virtual Network
This implementation requires a VNET with two subnets with NSGs and two Public IP Addresses. Both the APIM instance and App Gateway instances require a dedicated subnet each to ensure that these services can be scaled out in future.
These are the steps required to configure the network-related resources needed before you can deploy the APIM and App Gateway instances.
1. Create a VNET.
2. Create a subnet for the APIM Instance.
3. Create an NSG for the APIM subnet, configure Inbound and Outbound rules and associate it with the APIM subnet. See details for Inbound and Outbound rules below.
4. Create a subnet for the App Gateway Instance.
5. Create an NSG for the App Gateway subnet, configure Inbound rules and associate it with the App Gateway subnet. See details for Inbound and Outbound rules below.
Please note that you need to specify an IP address in the App Gateway subnet that will be set as the App Gateway’s Private IP Address. This IP address will be used when creating the App Gateway instance.
Important — the Inbound rule for the App Gateway subnet must be set at a higher priority than the specific rule for the App Gateway instance’s public and private IP addresses.
6. Create a Public IP Address for the APIM instance. It must be set to Microsoft network routing reference.
7. Create a Public IP Address for the App Gateway instance. Must be set to Internet routing reference.
After completing these steps, the Resource Group should contain the following resources.
The Azure Network Watcher is a free tool for monitoring, diagnosing, viewing metrics, and enabling/disabling logs for resources in an Azure VNET. It is automatically deployed when the first VNET is created in a Subscription. If you are using a subscription that does not already contain a VNET, you will also notice a new NetworkWatcherRG resource group.
Generate Self-Signed Certificates
Self-signed digital certificates will be used in this lab to secure the APIM and App Gateway endpoints.
The sample PowerShell script below creates a Root CA certificate and generates certificates signed by the Root CA certificate as .pfx files with a password of ‘password1’.
- rootca-dev.cer — Root CA
- api-dev-cert.pfx — App Gateway
- proxy-dev-cert.pfx — Proxy APIM Endpoint
- management-dev-cert.pfx — Management APIM Endpoint
- portal-dev-cert.pfx — Portal APIM Endpoint
Update the $env, $domain and $CnPrefix variables to change the Root CA, Domain and CN of the certificates.
Generate Self-Signed Certificate Script
$env = 'dev'
$domain = 'demo.com'
$CnPrefix = 'portal','proxy','management','api'
#Create the root certificate for the self-signed certificate
$param1 = @{
Subject = "CN=$env.$domain, C=AU"
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.cert
$path = ".\rootca-$env.cer"
# 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 ".\rootca-$env.cer"
function Generate-Cert {
param (
[String[]]$cnPrefix
)
foreach ($cn in $cnPrefix) {
$param2 = @{
DnsName = "*.$domain"
Subject = "$cn.$domain"
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 ".\$cn-$env-cert.pfx" -Password (ConvertTo-SecureString -AsPlainText 'password1' -Force)`
}
}
Generate-Cert -cnPrefix $CnPrefixDeploy APIM
Now that the networking prerequisites have been completed, the APIM instance can be created using these components — specifically, the APIM subnet and the APIM Public IP Address.
Please note that only the Developer and Premium tier of the APIM service support VNET integration.
Create an APIM instance specifying the Developer pricing tier and virtual network settings referencing the VNET, APIM subnet and APIM Public IP Address created in the previous steps.
Once the APIM instance provisioning process is initiated, it will take between 15–45 minutes for the instance to be ready for use. At this point, an email will be sent to the Administrator email, notifying them of the instance’s readiness.
Once the APIM instance has been deployed, it should be available with a public and private IP address. While the public address is available, it will not be used to access the instance in this implementation.
Verifying APIM Network Configuration
The APIM Network configuration can be verified by navigating to the Network status tab in Network under Deployment + infrastructure on the APIM instance.
Configure Custom Domains
Now that the APIM instance is deployed in Internal VNET mode, the custom domains can be configured using the self-signed certificate generated during the previous steps.
By default, the APIM instance is available through the *azure-api.net subdomain.
We will create a custom domain for the following APIM endpoints in this lab.
- Gateway — Proxy endpoint for accessing APIs.
- Developer Portal — This is the endpoint for accessing the developer portal. Please note that this is the new Developer Portal, not the Deprecated developer portal.
- Management — Management endpoint for APIM instance.
These are the high-level steps required to configure the custom domains for the APIM instance. Please ensure that these steps are repeated for each of the three endpoints: Gateway, Developer Portal, and Management.
- In the portal, navigate to Custom domains under the Deployment + infrastructure section on the APIM instance and click Add.
- Specify the endpoint Type, Hostname and Certificate details, including the password for the *.pfx file.
Further information about configuring custom domains can be found here.
The custom domain configuration for the APIM instance should look similar to the screen capture below.
Deploy Private DNS Zone
When Azure APIM is deployed in Internal VNET mode, you need to manage your own DNS servers to resolve the names of your APIM endpoints. This lab uses Azure Private DNS to fulfil this requirement.
Further details on creating a Private DNS Zone can be found here.
These are the high-level steps required to configure the Azure Private DNS zone necessary for the APIM instance.
1. Create a Private DNS Zone specifying the domain name as the domain suffix of the APIM endpoint created in the previous steps.
2. Once the Private DNS Zone has been created, navigate to the zone and click Record Set to add A record entries for each APIM instance endpoint created when configuring the custom domains in the previous steps.
These records should be set to the APIM instance’s internal IP address, and the Private DNS zone name should be part of the FQDN for the hostname.
The A record entries should look similar to the screen capture below.
3. Create a virtual network link to link the Private DNS zone created in the previous step to the VNet you created earlier. Under Settings in your Private DNS Zone, navigate to virtual network links.
Deploy App Gateway
This implementation uses the Application Gateway WAF V2 service tier. The Web Application Firewall (WAF) on Azure Application Gateway is based on the Core Rule Set (CRS) from the Open Web Application Security Project (OWASP).
All the WAF configuration settings are encapsulated within a WAF policy, providing you with flexible and granular control over your security settings. WAF policies can be associated with an App Gateway instance, individual listeners, or path-based routing rules within the App Gateway instance, allowing you to tailor your security measures to your specific needs.
When deploying an App Gateway instance, an initial configuration must be provided for the backend pool, backend settings, and routing rule.
In this section, the App Gateway instance is deployed with a WAF Policy that will be created during the deployment and the initial configuration for the proxy endpoint in APIM.
Once the App Gateway has been deployed, additional steps are required to configure the custom health probe for the proxy endpoint in APIM and the configuration needed for the management and portal endpoints in APIM.
Deploying the App Gateway Instance
These are the high-level steps required to configure the App Gateway instance, which include creating a WAF Policy and configuring the Backend Pool, Backend Settings, and Routing Rule for the proxy endpoint in the APIM instance. Specify the WAF V2 as the Tier
1. Specify the WAF V2 as the Tier and click Create new next to WAF Policy
2. Set the Frontend IP address type to Both and specify the App Gateway Public IP Address created in the earlier steps as the Public IPv4 address and the Private address as the IP address used in the NSG Inbound rule created for the App Gateway subnet.
3. Create the Backend Pool for the proxy endpoint in APIM, specifying the FQDN as the custom domain name for the proxy custom domain endpoint in APIM.
4. Create a Routing rule to link the proxy frontend to the backend pool in the Configuration tab.
Define a multi-site listener with a single hostname that uses the App Gateway certificate created in the previous steps.
The hostname must be equal to the FQDN so that the endpoint will be available externally.
The Backend setting configuration will use the Root CA certificate we created earlier to allow the SSL handshake to complete from App Gateway to the proxy endpoint and allow the backend endpoint to override the hostname.
Configuring the Custom Health Probe — Proxy Endpoint
APIM requires Custom Health Probes when integrating with App Gateway. After deploying the App Gateway as per the previous steps, an error message will be displayed regarding the health of the backend pool.
Creating the custom health probe for the proxy endpoint in APIM is a straightforward process. Simply follow these steps to complete it.
1. Navigate to Health probes under Settings in the App Gateway instance and click Add if one was not created during the deployment of the App Gateway instance or edit the one already created.
2. Ensure the configuration of the health probe matches the screen capture below, click Test, and then Save.
Please note that the path for any custom domain that maps to the built-in Gateway APIM endpoint must be /status-0123456789abcdef.
Configuring the Management Endpoint
In this section will configure the custom domain for the management endpoint in APIM with the App Gateway instance.
1. Create the listener using the App Gateway self-signed digital certificate created in the previous steps by navigating to Listeners under Settings in the App Gateway instance and clicking Add listener.
2. Create the Backend Pool specifying the FQDN for the custom domain mapping to the management APIM endpoint created in the previous steps.
3. Create the custom Health Probe that will be applied the Backend Settings in the next step. Navigate to Health probes under Settings in the App Gateway instance and click Add.
Ensure the configuration of the health probe matches the screen capture below, untick the option to test the health probe and click Add.
Please note that the path for the management probe must be /ServiceStaus.
4. Create the Backend Settings, specifying the Self-Signed Root CA digital certificate created in the previous steps, the Override with new host name with Pick host name from backend target option and the newly created custom Health Probe.
Please note the Self-Signed Root CA certificate should be available as an existing certificate as it was added with apimProxy backend settings defined during the creation of the App Gateway instance.
5. Create a Routing rule to link the management frontend to the backend pool by specifying the listener configuration and backend pool and backend settings created for the management APIM endpoint in the previous steps.
Configuring the Portal Endpoint
In this section will configure the custom domain for the portal endpoint in APIM with the App Gateway instance.
1. Create the listener using the App Gateway self-signed digital certificate created in the previous steps by navigating to Listeners under Settings in the App Gateway instance and clicking Add listener.
2. Create the Backend Pool specifying the FQDN for the custom domain mapping to the portal APIM endpoint created in the previous steps.
3. Create the custom Health Probe that will be applied to the Backend Settings in the next step. Navigate to Health probes under Settings in the App Gateway instance and click Add.
Ensure the configuration of the health probe matches the screen capture below, untick the option to test the health probe and click Add.
Please note that the path for the management probe must be /signin.
3. Create the Backend Settings, specifying the Self-Signed Root CA digital certificate created in the previous steps, the Override with new hostname with Pick hostname from the backend target option and the newly created custom Health Probe.
Please note the Self-Signed Root CA certificate should be available as an existing certificate as it was added with apimProxy backend settings defined during the creation of the App Gateway instance.
4. Create a Routing rule to link the portal frontend to the backend pool by specifying the listener configuration and backend pool and backend settings created for the portal APIM endpoint in the previous steps.
Final App Gateway Configuration
The configuration in the App Gateway instance should now look similar to the screen captures below.
Validating the Implementation
To ensure that the setup is working as expected, we can try to browse any of the configured endpoints from the local machine.
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.
- <App Gateway Public IP Address> proxy.demo.com
- <App Gateway Public IP Address> management.demo.com
- <App Gateway Public IP Address> portal.demo.com
Production Implementation
The following should be considered before implementing this solution in a Production environment.
Multiple Resource Groups — This strategic approach organises resources logically and enhances manageability and troubleshooting. By grouping resources based on deployment frequency and lifecycle, you can streamline support activities, reduce complexity, and optimise your operations.
Centralised Logging and Debugging — Deploying Log Analytics and Application Insights instances enables centralised monitoring, logging, and debugging of your application. This is crucial for troubleshooting issues, analysing performance, and gaining insights into usage patterns.
Infrastructure as Code (IaC) — Implementing infrastructure as code allows you to define and manage your infrastructure using code, typically with tools like Terraform or Azure Resource Manager templates. Using CI/CD pipelines for deployment and configuration ensures consistency, repeatability, and automation, reducing manual errors and speeding up the deployment process.
Digital Certificates from Valid CA — Obtaining digital certificates from a trusted Certificate Authority (CA) is a security measure that should be considered. It enhances security by ensuring your services are encrypted and authenticated, fortifying your communication channels, and building trust with users.
Custom Domain and DNS Configuration — Using a custom domain and configuring DNS to point to the Public Address of the Application Gateway adds a professional touch to your application and enhances its accessibility. It makes your application easier to access and improves its branding.
Authentication and Authorisation — Implement authentication mechanisms like OAuth 2.0, OpenID Connect, or API keys to secure Developer Portal access, authenticating developers before they utilise features such as API documentation, testing consoles, and community forums while leveraging single sign-on (SSO) solutions for integration with existing identity providers; for authorisation, establish role-based access control (RBAC) policies defining permissions for features and resources, assigning roles such as developer, administrator, or guest, and implementing fine-grained access controls, particularly for sensitive operations; within the APIM instance, use OAuth 2.0 or API keys to authenticate API consumers, enforce access policies and scopes, and implement rate limiting, quotas, and throttling to manage API usage and prevent abuse for the Developer Portal and APIs.
Policy Enforcement in APIM — API policies within APIM enforce authentication, authorisation, and other security measures, including JWT validation, OAuth token validation, and CORS enforcement at the API gateway level to secure API endpoints, alongside transformation policies that sanitise requests and responses to ensure data privacy and integrity.
Troubleshooting Tips
We’ll address some common troubleshooting scenarios that may arise when integrating an APIM service with an Application Gateway.
Unknown Backend Health
It’s common to encounter backend health stuck in an Unknown state after setup completion. A critical bottleneck could be the Network Security Group (NSG) associated with the subnet where the App Gateway resides.
If NSGs are required, specific guidelines must be followed as documented here.
Additional areas to investigate for Unknown backend health can be found here.
Isolating Issues in the Pipeline
Given the involvement of multiple components in this configuration, it’s advisable to pinpoint any issues to the specific component not functioning as expected.
One method is to utilize a Jump Box VM
Create an Azure VM within the same Virtual Network (VNet) as the APIM.
For a quick test, update the VM’s host file with the private IP and endpoints for the APIM service.
If the APIM service is accessible from this VM within the same VNet, it helps narrow down the issue to the App Gateway and DNS configuration.
FAQs
Can standalone certificates be used in the deployment?
No, standalone certificates cannot be used. A root certificate from the chain (in .cer format) is required to configure the app gateway.
Why are the links to my Developer Portal and the Publisher Portal of the APIM instance greyed out on the Azure Portal?
When the APIM service is deployed within an internal virtual network, it becomes inaccessible to the public Internet. However, you can successfully access these links from any local machine with either the Application Gateway Public IP mapped to the APIM custom domain names or with a custom DNS functioning as expected.
You should now have a foundational understanding of integrating Azure API Mangement with Azure Application Gateway to implement a Gateway Routing Pattern and securely expose internal APIs to external consumers.
I hope you found this lab useful. Happy learning.
