|
1 | 1 | --- |
2 | 2 | uid: fundamentals/servers/yarp/header-guidelines |
3 | | -title: YARP HTTP Headers |
4 | | -description: YARP HTTP Headers |
| 3 | +title: YARP HTTP header guidelines |
| 4 | +description: Learn about YARP HTTP header guidelines. |
5 | 5 | author: samsp-msft |
6 | 6 | ms.author: samsp |
7 | 7 | ms.date: 2/6/2025 |
8 | 8 | ms.topic: article |
9 | 9 | content_well_notification: AI-contribution |
10 | 10 | ai-usage: ai-assisted |
11 | 11 | --- |
| 12 | +# YARP HTTP header guidelines |
12 | 13 |
|
13 | | -# YARP HTTP Headers |
14 | | - |
15 | | -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 the proxy and destination are independent, and so headers that affect the connection and transport need to 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. Below is a collection of guidelines about how specific headers might be impacted and what to do about them. |
| 14 | +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. |
16 | 15 |
|
17 | 16 | ## YARP header filtering |
18 | 17 |
|
19 | 18 | 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. |
20 | 19 |
|
21 | | -### Connection, KeepAlive, Close |
| 20 | +### `Connection`, `KeepAlive`, `Close` |
22 | 21 |
|
23 | | -These headers control how the TCP connection is managed and are removed to avoid impacting the connection on the other side of the proxy. |
| 22 | +These headers control how the TCP connection is managed and are removed to prevent impacting the connection on the other side of the proxy. |
24 | 23 |
|
25 | | -### Transfer-Encoding |
| 24 | +### `Transfer-Encoding` |
26 | 25 |
|
27 | 26 | This header describes the format of the request or response body on the wire, e.g. 'chunked', and is removed because the format can vary between the internal and external connection. The incoming and outgoing HTTP stacks will add transport headers as needed. |
28 | 27 |
|
29 | | -### TE |
| 28 | +### `TE` |
30 | 29 |
|
31 | 30 | Only the `TE: trailers` header value is allowed through the proxy since it's required for some gRPC implementations. |
32 | 31 |
|
33 | | -### Upgrade |
| 32 | +### `Upgrade` |
34 | 33 |
|
35 | 34 | This is used for protocols like WebSockets. It is removed by default and only added back for specifically supported protocols (WebSockets, SPDY). |
36 | 35 |
|
37 | | -### Proxy-* |
| 36 | +### `Proxy-*` |
38 | 37 |
|
39 | 38 | These are headers used with proxies and are not considered appropriate to forward. |
40 | 39 |
|
41 | | -### Alt-Svc |
| 40 | +### `Alt-Svc` |
42 | 41 |
|
43 | 42 | This response header is used with HTTP/3 upgrades and only applies to the immediate connection. |
44 | 43 |
|
45 | 44 | ### Distributed tracing headers |
46 | 45 |
|
47 | | -These headers include TraceParent, Request-Id, TraceState, Baggage, Correlation-Context. |
48 | | -They are automatically removed based on `DistributedContextPropagator.Fields` so that the forwarding HttpClient can replace them with updated values. |
49 | | -You can opt out of modifying these headers by setting `SocketsHttpHandler.ActivityHeadersPropagator` to `null`: |
50 | | -```C# |
| 46 | +These headers include `TraceParent`, `Request-Id`, `TraceState`, `Baggage`, and `Correlation-Context`. |
| 47 | + |
| 48 | +They're automatically removed based on <xref:System.Diagnostics.DistributedContextPropagator.Fields%2A?displayProperty=nameWithType>, allowing the forwarding <xref:System.Net.Http.HttpClient> to replace them with updated values. |
| 49 | + |
| 50 | +You can opt out of modifying these headers by setting <xref:System.Net.Http.SocketsHttpHandler.ActivityHeadersPropagator%2A?displayProperty=nameWithType> to `null`: |
| 51 | + |
| 52 | +```csharp |
51 | 53 | services.AddReverseProxy() |
52 | 54 | .ConfigureHttpClient((_, handler) => handler.ActivityHeadersPropagator = null); |
53 | 55 | ``` |
54 | 56 |
|
55 | | -### Strict-Transport-Security |
| 57 | +### `Strict-Transport-Security` |
56 | 58 |
|
57 | 59 | This header instructs clients to always use HTTPS, but there may be a conflict between values provided by the proxy and destination. To avoid confusion, the destination's value is not copied to the response if one was already added to the response by the proxy application. |
58 | 60 |
|
59 | | -## Other Header Guidelines |
| 61 | +## Other header guidelines |
60 | 62 |
|
61 | | -### Host |
| 63 | +### `Host` |
62 | 64 |
|
63 | | -The Host header indicates which site on the server the request is intended for. This header is removed by default since the host name used publicly by the proxy is likely to differ from the one used by the service behind the proxy. This is configurable using the [RequestHeaderOriginalHost](xref:fundamentals/servers/yarp/transforms#requestheaderoriginalhost) transform. |
| 65 | +The Host header indicates which site on the server the request is intended for. This header is removed by default since the host name used publicly by the proxy is likely to differ from the one used by the service behind the proxy. This can be configured using the [`RequestHeaderOriginalHost`](xref:fundamentals/servers/yarp/transforms#requestheaderoriginalhost) transform. |
64 | 66 |
|
65 | | -### X-Forwarded-*, Forwarded |
| 67 | +### `X-Forwarded-*`, `Forwarded` |
66 | 68 |
|
67 | | -Because a separate connection is used to communicate with the destination, these request headers can be used to forward information about the original connection like the IP, scheme, port, client certificate, etc.. X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Prefix are enabled by default. This information is subject to spoofing attacks so any existing headers on the request are removed and replaced by default. The destination app should be careful about how much trust it places in these values. See [transforms](xref:fundamentals/servers/yarp/transforms#defaults) for configuring these in the proxy. See the [ASP.NET docs](/aspnet/core/host-and-deploy/proxy-load-balancer) for configuring the destination app to read these headers. |
| 69 | +Because a separate connection is used to communicate with the destination, these request headers can be used to forward information about the original connection, such as the IP, scheme, port, and client certificate. `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Forwarded-Prefix` are enabled by default. This information is subject to spoofing attacks so any existing headers on the request are removed and replaced by default. The destination app should be careful about how much trust it places in these values. See [transforms](xref:fundamentals/servers/yarp/transforms#defaults) for configuring these in the proxy. For guidance on configuring the destination app to read these headers, see <xref:host-and-deploy/proxy-load-balancer>. |
68 | 70 |
|
69 | | -### X-http-method-override, x-http-method, x-method-override |
| 71 | +### `X-http-method-override`, `x-http-method`, `x-method-override` |
70 | 72 |
|
71 | | -Some clients and servers limit which HTTP methods they allow (GET, POST, etc.). These request headers are sometimes used to work around those restrictions. These headers are proxied by default. If in the proxy you want to prevent these bypasses then use the [RequestHeaderRemove](xref:fundamentals/servers/yarp/transforms#requestheaderremove) transform. |
| 73 | +Some clients and servers limit which HTTP methods they allow (for example, GET). These request headers are sometimes used to work around those restrictions. These headers are proxied by default. If in the proxy you want to prevent these bypasses then use the [RequestHeaderRemove](xref:fundamentals/servers/yarp/transforms#requestheaderremove) transform. |
72 | 74 |
|
73 | | -### Set-Cookie |
| 75 | +### `Set-Cookie` |
74 | 76 |
|
75 | | -This response header may contain fields constraining the path, domain, scheme, etc. where the cookie should be used. Using a reverse proxy may change the effective domain, path, or scheme of a site from the public view. While it would be possible to [rewrite](https://github.com/microsoft/reverse-proxy/issues/1109) response cookies using custom transforms, it's recommended instead to use the Forwarded headers described above to flow the correct values to the destination app so it can generate the correct set-cookie headers. |
| 77 | +This response header may contain fields that constrain aspects of the URL, such as the scheme, domain, or path, where the cookie should be used. Using a reverse proxy may change the effective scheme, domain, or path of a site from the public view. While it would be possible to [rewrite response cookies using custom transforms](https://github.com/microsoft/reverse-proxy/issues/1109), we recommended instead to use the `Forwarded` headers described earlier to flow the correct values to the destination app so it can generate the correct `set-cookie` headers. |
76 | 78 |
|
77 | | -### Location |
| 79 | +### `Location` |
78 | 80 |
|
79 | 81 | This response header is used with redirects and may contain a scheme, domain, and path that differ from the public values due to the use of the proxy. While it would be possible to [rewrite](https://github.com/microsoft/reverse-proxy/discussions/466) the Location header using custom transforms, it's recommended instead to use the Forwarded headers described above to flow the correct values to the destination app so it can generate the correct Location headers. |
80 | 82 |
|
81 | | -### Server |
| 83 | +### `Server` |
82 | 84 |
|
83 | | -This response header indicates what server technology was used to generate the response (IIS, Kestrel, etc.). This header is proxied from the destination by default. Applications that want to remove it can use the [ResponseHeaderRemove](xref:fundamentals/servers/yarp/transforms#responseheaderremove) transform, in which case the proxy's default server header will be used. Suppressing the proxy default server header is server specific, such as for [Kestrel](/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserveroptions.addserverheader#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerOptions_AddServerHeader). |
| 85 | +This response header indicates what server technology was used to generate the response (for example, IIS, Kestrel). This header is proxied from the destination by default. Applications that want to remove it can use the [ResponseHeaderRemove](xref:fundamentals/servers/yarp/transforms#responseheaderremove) transform, in which case the proxy's default server header will be used. Suppressing the proxy default server header is server specific, such as for [Kestrel](/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserveroptions.addserverheader#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerOptions_AddServerHeader). |
84 | 86 |
|
85 | | -### X-Powered-By |
| 87 | +### `X-Powered-By` |
86 | 88 |
|
87 | | -This response header indicates what web framework was used to generate the response (ASP.NET, etc.). ASP.NET Core does not generate this header but IIS can. This header is proxied from the destination by default. Applications that want to remove it can use the [ResponseHeaderRemove](xref:fundamentals/servers/yarp/transforms#responseheaderremove) transform. |
| 89 | +This response header indicates what web framework was used to generate the response (for example, ASP.NET). ASP.NET Core does not generate this header but IIS can. This header is proxied from the destination by default. Applications that want to remove it can use the [ResponseHeaderRemove](xref:fundamentals/servers/yarp/transforms#responseheaderremove) transform. |
0 commit comments