diff --git a/src/asciidoc/web-cors.adoc b/src/asciidoc/web-cors.adoc new file mode 100644 index 00000000000..ea3e1e03fac --- /dev/null +++ b/src/asciidoc/web-cors.adoc @@ -0,0 +1,201 @@ +[[cors]] += CORS Support + +== Introduction + +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!) +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. + +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 +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] +by default) in order to add the relevant CORS response headers (like `Access-Control-Allow-Origin`) +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 +(`false`) is the recommended approach. +==== + +== Controller method CORS configuration + +You can add to your `@RequestMapping` annotated handler method a +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): + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- +@RestController +@RequestMapping("/account") +public class AccountController { + + @CrossOrigin + @RequestMapping("/{id}") + public Account retrieve(@PathVariable Long id) { + // ... + } + + @RequestMapping(method = RequestMethod.DELETE, value = "/{id}") + public void remove(@PathVariable Long id) { + // ... + } +} +---- + +It is also possible to enable CORS for the whole controller: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- +@CrossOrigin(origins = "http://domain2.com", maxAge = 3600) +@RestController +@RequestMapping("/account") +public class AccountController { + + @RequestMapping("/{id}") + public Account retrieve(@PathVariable Long id) { + // ... + } + + @RequestMapping(method = RequestMethod.DELETE, value = "/{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. + +You can even use both controller and method level CORS configurations, Spring will then combine both annotation attributes to create a merged CORS configuration. + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- +@CrossOrigin(maxAge = 3600) +@RestController +@RequestMapping("/account") +public class AccountController { + + @CrossOrigin(origins = "http://domain2.com") + @RequestMapping("/{id}") + public Account retrieve(@PathVariable Long id) { + // ... + } + + @RequestMapping(method = RequestMethod.DELETE, value = "/{id}") + public void remove(@PathVariable Long id) { + // ... + } +} +---- + +== Global CORS configuration + +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. + +=== JavaConfig + +Enabling CORS for the whole application is as simple as: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- +@Configuration +@EnableWebMvc +public class WebConfig extends WebMvcConfigurerAdapter { + + @Override + public void addCorsMappings(CorsRegistry registry) { + registry.addMapping("/**"); + } +} +---- + +You can easily change any properties, as well as only apply this CORS configuration to a +specific path pattern: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- +@Configuration +@EnableWebMvc +public class WebConfig extends WebMvcConfigurerAdapter { + + @Override + public void addCorsMappings(CorsRegistry registry) { + registry.addMapping("/api/**") + .allowedOrigins("http://domain2.com") + .allowedMethods("PUT", "DELETE") + .allowedHeaders("header1", "header2", "header3") + .exposedHeaders("header1", "header2") + .allowCredentials(false).maxAge(3600); + } +} +---- + +=== XML namespace + +This minimal XML configuration enable CORS on `/**` path pattern with the same default properties than the JavaConfig one: + +[source,xml,indent=0] +[subs="verbatim"] +---- + + + +---- + +It is also possible to declare several CORS mappings with customized properties: + +[source,xml,indent=0] +[subs="verbatim"] +---- + + + + + + + +---- + +== Advanced Customizations + +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. +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`] + 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 diff --git a/src/asciidoc/web.adoc b/src/asciidoc/web.adoc index ae17eddc960..debdaa66f51 100644 --- a/src/asciidoc/web.adoc +++ b/src/asciidoc/web.adoc @@ -32,3 +32,5 @@ include::web-integration.adoc[leveloffset=+1] include::web-portlet.adoc[leveloffset=+1] include::web-websocket.adoc[leveloffset=+1] + +include::web-cors.adoc[leveloffset=+1]