Skip to content

Add a note about dashes and underscores in header names #37337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
guardrex merged 1 commit into from
Jul 13, 2026
+8 −2
Merged

Add a note about dashes and underscores in header names #37337

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion aspnetcore/fundamentals/servers/yarp/header-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down
5 changes: 4 additions & 1 deletion aspnetcore/fundamentals/servers/yarp/header-routing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`.
Expand Down
Loading