Networking Application delivery and API edge template-specs-upgraded

Rewrite rule

A rewrite rule tells Azure Application Gateway to change parts of a request or response while traffic passes through the gateway. It can adjust a URL path, query string, host name, or HTTP header without forcing the browser to visit a different address. That makes it useful when backends expect different paths, when security headers must be added, or when noisy response headers should be removed. The rule can run for all matching traffic or only when conditions match specific headers or server variables.

Aliases
Application Gateway rewrite rule, URL rewrite rule, HTTP header rewrite rule, rewrite rule set, App Gateway rewrite
Difficulty
intermediate
CLI mappings
6
Last verified
2026-05-22

Microsoft Learn

Microsoft Learn explains that Application Gateway rewrite rules can modify selected request or response content, including URLs, query strings, and HTTP headers, when configured conditions match. Rewrite sets attach to routing rules, work on the v2 SKU, and can affect WAF inspection order and backend behavior.

Microsoft Learn: Rewrite HTTP headers and URL with Application Gateway2026-05-22

Technical context

In Azure architecture, a rewrite rule lives inside an Application Gateway rewrite rule set and is associated with a request routing rule or a path-based routing rule. It belongs to the application delivery layer, between client-facing listeners and backend pools. Operators manage it through ARM, Bicep, portal, or Azure CLI. Conditions inspect request and response headers or server variables, and actions rewrite headers or URL components. With WAF_v2, the rewrite decision can influence what the firewall evaluates after URL or host changes.

Why it matters

Rewrite rules matter because the edge often has to normalize traffic before legacy backends, App Service apps, APIs, or security tools can handle it correctly. A clean rewrite can preserve a public URL while sending a different path to the backend, add security headers consistently, remove sensitive technology details, or repair redirect responses that leak an internal host name. A bad rewrite can also create loops, break WAF inspection, hide client identity, or send users to the wrong route. Teams need to treat rewrite behavior as production routing logic, not cosmetic configuration. That review forces the rule to be owned, tested, and monitored like any other production routing change.

Where you see it

Signals, screens, and Azure surfaces where this term usually becomes operational.

Signal 01

In the Application Gateway rewrite rule set blade, you see rule sequence, conditions, URL actions, request-header actions, and response-header actions tied to edge behavior. during release review

Signal 02

In Azure CLI, rewrite rules appear under az network application-gateway rewrite-rule commands, with gateway name, rule set name, conditions, sequence, and header values. during scripted audits

Signal 03

In access logs and WAF logs, rewrite problems appear as unexpected paths, altered host headers, redirect loops, blocked requests, or sudden 4xx and 5xx spikes.

When this becomes relevant

Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.

  • Preserve a stable public URL while rewriting paths to a versioned backend during an API migration.
  • Add security response headers at Application Gateway when several backend teams cannot change code quickly.
  • Remove backend technology headers from responses before an external penetration test or compliance review.
  • Repair Location headers from App Service redirects so users stay on the gateway domain instead of backend hostnames.
  • Route path-based traffic using rewritten URLs while testing WAF behavior against the final backend request shape.

Real-world case studies

Different enterprise-style examples that show the term being used to hit measurable objectives.

Case study 01

Ticketing platform keeps public URLs stable during API migration

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A live-event ticketing platform moved checkout APIs from a monolith to a new service, but partner integrations still called old public paths. Changing every partner URL before concert season was not realistic.

Business/Technical Objectives
  • Keep existing partner URLs working through the migration window.
  • Send only checkout paths to the new backend service.
  • Avoid browser-visible redirects that would break signed partner callbacks.
  • Detect rollback need within fifteen minutes of cutover.
Solution Using Rewrite rule

