Update documentation on forwarded headers

See gh-37072

framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc

@@ -338,21 +338,26 @@ include::partial$web/forwarded-headers.adoc[]
 [[webflux-forwarded-headers-transformer]]
 === ForwardedHeaderTransformer
 
-`ForwardedHeaderTransformer` is a component that modifies the host, port, and scheme of
+`ForwardedHeaderTransformer` is a component that modifies the request to match information
-the request, based on forwarded headers, and then removes those headers. If you declare
+from the standard `"Forwarded"` or `"X-Forwarded"` headers, and also removes those headers
-it as a bean with the name `forwardedHeaderTransformer`, it will be
+to eliminate further impact. If you declare it as a bean with the name
+`forwardedHeaderTransformer`, it will be
 xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api-special-beans[detected] and used.
 
-
 [[webflux-forwarded-headers-security]]
 === Security Considerations
 
-There are security considerations for forwarded headers since an application cannot know
+Forwarded headers are intended to be set by trusted proxies and never allowed in from the
-if the headers were added by a proxy, as intended, or by a malicious client. This is why
+outside. A proxy at the edge of trust must remove forwarded headers including both the
-a proxy at the boundary of trust should be configured to remove untrusted forwarded traffic coming
+standard `"Forwarded"` and `"X-Forwarded"` headers, regardless of which one they use,
-from the outside. You can also configure the `ForwardedHeaderTransformer` with
+to protect applications which may check both.
-`removeOnly=true`, in which case it removes but does not use the headers.
 
+When creating `ForwardedHeaderTransformer` you need to specify whether it should use the
+standard `"Forwarded"` or `"X-Forwarded"` headers. If needed `"X-Forwarded-Prefix"`
+must be enabled separately through a property on the transformer.
+
+`ForwardedHeaderTransformer`  can be configured in `removeOnly` mode, in which case it removes
+forwarded headers from the request without using them.
 
 [[webflux-filters]]
 == Filters

framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc

@@ -24,7 +24,7 @@ ignoring further handling via `FORWARD` dispatches. The filter also provides con
 over whether the `Filter` gets involved in `ASYNC` and `ERROR` dispatches.
 
 Servlet filters can be configured in `web.xml` or via Servlet annotations.
-In a Spring Boot application , you can
+In a Spring Boot application, you can
 {spring-boot-docs}/how-to/webserver.html#howto.webserver.add-servlet-filter-listener.spring-bean[declare Filter's as beans]
 and Boot will have them configured.
 
@@ -51,20 +51,29 @@ include::partial$web/forwarded-headers.adoc[]
 [[filters-forwarded-headers-non-forwardedheaderfilter]]
 === ForwardedHeaderFilter
 
-`ForwardedHeaderFilter` is a Servlet filter that modifies the request in order to
+`ForwardedHeaderFilter` is a Servlet filter that modifies the request to match information
-a) change the host, port, and scheme based on `Forwarded` headers, and b) to remove those
+from the standard `"Forwarded"` or `"X-Forwarded"` headers, and also removes those headers
-headers to eliminate further impact. The filter relies on wrapping the request, and
+to eliminate further impact. The filter wraps the request and must be ordered ahead
-therefore it must be ordered ahead of other filters, such as `RequestContextFilter`, that
+of other filters such as `RequestContextFilter` in order for all downstream
-should work with the modified and not the original request.
+handlers to see the modified request.
+
 
 [[filters-forwarded-headers-security]]
 === Security Considerations
 
