Rewrite HTTP request and response headers with Azure Application Gateway - Azure PowerShell

This article describes how to use Azure PowerShell to configure an Application Gateway v2 SKU instance to rewrite HTTP headers in requests and responses. Header rewriting enables you to add, remove, or update HTTP headers while the request and response packets move between the client and backend pools.

If you don't have an Azure subscription, create a Trial before you begin.

Before you begin, ensure you have the following requirements:

• Azure PowerShell: You need Azure PowerShell installed locally. The Azure PowerShell Az module version 1.0.0 or later is required. To check your version, run Get-Module -ListAvailable Az. If you need to upgrade, see Install Azure PowerShell module.
• Azure connection: After verifying the PowerShell version, run Connect-AzAccount to authenticate with Azure.
• Application Gateway v2: You need an existing Application Gateway v2 SKU instance. Header rewriting is only supported in the v2 SKU (Standard_v2 or WAF_v2). If you don't have one, create an Application Gateway v2 SKU instance before you begin.
• Proper permissions: Ensure you have Contributor or Owner permissions on the Application Gateway resource.

To configure HTTP header rewrite, you need to understand and create the following components in a specific order:

1. RequestHeaderConfiguration: Specifies the request header fields you want to rewrite and their new values. Use this component to modify headers in client requests before they reach the backend servers.

2. ResponseHeaderConfiguration: Specifies the response header fields you want to rewrite and their new values. Use this component to modify headers in server responses before they reach the client.

3. ActionSet: Contains the configurations of the request and response headers specified. Each action set represents a collection of header modifications to perform.

   • Condition: An optional configuration. Rewrite conditions evaluate the content of HTTP(S) requests and responses. The rewrite action occurs if the HTTP(S) request or response matches the rewrite condition.

   Note

   Multiple conditions associated with an action use logical AND operation - all conditions must be met for the action to execute.

4. RewriteRule: Combines multiple rewrite actions and rewrite conditions. Each rule defines when and how to modify headers.

5. RuleSequence (Optional): Determines the execution order when you have multiple rewrite rules in a rewrite set. Rules with lower sequence values execute first. If you don't specify a value, the default is 100.

   Warning

   If you assign the same sequence value to multiple rules, the execution order becomes non-deterministic.

6. RewriteRuleSet: Contains multiple rewritten rules that are associated with a request routing rule.

The rewrite configuration scope depends on the routing rule type:

• Basic routing rule: Header rewrite configuration applies globally to all requests for the associated listener
• Path-based routing rule: Header rewrite configuration applies only to requests matching specific URL path patterns defined in the URL path map

Before configuring header rewrite rules, authenticate with Azure and select your subscription:

Connect-AzAccount -Environment AzureChinaCloud
Select-AzSubscription -Subscription "<sub name>"

In this example, we modify a redirection URL by rewriting the location header in the HTTP response whenever the location header contains a reference to chinacloudsites.cn. To do this modification, we add a condition to evaluate whether the location header in the response contains chinacloudsites.cn. We use the pattern (https?)://.*chinacloudsites.cn(.*)$. And we use {http_resp_Location_1}://contoso.com{http_resp_Location_2} as the header value. This value replaces chinacloudsites.cn with contoso.com in the location header.

$responseHeaderConfiguration = New-AzApplicationGatewayRewriteRuleHeaderConfiguration -HeaderName "Location" -HeaderValue "{http_resp_Location_1}://contoso.com{http_resp_Location_2}"
$actionSet = New-AzApplicationGatewayRewriteRuleActionSet -ResponseHeaderConfiguration $responseHeaderConfiguration
$condition = New-AzApplicationGatewayRewriteRuleCondition -Variable "http_resp_Location" -Pattern "(https?):\/\/.*chinacloudsites\.cn(.*)$" -IgnoreCase
$rewriteRule = New-AzApplicationGatewayRewriteRule -Name LocationHeader -ActionSet $actionSet -Condition $condition
$rewriteRuleSet = New-AzApplicationGatewayRewriteRuleSet -Name LocationHeaderRewrite -RewriteRule $rewriteRule

$appgw = Get-AzApplicationGateway -Name "AutoscalingAppGw" -ResourceGroupName "<rg name>"

Get the specific request routing rule where you want to apply the header rewrite configuration:

$reqRoutingRule = Get-AzApplicationGatewayRequestRoutingRule -Name rule1 -ApplicationGateway $appgw

In this example, the rewrite set would be associated instantly against a basic routing rule. In a path based routing rule, the association wouldn't be enabled by default. The rewrite set can be enabled either via -- checking the paths on which it needs to be applied via portal or by providing a URL path map config specifying the RewriteRuleSet against each path option.

Add-AzApplicationGatewayRewriteRuleSet -ApplicationGateway $appgw -Name $rewriteRuleSet.Name  -RewriteRule $rewriteRuleSet.RewriteRules
Set-AzApplicationGatewayRequestRoutingRule -ApplicationGateway $appgw -Name $reqRoutingRule.Name -RuleType $reqRoutingRule.RuleType -BackendHttpSettingsId $reqRoutingRule.BackendHttpSettings.Id -HttpListenerId $reqRoutingRule.HttpListener.Id -BackendAddressPoolId $reqRoutingRule.BackendAddressPool.Id -RewriteRuleSetId $rewriteRuleSet.Id
Set-AzApplicationGateway -ApplicationGateway $appgw

If you need to remove a rewrite rule set from your Application Gateway, use the following steps:

# Retrieve the current Application Gateway configuration
$appgw = Get-AzApplicationGateway -Name "AutoscalingAppGw" -ResourceGroupName "<rg name>"

# Remove the rewrite rule set association from the routing rule first
$requestRoutingRule = Get-AzApplicationGatewayRequestRoutingRule -Name "rule1" -ApplicationGateway $appgw

# Clear the rewrite rule set reference
$requestRoutingRule.RewriteRuleSet = $null

# Remove the rewrite rule set from the Application Gateway
Remove-AzApplicationGatewayRewriteRuleSet -Name "LocationHeaderRewrite" -ApplicationGateway $appgw

# Apply the changes
Set-AzApplicationGateway -ApplicationGateway $appgw

Write-Output "Rewrite rule set removed successfully"

Now that you learned how to configure HTTP header rewrite rules, explore these related articles:

• Common scenarios: Learn about common header rewrite scenarios including security headers, custom routing, and backend server integration patterns.

• Monitoring and troubleshooting: Set up Application Gateway diagnostics to monitor header rewrite operations and troubleshoot issues.