From 09e844ccabe658f25ffdf35efa196bc9d3ee5b0a Mon Sep 17 00:00:00 2001 From: Miha Zupan Date: Mon, 13 Jul 2026 14:51:12 +0200 Subject: [PATCH] Add a note about dashes and underscores in header names --- aspnetcore/fundamentals/servers/yarp/header-guidelines.md | 5 ++++- aspnetcore/fundamentals/servers/yarp/header-routing.md | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/aspnetcore/fundamentals/servers/yarp/header-guidelines.md b/aspnetcore/fundamentals/servers/yarp/header-guidelines.md index b473cf61b206..1d3fc941210f 100644 --- a/aspnetcore/fundamentals/servers/yarp/header-guidelines.md +++ b/aspnetcore/fundamentals/servers/yarp/header-guidelines.md @@ -4,7 +4,7 @@ title: YARP HTTP header guidelines description: Learn about YARP HTTP header guidelines. author: wadepickett ms.author: wpickett -ms.date: 04/03/2025 +ms.date: 07/13/2026 ms.topic: concept-article content_well_notification: AI-contribution ai-usage: ai-assisted @@ -13,6 +13,9 @@ ai-usage: ai-assisted Headers are a very important part of processing HTTP requests and each have their own semantics and considerations. Most headers are proxied by default, though some used to control how the request is delivered are automatically adjusted or removed by the proxy. The connections between the client and the proxy and between the proxy and the destination are independent. Therefore, headers that affect the connection and transport must be filtered. Many headers contain information like domain names, paths, or other details that may be affected when a reverse proxy is included in the application architecture. The following is a collection of guidelines about how specific headers might be impacted and what to do about them. +> [!NOTE] +> YARP doesn't normalize dashes (`-`) and underscores (`_`) in header names. They're treated as different characters, so a name such as `my-header` doesn't match a request header named `my_header`. + ## YARP header filtering YARP automatically removes request and response headers that could impact its ability to forward a request correctly, or that may be used maliciously to bypass features of the proxy. A complete list can be found [here](https://github.com/microsoft/reverse-proxy/blob/main/src/ReverseProxy/Forwarder/RequestUtilities.cs#L71), with some highlights described below. diff --git a/aspnetcore/fundamentals/servers/yarp/header-routing.md b/aspnetcore/fundamentals/servers/yarp/header-routing.md index b93610596f60..091a9e8e9fa3 100644 --- a/aspnetcore/fundamentals/servers/yarp/header-routing.md +++ b/aspnetcore/fundamentals/servers/yarp/header-routing.md @@ -4,7 +4,7 @@ title: YARP Header Based Routing description: YARP Header Based Routing author: wadepickett ms.author: wpickett -ms.date: 2/6/2025 +ms.date: 07/13/2026 ms.topic: concept-article content_well_notification: AI-contribution ai-usage: ai-assisted @@ -283,6 +283,9 @@ var routes = new[] The header name to check for on the request. A non-empty value is required. This field is case-insensitive per the HTTP RFCs. +> [!NOTE] +> YARP doesn't normalize dashes (`-`) and underscores (`_`) in header names. They're treated as different characters, so a name such as `my-header` doesn't match a request header named `my_header`. + ### Values A list of possible values to search for. The header must match at least one of these values according to the specified `Mode` except for the 'NotContains'. At least one value is required unless `Mode` is set to `Exists` or `NotExists`.