-There are security considerations for forwarded headers since an application cannot know
+Forwarded headers are intended to be set by trusted proxies and never allowed in from the
-if the headers were added by a proxy, as intended, or by a malicious client. This is why
+outside. A proxy at the edge of trust must remove forwarded headers including both the
-a proxy at the boundary of trust should be configured to remove untrusted `Forwarded`
+standard `"Forwarded"` and `"X-Forwarded"` headers, regardless of which one they use,
-headers that come from the outside. You can also configure the `ForwardedHeaderFilter`
+to protect applications which may check both.
-with `removeOnly=true`, in which case it removes but does not use the headers.
+
+When creating `ForwardedHeaderFilter` you need to specify whether it should use the
+standard `"Forwarded"` or `"X-Forwarded"` headers. If needed `"X-Forwarded-Prefix"`
+must be enabled separately through a property on the filter.
+
+`ForwardedHeaderFilter` can be configured in `removeOnly` mode, in which case it removes
+forwarded headers from the request without using them.
+
+
 
 [[filters-forwarded-headers-dispatcher]]
 === Dispatcher Types

framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc

@@ -112,8 +112,8 @@ Kotlin::
 
 NOTE: As of 5.1, `ServletUriComponentsBuilder` ignores information from the `Forwarded` and
 `X-Forwarded-*` headers, which specify the client-originated address. Consider using the
-xref:web/webmvc/filters.adoc#filters-forwarded-headers[`ForwardedHeaderFilter`] to extract and use or to discard
+xref:web/webmvc/filters.adoc#filters-forwarded-headers[`ForwardedHeaderFilter`]
-such headers.
+to extract and use or to discard such headers.
 
 
 [[mvc-links-to-controllers]]
@@ -261,8 +261,8 @@ Kotlin::
 
 NOTE: As of 5.1, `MvcUriComponentsBuilder` ignores information from the `Forwarded` and
 `X-Forwarded-*` headers, which specify the client-originated address. Consider using the
-xref:web/webmvc/filters.adoc#filters-forwarded-headers[ForwardedHeaderFilter] to extract and use or to discard
+xref:web/webmvc/filters.adoc#filters-forwarded-headers[ForwardedHeaderFilter] to extract
-such headers.
+and use or to discard such headers.
 
 
 [[mvc-links-to-controllers-from-views]]

framework-docs/modules/ROOT/partials/web/forwarded-headers.adoc

@@ -1,15 +1,30 @@
-As a request goes through proxies such as load balancers the host, port, and
+As a request goes through a chain of proxies, request details such as the scheme, host,
-scheme may change, and that makes it a challenge to create links that point to the correct
+port, remote address, and local address change. Proxies can insert headers that keep track of
-host, port, and scheme from a client perspective.
+the hops, and that can help to restore the request from the original client's perspective.
+This allows an application to create self-reference links for external clients.
+
+There are two alternatives for headers that proxies can use:
+
+- {rfc-site}/rfc7239[RFC 7239] defines the `"Forwarded"` HTTP header, a single header with
+individual attributes for each component in the chain of proxied requests with the
+following syntax.
+- `"X-Forwarded-"` prefixed headers are the original approach that predates the standard
+and uses a separate header for each request component.
+
+The Spring Framework supports both approaches. Most proxies today support the original
+`"X-Forwarded"` headers only as a de facto standard.
+
+WARNING: For maximum security, a proxy at the edge of trust must be configured to reset both
+the standard `"Forwarded"` and `"X-Forwarded-"` headers regardless of which ones are chosen
+for use. Likewise, when configuring forwarded header handling in Spring, you need to indicate
+which type of headers to use. More on security considerations later in this section.
+
 
-{rfc-site}/rfc7239[RFC 7239] defines the `Forwarded` HTTP header
-that proxies can use to provide information about the original request.
 
 [[forwarded-headers-non-standard]]
-=== Non-standard Headers
+=== X-Forwarded Headers
 
-There are other non-standard headers, too, including `X-Forwarded-Host`, `X-Forwarded-Port`,
+This section describes supported `"X-Forwarded"` headers.
-`X-Forwarded-Proto`, `X-Forwarded-Ssl`, `X-Forwarded-Prefix`, and `X-Forwarded-For`.
 
 [[x-forwarded-host]]
 ==== X-Forwarded-Host