diff --git a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc index ff2e0bee73..4be5c9b431 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc @@ -372,7 +372,7 @@ include::partial$web/forwarded-headers.adoc[] -[[webflux-forwarded-headers-forwardedheadertransformer]] +[[webflux-forwarded-headers-transformer]] === ForwardedHeaderTransformer `ForwardedHeaderTransformer` is a component that modifies the host, port, and scheme of @@ -390,7 +390,7 @@ filters, and `ForwardedHeaderTransformer` is used instead. [[webflux-forwarded-headers-security]] === Security Considerations -There are security considerations for forwarded headers, since an application cannot know +There are security considerations for forwarded headers since an application cannot know if the headers were added by a proxy, as intended, or by a malicious client. This is why a proxy at the boundary of trust should be configured to remove untrusted forwarded traffic coming from the outside. You can also configure the `ForwardedHeaderTransformer` with diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc index 1ef0171acc..27629d92a7 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc @@ -57,7 +57,7 @@ with `removeOnly=true`, in which case it removes but does not use the headers. [[filters-forwarded-headers-dispatcher]] -=== About Dispatcher Types +=== Dispatcher Types In order to support xref:web/webmvc/mvc-ann-async.adoc[asynchronous requests] and error dispatches this filter should be mapped with `DispatcherType.ASYNC` and also `DispatcherType.ERROR`. diff --git a/framework-docs/modules/ROOT/partials/web/forwarded-headers.adoc b/framework-docs/modules/ROOT/partials/web/forwarded-headers.adoc index bdd12add26..99ccfe3c48 100644 --- a/framework-docs/modules/ROOT/partials/web/forwarded-headers.adoc +++ b/framework-docs/modules/ROOT/partials/web/forwarded-headers.adoc @@ -1,4 +1,4 @@ -As a request goes through proxies (such as load balancers) the host, port, and +As a request goes through proxies such as load balancers the host, port, and scheme may change, and that makes it a challenge to create links that point to the correct host, port, and scheme from a client perspective. @@ -14,7 +14,6 @@ There are other non-standard headers, too, including `X-Forwarded-Host`, `X-Forw `X-Forwarded-Proto`, `X-Forwarded-Ssl`, and `X-Forwarded-Prefix`. - [[x-forwarded-host]] ==== X-Forwarded-Host @@ -25,7 +24,6 @@ a proxy which forwards the request to `http://localhost:8080/resource`, then a h `X-Forwarded-Host: example.com` can be sent to inform the server that the original host was `example.com`. - [[x-forwarded-port]] ==== X-Forwarded-Port @@ -36,7 +34,6 @@ communicate the original port to a downstream server. For example, if a request to inform the server that the original port was `443`. - [[x-forwarded-proto]] ==== X-Forwarded-Proto @@ -47,7 +44,6 @@ a proxy which forwards the request to `http://localhost:8080/resource`, then a h `X-Forwarded-Proto: https` can be sent to inform the server that the original protocol was `https`. - [[x-forwarded-ssl]] ==== X-Forwarded-Ssl @@ -58,7 +54,6 @@ original protocol (e.g. https / https) to a downstream server. For example, if a original protocol was `https`. - [[x-forwarded-prefix]] ==== X-Forwarded-Prefix @@ -66,25 +61,25 @@ While not standard, https://microsoft.github.io/reverse-proxy/articles/transform is a de-facto standard header that is used to communicate the original URL path prefix to a downstream server. -The definition of the path prefix is most easily defined by an example. For example, consider -the following proxy to server mapping of: +Use of `X-Forwarded-Prefix` can vary by deployment scenario, and needs to be flexible to +allow replacing, removing, or prepending the path prefix of the target server. + +_Scenario 1: Override path prefix_ [subs="-attributes"] ---- https://example.com/api/{path} -> http://localhost:8080/app1/{path} ---- -The prefix is defined as the porition of the URL path before the capture group of `+{path}+`. -For the proxy, the prefix is `/api` and for the server the prefix is `/app1`. In this case, -the header of `X-Forwarded-Prefix: /api` can be sent to indicate the original prefix of `/api` -which overrides the server's prefix of `/app1`. +The prefix is the start of the path before the capture group `+{path}+`. For the proxy, +the prefix is `/api` while for the server the prefix is `/app1`. In this case, the proxy +can send `X-Forwarded-Prefix: /api` to have the original prefix `/api` override the +server prefix `/app1`. -The `X-Forwarded-Prefix` is flexible because it overrides the existing prefix. This means that -the server prefix can be replaced (as demonstrated above), removed, or modified. +_Scenario 2: Remove path prefix_ -The previous example demonstrated how to replace the prefix, but at times users may want to -instruct the server to remove the prefix. For example, consider the proxy to server -mapping of: +At times, an application may want to have the prefix removed. For example, consider the +following proxy to server mapping: [subs="-attributes"] ---- @@ -92,44 +87,36 @@ https://app1.example.com/{path} -> http://localhost:8080/app1/{path} https://app2.example.com/{path} -> http://localhost:8080/app2/{path} ---- -In the `app1` example above, the proxy has an empty prefix and the server has a prefix of -`/app1`. The header of ``X-Forwarded-Prefix: `` can be sent to indicate the original empty -prefix which overrides the server's prefix of `/app1`. In the `app2` example above, the proxy -has an empty prefix and the server has a prefix of `/app2`. The header of ``X-Forwarded-Prefix: `` -can be sent to indicate the original empty prefix which overrides the server's prefix of `/app2`. +The proxy has no prefix, while applications `app1` and `app2` have path prefixes +`/app1` and `/app2` respectively. The proxy can send ``X-Forwarded-Prefix: `` to +have the empty prefix override server prefixes `/app1` and `/app2`. [NOTE] ==== -A common usecase is that an organization pays licenses per production application server. -This means that they prefer to deploy multiple applications to each application server to -avoid paying the licensing fees. +A common case for this deployment scenario is where licenses are paid per +production application server, and it is preferable to deploy multiple applications per +server to reduce fees. Another case is I/O bound applications, and the need to deploy +multiple applications to each application server to consume less resources. -Another common usecase is that organizations may be using more resource intensive -application servers. This means that they prefer to deploy multiple applications to each -application server to avoid consuming additional resources. +In this scenario, applications need a non-empty context root because there are multiple +applications on the same server. However, this should not be visible in URL paths of +the public API where applications may use different subdomains that provides benefits +such as: -In both of these usecases, applications must define a non-empty context root because there is -more than one application associated to the same application server. - -While their application is deployed with a non-empty context root, they do not want this -expressed in the path of their URLs because they use a different subdomain for each application. -Using different subdomains for each application provides benefits such as: - -* Added security (e.g. same origin policy) -* Allows for scaling the applications differently (a different domain can point to different -IP addresses) - -The example above illustrates how to implement such a scenario. +* Added security, e.g. same origin policy +* Independent scaling of applications (different domain points to different IP address) ==== -In some cases, a proxy may want to insert a prefix in front of the existing prefix. For -example, consider the proxy to server mapping of: +_Scenario 3: Insert path prefix_ + +In other cases, it may be necessary to prepend a prefix. For example, consider the +following proxy to server mapping: [subs="-attributes"] ---- https://example.com/api/app1/{path} -> http://localhost:8080/app1/{path} ---- -In the example above, the proxy has a prefix of `/api/app1` and the server has a prefix of -`/app1`. The header of `X-Forwarded-Prefix: /api/app1` can be sent to indicate the original -prefix of `/api/app1` which overrides the server's prefix of `/app1`. \ No newline at end of file +In this case, the proxy has a prefix of `/api/app1` and the server has a prefix of +`/app1`. The proxy can send `X-Forwarded-Prefix: /api/app1` to have the original prefix +`/api/app1` override the server prefix `/app1`. \ No newline at end of file