NetworkingApplication delivery and API edgetemplate-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.
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.
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.
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.