From a7d8103d640f76de95f92bdda87582a863d7ddba Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Mon, 29 Jun 2015 16:40:50 +0200 Subject: [PATCH] Polish CORS documentation in the reference manual --- src/asciidoc/web-cors.adoc | 51 +++++++++++++++++++++----------------- 1 file changed, 28 insertions(+), 23 deletions(-) diff --git a/src/asciidoc/web-cors.adoc b/src/asciidoc/web-cors.adoc index ea3e1e03fa..3a9ab413c2 100644 --- a/src/asciidoc/web-cors.adoc +++ b/src/asciidoc/web-cors.adoc @@ -5,19 +5,19 @@ For security reasons, browsers prohibit AJAX calls to resources residing outside the current origin. For example, as you're checking your bank account in one tab, you -could have the evil.com website in another tab. The scripts from evil.com should not -be able to make AJAX requests to your bank API (withdrawing money from your account!) +could have the evil.com website open in another tab. The scripts from evil.com should not +be able to make AJAX requests to your bank API (e.g., withdrawing money from your account!) using your credentials. http://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing] (CORS) is a http://www.w3.org/TR/cors/[W3C specification] implemented by http://caniuse.com/#feat=cors[most browsers] that allows you to specify in a flexible way what kind of cross domain requests are authorized, instead of using some less secured -and less powerful hacks like IFrame or JSONP. +and less powerful hacks like IFRAME or JSONP. As of Spring Framework 4.2, CORS is supported out of the box. CORS requests (https://github.com/spring-projects/spring-framework/blob/master/spring-webmvc/src/main/java/org/springframework/web/servlet/FrameworkServlet.java#L906[including preflight ones with an `OPTIONS` method]) -are automatically dispatched to the various `HandlerMapping` registered. They handle +are automatically dispatched to the various registered ++HandlerMapping++s. They handle CORS preflight requests and intercept CORS simple and actual requests thanks to a http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsProcessor.html[CorsProcessor] implementation (https://github.com/spring-projects/spring-framework/blob/master/spring-web/src/main/java/org/springframework/web/cors/DefaultCorsProcessor.java[DefaultCorsProcessor] @@ -26,17 +26,18 @@ based on the CORS configuration you have provided. [NOTE] ==== -Since CORS requests are automatically dispatched, you *do not need* to change -`DispatcherServlet` `dispatchOptionsRequest` init parameter value, using its default value +Since CORS requests are automatically dispatched, you *do not need* to change the +`DispatcherServlet` `dispatchOptionsRequest` init parameter value; using its default value (`false`) is the recommended approach. ==== == Controller method CORS configuration -You can add to your `@RequestMapping` annotated handler method a +You can add an http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`] -annotation in order to enable CORS on it (by default `@CrossOrigin` allows all origins -and the HTTP methods specified in the `@RequestMapping` annotation): +annotation to your `@RequestMapping` annotated handler method in order to enable CORS on +it. By default `@CrossOrigin` allows all origins and the HTTP methods specified in the +`@RequestMapping` annotation: [source,java,indent=0] [subs="verbatim,quotes"] @@ -51,7 +52,7 @@ public class AccountController { // ... } - @RequestMapping(method = RequestMethod.DELETE, value = "/{id}") + @RequestMapping(method = RequestMethod.DELETE, path = "/{id}") public void remove(@PathVariable Long id) { // ... } @@ -73,16 +74,19 @@ public class AccountController { // ... } - @RequestMapping(method = RequestMethod.DELETE, value = "/{id}") + @RequestMapping(method = RequestMethod.DELETE, path = "/{id}") public void remove(@PathVariable Long id) { // ... } } ---- -In this example CORS support is enabled for both `retrieve()` and `remove()` handler methods, and you can also see how you can customize the CORS configuration using `@CrossOrigin` attributes. +In the above example CORS support is enabled for both the `retrieve()` and the `remove()` +handler methods, and you can also see how you can customize the CORS configuration using +`@CrossOrigin` attributes. -You can even use both controller and method level CORS configurations, Spring will then combine both annotation attributes to create a merged CORS configuration. +You can even use both controller-level and method-level CORS configurations; Spring will +then combine attributes from both annotations to create merged CORS configuration. [source,java,indent=0] [subs="verbatim,quotes"] @@ -98,7 +102,7 @@ public class AccountController { // ... } - @RequestMapping(method = RequestMethod.DELETE, value = "/{id}") + @RequestMapping(method = RequestMethod.DELETE, path = "/{id}") public void remove(@PathVariable Long id) { // ... } @@ -109,8 +113,8 @@ public class AccountController { In addition to fine-grained, annotation-based configuration you'll probably want to define some global CORS configuration as well. This is similar to using filters but can -be declared withing Spring MVC and combined with fine-grained `@CrossOrigin` configuration. -By default all origins and `GET`, `HEAD` and `POST` methods are allowed. +be declared within Spring MVC and combined with fine-grained `@CrossOrigin` configuration. +By default all origins and `GET`, `HEAD`, and `POST` methods are allowed. === JavaConfig @@ -154,7 +158,8 @@ public class WebConfig extends WebMvcConfigurerAdapter { === XML namespace -This minimal XML configuration enable CORS on `/**` path pattern with the same default properties than the JavaConfig one: +The following minimal XML configuration enables CORS for the `/**` path pattern with +the same default properties as with the aforementioned JavaConfig examples: [source,xml,indent=0] [subs="verbatim"] @@ -184,7 +189,7 @@ It is also possible to declare several CORS mappings with customized properties: ---- -== Advanced Customizations +== Advanced Customization http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsConfiguration.html[CorsConfiguration] allows you to specify how the CORS requests should be processed: allowed origins, headers, methods, etc. @@ -192,10 +197,10 @@ It can be provided in various ways: * http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/servlet/handler/AbstractHandlerMapping.html#setCorsConfiguration-java.util.Map-[`AbstractHandlerMapping#setCorsConfiguration()`] allows to specify a `Map` with several http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsConfiguration.html[CorsConfiguration] - mapped on path patterns like `/api/**` - * Subclasses can provide their own `CorsConfiguration` by overriding - `AbstractHandlerMapping#getCorsConfiguration(Object, HttpServletRequest)` method - * Handlers can implement http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsConfigurationSource.html[`CorsConfigurationSource`] + instances mapped to path patterns like `/api/**`. + * Subclasses can provide their own `CorsConfiguration` by overriding the + `AbstractHandlerMapping#getCorsConfiguration(Object, HttpServletRequest)` method. + * Handlers can implement the http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsConfigurationSource.html[`CorsConfigurationSource`] interface (like https://github.com/spring-projects/spring-framework/blob/master/spring-webmvc/src/main/java/org/springframework/web/servlet/resource/ResourceHttpRequestHandler.java[`ResourceHttpRequestHandler`] now does) in order to provide a http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsConfiguration.html[CorsConfiguration] - for each request. \ No newline at end of file + instance for each request. \ No newline at end of file