Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Polish CORS documentation in the reference manual

Browse Source
This commit is contained in:
Sam Brannen
2015-06-29 16:40:50 +02:00
parent 39d689da0c
commit a7d8103d64
1 changed files with 28 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
src/asciidoc/web-cors.adoc
View File

@@ -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:
</mvc:cors>
----
== 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.
instance for each request.