Edit

Configure a custom response for Azure Web Application Firewall (WAF)

  • Article
  • 2 minutes to read

By default, when WAF blocks a request because of a matched rule, it returns a 403 status code with The request is blocked message. The default message also includes the tracking reference string that can be used to link to log entries for the request. You can configure a custom response status code and a custom message with reference string for your use case. This article describes how to configure a custom response page when a request is blocked by WAF.

Configure custom response status code and message use portal

You can configure a custom response status code and body under "Policy settings" from the WAF portal.

WAF Policy settings

In the above example, we kept the response code as 403, and configured a short "Please contact us" message as shown in the below image:

Custom response example

"{{azure-ref}}" inserts the unique reference string in the response body. The value matches the TrackingReference field in the FrontDoorAccessLog and FrontDoorWebApplicationFirewallLog logs.

"{{azure-ref}}" inserts the unique reference string in the response body. The value matches the TrackingReference field in the FrontdoorAccessLog and FrontdoorWebApplicationFirewallLog logs.

Configure custom response status code and message use PowerShell

Set up your PowerShell environment

Azure PowerShell provides a set of cmdlets that use the Azure Resource Manager model for managing your Azure resources.

You can install Azure PowerShell on your local machine and use it in any PowerShell session. Follow the instructions on the page, to sign in with your Azure credentials, and install the Az PowerShell module.

Connect to Azure with an interactive dialog for sign-in

Connect-AzAccount
Install-Module -Name Az

Make sure you have the current version of PowerShellGet installed. Run below command and reopen PowerShell.

Install-Module PowerShellGet -Force -AllowClobber

Install Az.FrontDoor module

Install-Module -Name Az.FrontDoor

Create a resource group

In Azure, you allocate related resources to a resource group. Here we create a resource group by using New-AzResourceGroup.

New-AzResourceGroup -Name myResourceGroupWAF

Create a new WAF policy with custom response

Below is an example of creating a new WAF policy with custom response status code set to 405, and message to You are blocked., using New-AzFrontDoorWafPolicy

# WAF policy setting
New-AzFrontDoorWafPolicy `
-Name myWAFPolicy `
-ResourceGroupName myResourceGroupWAF `
-EnabledState enabled `
-Mode Detection `
-CustomBlockResponseStatusCode 405 `
-CustomBlockResponseBody "<html><head><title>You are blocked.</title></head><body></body></html>"

Modify custom response code or response body settings of an existing WAF policy, using Update-AzFrontDoorFireWallPolicy.

# modify WAF response code
Update-AzFrontDoorFireWallPolicy `
-Name myWAFPolicy `
-ResourceGroupName myResourceGroupWAF `
-EnabledState enabled `
-Mode Detection `
-CustomBlockResponseStatusCode 403

# modify WAF response body
Update-AzFrontDoorFireWallPolicy `
-Name myWAFPolicy `
-ResourceGroupName myResourceGroupWAF `
-CustomBlockResponseBody "<html><head><title>Forbidden</title></head><body>{{azure-ref}}</body></html>"

Next steps