root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Improve docs on forwarded headers 

Issue: SPR-16660
This commit is contained in:
Rossen Stoyanchev 2018-03-29 16:11:01 -04:00
parent a546cf0a3b
commit dd96c873e3
11 changed files with 115 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
spring-web/src/main/java/org/springframework/web/bind/annotation/CrossOrigin.java
View File

@ -1,5 +1,5 @@
/*
* Copyright 2002-2017 the original author or authors.
* Copyright 2002-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@ -81,6 +81,13 @@ public @interface CrossOrigin {
* <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
* response header of preflight actual CORS requests.
* <p>By default all origins are allowed.
* <p><strong>Note:</strong> CORS checks use values from "Forwarded"
* (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
* if present, in order to reflect the client-originated address.
* Consider using the {@code ForwardedHeaderFilter} in order to choose from a
* central place whether to extract and use, or to discard such headers.
* See the Spring Framework reference for more on this filter.
* @see #value
*/
@AliasFor("value")

9
spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java
View File

@ -1,5 +1,5 @@
/*
* Copyright 2002-2017 the original author or authors.
* Copyright 2002-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@ -145,6 +145,13 @@ public class CorsConfiguration {
* <p>The special value {@code "*"} allows all methods.
* <p>If not set, only {@code "GET"} and {@code "HEAD"} are allowed.
* <p>By default this is not set.
* <p><strong>Note:</strong> CORS checks use values from "Forwarded"
* (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
* if present, in order to reflect the client-originated address.
* Consider using the {@code ForwardedHeaderFilter} in order to choose from a
* central place whether to extract and use, or to discard such headers.
* See the Spring Framework reference for more on this filter.
*/
public void setAllowedMethods(@Nullable List<String> allowedMethods) {
this.allowedMethods = (allowedMethods != null ? new ArrayList<>(allowedMethods) : null);

7
spring-web/src/main/java/org/springframework/web/cors/reactive/CorsUtils.java
View File

@ -54,6 +54,13 @@ public abstract class CorsUtils {
* @code X-Forwarded-Port} headers.
* @return {@code true} if the request is a same-origin one, {@code false} in case
* of a cross-origin request
* <p><strong>Note:</strong> this method uses values from "Forwarded"
* (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
* if present, in order to reflect the client-originated address.
* Consider using the {@code ForwardedHeaderFilter} in order to choose from a
* central place whether to extract and use, or to discard such headers.
* See the Spring Framework reference for more on this filter.
*/
public static boolean isSameOrigin(ServerHttpRequest request) {
String origin = request.getHeaders().getOrigin();

14
spring-web/src/main/java/org/springframework/web/util/WebUtils.java
View File

@ -677,6 +677,13 @@ public abstract class WebUtils {
* Check the given request origin against a list of allowed origins.
* A list containing "*" means that all origins are allowed.
* An empty list means only same origin is allowed.
* <p><strong>Note:</strong> this method may use values from "Forwarded"
* (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
* if present, in order to reflect the client-originated address.
* Consider using the {@code ForwardedHeaderFilter} in order to choose from a
* central place whether to extract and use, or to discard such headers.
* See the Spring Framework reference for more on this filter.
* @return {@code true} if the request origin is valid, {@code false} otherwise
* @since 4.1.5
* @see <a href="https://tools.ietf.org/html/rfc6454">RFC 6454: The Web Origin Concept</a>
@ -701,6 +708,13 @@ public abstract class WebUtils {
* Check if the request is a same-origin one, based on {@code Origin}, {@code Host},
* {@code Forwarded}, {@code X-Forwarded-Proto}, {@code X-Forwarded-Host} and
* @code X-Forwarded-Port} headers.
* <p><strong>Note:</strong> this method uses values from "Forwarded"
* (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
* if present, in order to reflect the client-originated address.
* Consider using the {@code ForwardedHeaderFilter} in order to choose from a
* central place whether to extract and use, or to discard such headers.
* See the Spring Framework reference for more on this filter.
* @return {@code true} if the request is a same-origin one, {@code false} in case
* of cross-origin request
* @since 4.2

9
spring-webflux/src/main/java/org/springframework/web/reactive/config/CorsRegistration.java
View File

@ -1,5 +1,5 @@
/*
* Copyright 2002-2017 the original author or authors.
* Copyright 2002-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@ -49,6 +49,13 @@ public class CorsRegistration {
* <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
* response header of preflight actual CORS requests.
* <p>By default all origins are allowed.
* <p><strong>Note:</strong> CORS checks use values from "Forwarded"
* (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
* if present, in order to reflect the client-originated address.
* Consider using the {@code ForwardedHeaderFilter} in order to choose from a
* central place whether to extract and use, or to discard such headers.
* See the Spring Framework reference for more on this filter.
*/
public CorsRegistration allowedOrigins(String... origins) {
this.config.setAllowedOrigins(new ArrayList<>(Arrays.asList(origins)));

9
spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistration.java
View File

@ -1,5 +1,5 @@
/*
* Copyright 2002-2017 the original author or authors.
* Copyright 2002-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@ -51,6 +51,13 @@ public class CorsRegistration {
* <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
* response header of preflight actual CORS requests.
* <p>By default, all origins are allowed.
* <p><strong>Note:</strong> CORS checks use values from "Forwarded"
* (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
* if present, in order to reflect the client-originated address.
* Consider using the {@code ForwardedHeaderFilter} in order to choose from a
* central place whether to extract and use, or to discard such headers.
* See the Spring Framework reference for more on this filter.
*/
public CorsRegistration allowedOrigins(String... origins) {
this.config.setAllowedOrigins(Arrays.asList(origins));

17
spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/MvcUriComponentsBuilder.java
View File

@ -1,5 +1,5 @@
/*
* Copyright 2002-2017 the original author or authors.
* Copyright 2002-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@ -83,14 +83,13 @@ import org.springframework.web.util.UriComponentsBuilder;
* {@link #relativeTo(org.springframework.web.util.UriComponentsBuilder)}.
* </ul>
*
* <p><strong>Note:</strong> This class extracts and uses values from the headers
* "Forwarded" (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* or "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" if
* "Forwarded" is not found, in order to reflect the client-originated protocol
* and address. As an alternative consider using the
* {@link org.springframework.web.filter.ForwardedHeaderFilter} to have such
* headers extracted once and removed, or removed only (without being used).
* See the reference for further information including security considerations.
* <p><strong>Note:</strong> This class uses values from "Forwarded"
* (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
* if present, in order to reflect the client-originated protocol and address.
* Consider using the {@code ForwardedHeaderFilter} in order to choose from a
* central place whether to extract and use, or to discard such headers.
* See the Spring Framework reference for more on this filter.
*
* @author Oliver Gierke
* @author Rossen Stoyanchev

15
spring-webmvc/src/main/java/org/springframework/web/servlet/support/ServletUriComponentsBuilder.java
View File

@ -36,14 +36,13 @@ import org.springframework.web.util.UrlPathHelper;
* UriComponentsBuilder with additional static factory methods to create links
* based on the current HttpServletRequest.
*
* <p><strong>Note:</strong> This class extracts and uses values from the headers
* "Forwarded" (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* or "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" if
* "Forwarded" is not found, in order to reflect the client-originated protocol
* and address. As an alternative consider using the
* {@link org.springframework.web.filter.ForwardedHeaderFilter} to have such
* headers extracted once and removed, or removed only (without being used).
* See the reference for further information including security considerations.
* <p><strong>Note:</strong> This class uses values from "Forwarded"
* (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
* "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
* if present, in order to reflect the client-originated protocol and address.
* Consider using the {@code ForwardedHeaderFilter} in order to choose from a
* central place whether to extract and use, or to discard such headers.
* See the Spring Framework reference for more on this filter.
*
* @author Rossen Stoyanchev
* @since 3.1

6
spring-webmvc/src/main/resources/org/springframework/web/servlet/config/spring-mvc.xsd
View File

@ -1331,6 +1331,12 @@
<xsd:documentation><![CDATA[
Comma-separated list of origins to allow, e.g. "http://domain1.com, http://domain2.com".
The special value "*" allows all domains (default).
Note that CORS checks use values from "Forwarded" (RFC 7239), "X-Forwarded-Host",
"X-Forwarded-Port", and "X-Forwarded-Proto" headers, if present, in order to reflect
the client-originated address. Consider using the ForwardedHeaderFilter in order to
choose from a central place whether to extract and use such headers, or whether to
discard them. See the Spring Framework reference for more on this filter.
]]></xsd:documentation>
</xsd:annotation>
</xsd:attribute>

38
src/docs/asciidoc/web/webflux.adoc
View File

@ -854,6 +854,44 @@ views through the <<webflux-config-view-resolvers,WebFlux Config>>. Default view
always selected and used if they match the requested media type.
[[webflux-filters]]
== Filters
[.small]#<<web.adoc#filters,Same in Spring MVC>>#
As part of the <<webflux-web-handler-api>>, the `spring-web` module provides a number of
`WebFilter` implementations.
[[webflux-filters-forwarded-headers]]
=== Forwarded Headers
[.small]#<<web.adoc#filters-forwarded-headers,Same in Spring MVC>>#
As a request goes through proxies such as load balancers the host, port, and
scheme may change presenting a challenge for applications that need to create links
to resources since the links should reflect the host, port, and scheme of the
original request as seen from a client perspective.
https://tools.ietf.org/html/rfc7239[RFC 7239] defines the "Forwarded" HTTP header
for proxies to use to provide information about the original request. There are also
other non-standard headers in use such as "X-Forwarded-Host", "X-Forwarded-Port",
and "X-Forwarded-Proto".
`ForwardedHeaderFilter` detects, extracts, and uses information from the "Forwarded"
header, or from "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto".
It wraps the request in order to overlay its host, port, and scheme and also "hides"
the forwarded headers for subsequent processing.
Note that there are security considerations when using forwarded headers as explained
in Section 8 of RFC 7239. At the application level it is difficult to determine whether
forwarded headers can be trusted or not. This is why the network upstream should be
configured correctly to filter out untrusted forwarded headers from the outside.
Applications that don't have a proxy and don't need to use forwarded headers can
configure the `ForwardedHeaderFilter` to remove and ignore such headers.
[[webflux-controller]]

4
src/docs/asciidoc/web/webmvc.adoc
View File

@ -1029,6 +1029,7 @@ Once the Servlet 3.0 configuration is in place, simply add a bean of type
[[filters]]
== Filters
[.small]#<<web-reactive.adoc#webflux-filters,Same in Spring WebFlux>>#
The `spring-web` module provides some useful filters.
@ -1048,8 +1049,9 @@ available through the `ServletRequest.getParameter{asterisk}()` family of method
[[filters-forwarded-headers]]
[[webflux-filters-forwarded-headers]]
=== Forwarded Headers
[.small]#<<web-reactive.adoc#webflux-filters-forwarded-headers,Same in Spring WebFlux>>#
As a request goes through proxies such as load balancers the host, port, and
scheme may change presenting a challenge for applications that need to create links