Public Preview: Custom WAF Block Status & Body for Azure Application Gateway

Introduction

Azure Application Gateway Web Application Firewall (WAF) now supports custom HTTP status codes and custom response bodies for blocked requests. This Public Preview feature gives you more control over user experience and client-side handling, aligning with capabilities already available on Azure Front Door WAF.

Why this matters

Previously, WAF returned a fixed 403 response with a generic message. Now you can:

• Set a custom status code (e.g., 403, 429) to match your app logic.
• Provide a custom response body (e.g., a friendly error page or troubleshooting steps).
• Ensure consistency across all blocked requests under WAF policy.

This feature improves user experience (UX), helps with compliance, and simplifies troubleshooting.

Key capabilities

• Custom Status Codes: Allowed values: 200, 403, 405, 406, 429, 990–999.
• Custom Response Body: Up to 32 KB, base64-encoded for ARM/REST.
• Policy-level setting: Applies to all blocked requests under that WAF policy.
• Limit: Up to 20 WAF policies with custom block response per Application Gateway.

Configure in the Azure Portal

Follow these steps:

1. Sign in to the https://portal.azure.com.
2. Navigate to your WAF Policy linked to the Application Gateway.
3. Under Settings, select Policy settings.
4. In the Custom block response section:
5. Block response status code: Choose from allowed values (e.g., 403 or 429).
6. Block response body: Enter your custom message (plain text or HTML).
7. Save the policy.
8. Apply the policy to your Application Gateway if not already associated.

Configure via CLI

az network application-gateway waf-policy update \
--name MyWafPolicy \
--resource-group MyRG \
--custom-block-response-status-code 429 \
--custom-block-response-body "$(base64 custompage.html)"

Configure via PowerShell

Set-AzApplicationGatewayFirewallPolicy `
-Name MyWafPolicy `
-ResourceGroupName MyRG `
-CustomBlockResponseStatusCode 429 `
-CustomBlockResponseBody (Get-Content custompage.html -Encoding Byte | [System.Convert]::ToBase64String)

Tip: For ARM/REST, the body must be base64-encoded.

Best practices

• Use meaningful status codes (e.g., 429 for rate limiting).
• Keep the response body lightweight and informative.
• Test thoroughly to ensure downstream systems handle custom codes correctly.

Resources

• Configure Custom Response code
• Learn more about Application Gateway WAF