By default all origins and headers are permitted, credentials are not allowed, - * and the maximum age is set to 1800 seconds (30 minutes). The list of HTTP - * methods is set to the methods on the {@code @RequestMapping} if not - * explicitly set on {@code @CrossOrigin}. - * - *
NOTE: {@code @CrossOrigin} is processed if an appropriate - * {@code HandlerMapping}-{@code HandlerAdapter} pair is configured such as the - * {@code RequestMappingHandlerMapping}-{@code RequestMappingHandlerAdapter} - * pair which are the default in the MVC Java config and the MVC namespace. + *
Both Spring Web MVC and Spring WebFlux support this annotation through the + * {@code RequestMappingHandlerMapping} in their respective modules. The values + * from each type and method level pair of annotations are added to a + * {@link CorsConfiguration} and then default values are applied via + * {@link CorsConfiguration#applyPermitDefaultValues()}. * * @author Russell Allen * @author Sebastien Deleuze @@ -48,27 +46,19 @@ import org.springframework.web.cors.CorsConfiguration; @Documented public @interface CrossOrigin { - /** - * @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues} - */ + /** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */ @Deprecated String[] DEFAULT_ORIGINS = { "*" }; - /** - * @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues} - */ + /** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */ @Deprecated String[] DEFAULT_ALLOWED_HEADERS = { "*" }; - /** - * @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues} - */ + /** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */ @Deprecated boolean DEFAULT_ALLOW_CREDENTIALS = false; - /** - * @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues} - */ + /** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */ @Deprecated long DEFAULT_MAX_AGE = 1800; @@ -80,62 +70,69 @@ public @interface CrossOrigin { String[] value() default {}; /** - * List of allowed origins, e.g. {@code "http://domain1.com"}. - *
These values are placed in the {@code Access-Control-Allow-Origin} - * header of both the pre-flight response and the actual response. - * {@code "*"} means that all origins are allowed. - *
If undefined, all origins are allowed. + * The list of allowed origins that be specific origins, e.g. + * {@code "http://domain1.com"}, or {@code "*"} for all origins. + *
A matched origin is listed in the {@code Access-Control-Allow-Origin} + * response header of preflight actual CORS requests. + *
By default all origins are allowed. * @see #value */ @AliasFor("value") String[] origins() default {}; /** - * List of request headers that can be used during the actual request. - *
This property controls the value of the pre-flight response's - * {@code Access-Control-Allow-Headers} header. - * {@code "*"} means that all headers requested by the client are allowed. - *
If undefined, all requested headers are allowed. + * The list of request headers that are permitted in actual requests, + * possibly {@code "*"} to allow all headers. + *
Allowed headers are listed in the {@code Access-Control-Allow-Headers} + * response header of preflight requests. + *
A header name is not required to be listed if it is one of: + * {@code Cache-Control}, {@code Content-Language}, {@code Expires}, + * {@code Last-Modified}, or {@code Pragma} as per the CORS spec. + *
By default all requested headers are allowed. */ String[] allowedHeaders() default {}; /** - * List of response headers that the user-agent will allow the client to access. - *
This property controls the value of actual response's - * {@code Access-Control-Expose-Headers} header. - *
If undefined, an empty exposed header list is used. + * The List of response headers that the user-agent will allow the client + * to access on an actual response, other than "simple" headers, i.e. + * {@code Cache-Control}, {@code Content-Language}, {@code Content-Type}, + * {@code Expires}, {@code Last-Modified}, or {@code Pragma}, + *
Exposed headers are listed in the {@code Access-Control-Expose-Headers} + * response header of actual CORS requests. + *
By default no headers are listed as exposed. */ String[] exposedHeaders() default {}; /** - * List of supported HTTP request methods, e.g. - * {@code "{RequestMethod.GET, RequestMethod.POST}"}. - *
Methods specified here override those specified via {@code RequestMapping}. - *
If undefined, methods defined by {@link RequestMapping} annotation - * are used. + * The list of supported HTTP request methods. + *
By default the supported methods are the same as the ones to which a + * controller method is mapped. */ RequestMethod[] methods() default {}; /** - * Whether the browser should include any cookies associated with the - * domain of the request being annotated. Be aware that enabling this option could - * increase the surface attack of the web application (for example via exposing - * sensitive user-specific information like CSRF tokens). - *
Set to {@code "true"} means that the pre-flight response will include the header - * {@code Access-Control-Allow-Credentials=true} so such cookies should be included. - *
If undefined or set to {@code "false"}, such header is not included and - * credentials are not allowed. + * Whether the browser should send credentials, such as cookies along with + * cross domain requests, to the annotated endpoint. The configured value is + * set on the {@code Access-Control-Allow-Credentials} response header of + * preflight requests. + *
NOTE: Be aware that this option establishes a high + * level of trust with the configured domains and also increases the surface + * attack of the web application by exposing sensitive user-specific + * information such as cookies and CSRF tokens. + *
By default this is not set in which case the + * {@code Access-Control-Allow-Credentials} header is also not set and + * credentials are therefore not allowed. */ String allowCredentials() default ""; /** - * The maximum age (in seconds) of the cache duration for pre-flight responses. + * The maximum age (in seconds) of the cache duration for preflight responses. *
This property controls the value of the {@code Access-Control-Max-Age} - * header in the pre-flight response. - *
Setting this to a reasonable value can reduce the number of pre-flight + * response header of preflight requests. + *
Setting this to a reasonable value can reduce the number of preflight * request/response interactions required by the browser. * A negative value means undefined. - *
If undefined, max age is set to {@code 1800} seconds (i.e., 30 minutes). + *
By default this is set to {@code 1800} seconds (30 minutes). */ long maxAge() default -1; diff --git a/spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java b/spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java index 9cb065465c..c9f0e48567 100644 --- a/spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java +++ b/spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java @@ -35,24 +35,20 @@ import org.springframework.util.StringUtils; * *
By default a newly created {@code CorsConfiguration} does not permit any * cross-origin requests and must be configured explicitly to indicate what - * should be allowed. - * - *
Use {@link #applyPermitDefaultValues()} to flip the initialization model
- * to start with open defaults that permit all cross-origin requests for GET,
- * HEAD, and POST requests.
+ * should be allowed. Use {@link #applyPermitDefaultValues()} to flip the
+ * initialization model to start with open defaults that permit all cross-origin
+ * requests for GET, HEAD, and POST requests.
*
* @author Sebastien Deleuze
* @author Rossen Stoyanchev
* @author Juergen Hoeller
* @author Sam Brannen
* @since 4.2
- * @see CORS W3C recommendation
+ * @see CORS spec
*/
public class CorsConfiguration {
- /**
- * Wildcard representing all origins, methods, or headers.
- */
+ /** Wildcard representing all origins, methods, or headers. */
public static final String ALL = "*";
private static final List The following defaults are applied if not already set:
* The special value {@code "*"} allows all domains.
+ * The list of allowed origins that be specific origins, e.g.
+ * {@code "http://domain1.com"}, or {@code "*"} for all origins.
+ * A matched origin is listed in the {@code Access-Control-Allow-Origin}
+ * response header of preflight actual CORS requests.
* By default all origins are allowed.
*/
public CorsRegistration allowedOrigins(String... origins) {
@@ -102,6 +93,24 @@ public class CorsRegistration {
return this;
}
+ /**
+ * Whether the browser should send credentials, such as cookies along with
+ * cross domain requests, to the annotated endpoint. The configured value is
+ * set on the {@code Access-Control-Allow-Credentials} response header of
+ * preflight requests.
+ * NOTE: Be aware that this option establishes a high
+ * level of trust with the configured domains and also increases the surface
+ * attack of the web application by exposing sensitive user-specific
+ * information such as cookies and CSRF tokens.
+ * By default this is not set in which case the
+ * {@code Access-Control-Allow-Credentials} header is also not set and
+ * credentials are therefore not allowed.
+ */
+ public CorsRegistration allowCredentials(boolean allowCredentials) {
+ this.config.setAllowCredentials(allowCredentials);
+ return this;
+ }
+
/**
* Configure how long in seconds the response from a pre-flight request
* can be cached by clients.
@@ -112,17 +121,6 @@ public class CorsRegistration {
return this;
}
- /**
- * Whether user credentials are supported. Be aware that enabling this option
- * could increase the surface attack of the web application (for example via
- * exposing sensitive user-specific information like CSRF tokens).
- * By default credentials are not allowed.
- */
- public CorsRegistration allowCredentials(boolean allowCredentials) {
- this.config.setAllowCredentials(allowCredentials);
- return this;
- }
-
protected String getPathPattern() {
return this.pathPattern;
}
diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/config/CorsRegistry.java b/spring-webflux/src/main/java/org/springframework/web/reactive/config/CorsRegistry.java
index 67b3a06d33..4ef160a82d 100644
--- a/spring-webflux/src/main/java/org/springframework/web/reactive/config/CorsRegistry.java
+++ b/spring-webflux/src/main/java/org/springframework/web/reactive/config/CorsRegistry.java
@@ -24,10 +24,11 @@ import java.util.Map;
import org.springframework.web.cors.CorsConfiguration;
/**
- * {@code CorsRegistry} assists with the registration of {@link CorsConfiguration}
- * mapped to a path pattern.
+ * Assists with the registration of global, URL pattern based
+ * {@link CorsConfiguration} mappings.
*
* @author Sebastien Deleuze
+ * @author Rossen Stoyanchev
* @since 5.0
*/
public class CorsRegistry {
@@ -41,9 +42,13 @@ public class CorsRegistry {
* Exact path mapping URIs (such as {@code "/admin"}) are supported as
* well as Ant-style path patterns (such as {@code "/admin/**"}).
*
- * By default, all origins, all headers, credentials and {@code GET},
- * {@code HEAD}, and {@code POST} methods are allowed, and the max age
- * is set to 30 minutes.
+ * The following defaults are applied to the {@link CorsRegistration}:
+ * The special value {@code "*"} allows all domains.
+ * The list of allowed origins that be specific origins, e.g.
+ * {@code "http://domain1.com"}, or {@code "*"} for all origins.
+ * A matched origin is listed in the {@code Access-Control-Allow-Origin}
+ * response header of preflight actual CORS requests.
* By default, all origins are allowed.
*/
public CorsRegistration allowedOrigins(String... origins) {
@@ -68,9 +60,9 @@ public class CorsRegistration {
/**
* Set the HTTP methods to allow, e.g. {@code "GET"}, {@code "POST"}, etc.
- * The special value {@code "*"} allows all methods.
- * By default "simple" methods {@code GET}, {@code HEAD}, and {@code POST}
- * are allowed.
+ * The special value {@code "*"} allows all methods.
+ * By default "simple" methods, i.e. {@code GET}, {@code HEAD}, and
+ * {@code POST} are allowed.
*/
public CorsRegistration allowedMethods(String... methods) {
this.config.setAllowedMethods(Arrays.asList(methods));
@@ -78,9 +70,9 @@ public class CorsRegistration {
}
/**
- * Set the list of headers that a pre-flight request can list as allowed
- * for use during an actual request.
- * The special value {@code "*"} may be used to allow all headers.
+ * Set the list of headers that a preflight request can list as allowed
+ * for use during an actual request. The special value {@code "*"} may be
+ * used to allow all headers.
* A header name is not required to be listed if it is one of:
* {@code Cache-Control}, {@code Content-Language}, {@code Expires},
* {@code Last-Modified}, or {@code Pragma} as per the CORS spec.
@@ -104,6 +96,24 @@ public class CorsRegistration {
return this;
}
+ /**
+ * Whether the browser should send credentials, such as cookies along with
+ * cross domain requests, to the annotated endpoint. The configured value is
+ * set on the {@code Access-Control-Allow-Credentials} response header of
+ * preflight requests.
+ * NOTE: Be aware that this option establishes a high
+ * level of trust with the configured domains and also increases the surface
+ * attack of the web application by exposing sensitive user-specific
+ * information such as cookies and CSRF tokens.
+ * By default this is not set in which case the
+ * {@code Access-Control-Allow-Credentials} header is also not set and
+ * credentials are therefore not allowed.
+ */
+ public CorsRegistration allowCredentials(boolean allowCredentials) {
+ this.config.setAllowCredentials(allowCredentials);
+ return this;
+ }
+
/**
* Configure how long in seconds the response from a pre-flight request
* can be cached by clients.
@@ -114,17 +124,6 @@ public class CorsRegistration {
return this;
}
- /**
- * Whether user credentials are supported. Be aware that enabling this option
- * could increase the surface attack of the web application (for example via
- * exposing sensitive user-specific information like CSRF tokens).
- * By default credentials are not allowed.
- */
- public CorsRegistration allowCredentials(boolean allowCredentials) {
- this.config.setAllowCredentials(allowCredentials);
- return this;
- }
-
protected String getPathPattern() {
return this.pathPattern;
}
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistry.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistry.java
index 6fb5e19c46..ac7e56ff12 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistry.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistry.java
@@ -24,10 +24,11 @@ import java.util.Map;
import org.springframework.web.cors.CorsConfiguration;
/**
- * {@code CorsRegistry} assists with the registration of {@link CorsConfiguration}
- * mapped to a path pattern.
+ * Assists with the registration of global, URL pattern based
+ * {@link CorsConfiguration} mappings.
*
* @author Sebastien Deleuze
+ * @author Rossen Stoyanchev
* @since 4.2
* @see CorsRegistration
*/
@@ -38,14 +39,20 @@ public class CorsRegistry {
/**
* Enable cross-origin request handling for the specified path pattern.
+ *
* Exact path mapping URIs (such as {@code "/admin"}) are supported as
* well as Ant-style path patterns (such as {@code "/admin/**"}).
* By default, all origins, all headers, credentials and {@code GET},
* {@code HEAD}, and {@code POST} methods are allowed, and the max age
* is set to 30 minutes.
- * @param pathPattern the path pattern to enable CORS handling for
- * @return CorsRegistration the corresponding registration object,
- * allowing for further fine-tuning
+ *
+ * The following defaults are applied to the {@link CorsRegistration}:
+ *
- *
+ *
*/
public CorsRegistration addMapping(String pathPattern) {
CorsRegistration registration = new CorsRegistration(pathPattern);
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistration.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistration.java
index 1b0cab2d3d..db1b192e38 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistration.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistration.java
@@ -1,5 +1,5 @@
/*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -21,10 +21,8 @@ import java.util.Arrays;
import org.springframework.web.cors.CorsConfiguration;
/**
- * Assists with the creation of a {@link CorsConfiguration} instance mapped to
- * a path pattern. By default all origins, headers, and credentials for
- * {@code GET}, {@code HEAD}, and {@code POST} requests are allowed while the
- * max age is set to 30 minutes.
+ * Assists with the creation of a {@link CorsConfiguration} instance for a given
+ * URL path pattern.
*
* @author Sebastien Deleuze
* @author Rossen Stoyanchev
@@ -40,14 +38,6 @@ public class CorsRegistration {
private final CorsConfiguration config;
- /**
- * Create a new {@link CorsRegistration} that allows all origins, headers, and
- * credentials for {@code GET}, {@code HEAD}, and {@code POST} requests with
- * max age set to 1800 seconds (30 minutes) for the specified path.
- * @param pathPattern the path that the CORS configuration should apply to;
- * exact path mapping URIs (such as {@code "/admin"}) are supported as well
- * as Ant-style path patterns (such as {@code "/admin/**"}).
- */
public CorsRegistration(String pathPattern) {
this.pathPattern = pathPattern;
// Same implicit default values as the @CrossOrigin annotation + allows simple methods
@@ -56,8 +46,10 @@ public class CorsRegistration {
/**
- * Set the origins to allow, e.g. {@code "http://domain1.com"}.
- *
+ *
*/
public CorsRegistration addMapping(String pathPattern) {
CorsRegistration registration = new CorsRegistration(pathPattern);
diff --git a/spring-webmvc/src/main/resources/org/springframework/web/servlet/config/spring-mvc.xsd b/spring-webmvc/src/main/resources/org/springframework/web/servlet/config/spring-mvc.xsd
index efc126fee1..071ecae722 100644
--- a/spring-webmvc/src/main/resources/org/springframework/web/servlet/config/spring-mvc.xsd
+++ b/spring-webmvc/src/main/resources/org/springframework/web/servlet/config/spring-mvc.xsd
@@ -1310,8 +1310,11 @@