The team created an Application Gateway rewrite rule set on the WAF_v2 gateway. A path-based routing rule matched /checkout/* traffic, and the rewrite rule transformed legacy paths into the new service path format while preserving query parameters used for signed callbacks. The rule sequence was documented, and conditions limited the action to partner API hostnames. Azure CLI exported the rewrite set, conditions, routing-rule attachment, and backend-health output before deployment. Synthetic tests checked old and new paths, redirect behavior, and WAF logs before traffic was increased.

Results & Business Impact
  • Partner callback failures stayed below 0.2 percent during the first migration weekend.
  • The team avoided twelve emergency partner reconfiguration windows.
  • Checkout latency improved 18 percent because users no longer hit an extra redirect hop.
  • Rollback was reduced to detaching the rewrite set from one routing rule.
Key Takeaway for Glossary Readers

A rewrite rule is valuable when edge translation lets a migration move forward without forcing every client to change at once.

Case study 02

Municipal portal adds security headers without touching every app

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A city government portal hosted citizen services across several vendor-backed applications. A security audit found missing HSTS and content-security headers, but the vendors had different release timelines.

Business/Technical Objectives
  • Add approved response headers for high-traffic citizen pages.
  • Avoid code changes in six independently managed backend applications.
  • Keep WAF inspection active for rewritten traffic.
  • Provide auditors with before-and-after evidence.
Solution Using Rewrite rule

The platform team placed a response-header rewrite rule set on the shared Application Gateway. The rule added HSTS, Content-Security-Policy, and X-Content-Type-Options only for public service hostnames. A separate condition excluded legacy payment callbacks that failed strict header tests. Engineers verified WAF behavior after the rewrite, then used Azure CLI to capture the gateway rule set, routing-rule association, and backend-health state. Access logs and security scans were compared over a two-week observation period before the audit package was finalized. The final rollout checklist included one intentionally failing legacy path so auditors could see the exclusion behaving as designed.

Results & Business Impact
  • Security-header compliance rose from 41 percent to 96 percent across audited public endpoints.
  • No vendor release was required during the remediation sprint.
  • False WAF blocks stayed under the existing baseline after post-rewrite testing.
  • Audit evidence preparation dropped from four days to one afternoon.
Key Takeaway for Glossary Readers

Rewrite rules can turn the application gateway into a controlled remediation point when backend code changes are slow or fragmented.

Case study 03

Cybersecurity SaaS repairs redirect leakage from backend hostnames

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A cybersecurity SaaS provider routed customer admin traffic through Application Gateway, but backend services returned redirects pointing to internal App Service hostnames. Customers saw confusing URLs and some security scanners flagged host leakage.

Business/Technical Objectives
  • Keep users on the branded gateway hostname during login and admin flows.
  • Stop exposing backend App Service names in redirect responses.
  • Maintain traceability for support teams troubleshooting failed redirects.
  • Reduce scanner findings before a renewal review.
Solution Using Rewrite rule

The edge team added a response Location-header rewrite rule. Conditions matched redirects whose Location header contained the backend hostname, and the action replaced that host with the public customer domain while preserving the scheme and path. Engineers avoided rewriting request Host headers because backend authentication already depended on known hostnames. CLI checks listed the rewrite rule, conditions, listener bindings, and gateway backend health. Synthetic login flows validated successful redirects for three customer tiers before the rule moved to production.

Results & Business Impact
  • Backend hostname exposure findings fell from 37 to 1 in the renewal scan.
  • Support tickets about odd login URLs dropped 68 percent in the first month.
  • No authentication failures were attributed to the rewrite after phased rollout.
  • The customer-success team kept a clear evidence trail for renewal security questions.
Key Takeaway for Glossary Readers

A precise rewrite rule can hide backend implementation details while preserving the public experience customers expect.

Why use Azure CLI for this?

After years operating Azure edge services, I use Azure CLI for rewrite rules because the portal view can hide the exact relationship between listeners, routing rules, path maps, rewrite sets, and conditions. CLI gives me repeatable inventory, ordered rule output, and a way to export the gateway shape before a change. It is especially helpful during incident review because I can prove which rewrite set is attached to which routing rule. CLI also supports scripted creation, condition inspection, and controlled cleanup, so production rules do not drift from the tested Bicep or change-ticket design. It also makes peer review easier because the exact rule payload can be compared between environments.

CLI use cases

  • List rewrite rule sets and prove which routing rules reference them before a gateway change.
  • Create or update a rewrite rule with explicit sequence, conditions, URL actions, and header actions from a release script.
  • Export rule-set, condition, routing-rule, and backend-health output for incident evidence after a redirect or WAF problem.

Before you run CLI

  • Confirm tenant, subscription, resource group, gateway name, v2 SKU, listener, routing rule, path map, WAF policy, and output format.
  • Check permissions for Microsoft.Network/applicationGateways write operations and understand that rule updates can affect live edge traffic.
  • Validate backend hostnames, private DNS, certificates, WAF mode, regex patterns, destructive delete risk, and any cost impact from extra logs.

What output tells you

  • Rewrite-rule output shows rule set name, rule name, sequence number, conditions, URL configuration, and request or response header actions.
  • Routing-rule output tells whether the rewrite set is actually attached to a listener or path-based rule handling production traffic.
  • Backend-health and log output indicate whether the rewritten request still reaches healthy pools and whether WAF or redirects changed behavior.

Mapped Azure CLI commands

Application Gateway rewrite rule CLI commands

direct-management
az network application-gateway rewrite-rule set list --gateway-name <gateway-name> --resource-group <resource-group>
az network application-gateway rewrite-rule setdiscoverNetworking
az network application-gateway rewrite-rule list --gateway-name <gateway-name> --resource-group <resource-group> --rule-set-name <rewrite-rule-set>
az network application-gateway rewrite-rulediscoverNetworking
az network application-gateway rewrite-rule show --gateway-name <gateway-name> --resource-group <resource-group> --rule-set-name <rewrite-rule-set> --name <rewrite-rule>
az network application-gateway rewrite-rulediscoverNetworking
az network application-gateway rewrite-rule condition list --gateway-name <gateway-name> --resource-group <resource-group> --rule-set-name <rewrite-rule-set> --rule-name <rewrite-rule>
az network application-gateway rewrite-rule conditiondiscoverNetworking
az network application-gateway rule list --gateway-name <gateway-name> --resource-group <resource-group>
az network application-gateway rulediscoverNetworking
az network application-gateway show-backend-health --name <gateway-name> --resource-group <resource-group>
az network application-gatewaydiscoverNetworking

Architecture context

Architecturally, rewrite rules are part of the L7 traffic contract between the internet, Application Gateway, WAF policy, and backend applications. I place them where the edge must translate public behavior into backend expectations without exposing implementation details. For example, one gateway can keep customer-facing paths stable while routing to versioned APIs, App Service hostnames, or migration backends. The design must be explicit about whether routing uses the original or rewritten URL, whether WAF sees the transformed request, and which team owns the rule set. A mature design names rewrite sets clearly, tests them with path-based rules, and documents safe rollback.

Security

Security impact is direct. Rewrite rules can add headers such as HSTS or Content-Security-Policy, remove response headers that reveal backend technology, and preserve the correct client address for downstream security devices. They can also create risk if a rule rewrites host names, query strings, or forwarding headers without review. With WAF_v2, URL or host rewrites affect the request seen by WAF, so security testing must include post-rewrite behavior. Restrict who can edit rewrite sets, audit changes through Activity Log, and test rules against header spoofing, open redirect, cache poisoning, and backend exposure scenarios. Include these checks in deployment gates, not only in annual penetration tests.

Cost

Rewrite rules do not create a separate billing meter, but they can influence cost indirectly through gateway SKU choice, WAF usage, troubleshooting time, and backend traffic patterns. The feature requires Application Gateway v2, so teams running older or smaller edge designs may need a SKU migration before using it. A rewrite that prevents needless redirects can reduce backend chatter and user retries. A faulty rule can do the opposite by generating loops, extra logs, WAF evaluations, and support effort. FinOps review should connect rewrite changes to gateway capacity, WAF logging volume, test environments, and incident labor. That visibility keeps a small edge rule from becoming a recurring hidden operations expense.

Reliability

Reliability depends on rewrite correctness. A rule that changes paths, query strings, or Location headers can fix a migration issue cleanly, but it can also cause redirect loops, broken health checks, unexpected 500 responses, or traffic going to a backend that never receives the expected URL. Application Gateway warns about several rewrite pitfalls, including reevaluating path maps in ways that create loops. Reliable operations require staging tests, ordered rules, explicit conditions, backend-health validation, and rollback to the previous rewrite set. Keep rewrite changes separate from unrelated listener and backend-pool changes whenever possible. Track the owning application team so responders know who can approve emergency removal.

Performance

Performance impact is usually indirect but real. Simple header or URL rewrites add little overhead compared with TLS termination, WAF inspection, and backend response time, but complex conditions and bad routing outcomes can hurt users. Rewrites can improve perceived performance by avoiding external redirects and keeping users on the same public URL. They can hurt performance if they trigger WAF processing differences, send traffic to a slower backend path, or create retry and redirect loops. Measure end-to-end latency, backend latency, HTTP status rates, WAF matches, and client redirect counts before calling a rewrite safe. Compare the same request path before and after the rewrite rather than averaging all gateway traffic.

Operations

Operators inspect rewrite rules by listing rule sets, rule sequence numbers, conditions, request-header actions, response-header actions, URL actions, and the routing rules that reference them. Before making changes, they export the gateway configuration and test expected paths with curl or synthetic transactions. After deployment, they check backend health, access logs, WAF logs, HTTP status trends, and redirect behavior. Runbooks should describe how to identify the active rewrite set, which headers are intentionally modified, which rule owns a path change, and how to disable or roll back a rule without deleting the gateway. Keep examples of expected before-and-after requests close to the runbook.

Common mistakes

  • Creating a rewrite set but forgetting to attach it to the routing rule that actually receives the affected traffic.
  • Using regex captures without testing edge cases, causing paths, query strings, or Location headers to be rewritten incorrectly.
  • Changing host or URL rewrite behavior without retesting WAF policy order, backend authentication, health probes, and redirects.