spring-framework/src/docs/asciidoc/web/webflux-cors.adoc

[[webflux-cors]]
= CORS


== 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 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.

Spring WebFlux supports CORS out of the box. CORS requests, including preflight ones with an `OPTIONS` method,
are automatically dispatched to the various registered ``HandlerMapping``s. They handle
CORS preflight requests and intercept CORS simple and actual requests thanks to a
{api-spring-framework}/web/cors/reactive/CorsProcessor.html[CorsProcessor]
implementation (https://github.com/spring-projects/spring-framework/blob/master/spring-web/src/main/java/org/springframework/web/cors/reactive/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]
====
Be aware that cookies are not allowed by default to avoid increasing the surface attack of
the web application (for example via exposing sensitive user-specific information like
CSRF tokens). Set `allowedCredentials` property to `true` in order to allow them.
====


[[webflux-cors-controller]]
== @CrossOrigin

You can add an
{api-spring-framework}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`]
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"]
----
@RestController
@RequestMapping("/account")
public class AccountController {

	@CrossOrigin
	@GetMapping("/{id}")
	public Mono<Account> retrieve(@PathVariable Long id) {
		// ...
	}

	@DeleteMapping("/{id}")
	public Mono<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 {

	@GetMapping("/{id}")
	public Mono<Account> retrieve(@PathVariable Long id) {
		// ...
	}

	@DeleteMapping("/{id}")
	public Mono<Void> remove(@PathVariable Long id) {
		// ...
	}
}
----

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-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"]
----
@CrossOrigin(maxAge = 3600)
@RestController
@RequestMapping("/account")
public class AccountController {

	@CrossOrigin("http://domain2.com")
	@GetMapping("/{id}")
	public Account retrieve(@PathVariable Long id) {
		// ...
	}

	@DeleteMapping("/{id}")
	public void remove(@PathVariable Long id) {
		// ...
	}
}
----


[[webflux-cors-java-config]]
== Java Config

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 within Spring WebFlux and combined with fine-grained `@CrossOrigin` configuration.
By default all origins and `GET`, `HEAD`, and `POST` methods are allowed.

Enabling CORS for the whole application is as simple as:

[source,java,indent=0]
[subs="verbatim,quotes"]
----
@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@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
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public void addCorsMappings(CorsRegistry registry) {
		registry.addMapping("/api/**")
			.allowedOrigins("http://domain2.com")
			.allowedMethods("PUT", "DELETE")
			.allowedHeaders("header1", "header2", "header3")
			.exposedHeaders("header1", "header2")
			.allowCredentials(true).maxAge(3600);
	}
}
----


[[webflux-cors-webfilter]]
== CORS WebFilter

You can apply CORS support through the built-in
{api-spring-framework}/web/cors/reactive/CorsWebFilter.html[`CorsWebFilter`], which is a
good fit with <<webflux-fn,functional endpoints>>.

To configure the filter, you can declare a `CorsWebFilter` bean and pass a
`CorsConfigurationSource` to its constructor:

[source,java,indent=0]
----
@Bean
CorsWebFilter corsFilter() {
	CorsConfiguration config = new CorsConfiguration();
	config.setAllowCredentials(true);
	config.addAllowedOrigin("http://domain1.com");
	config.addAllowedHeader("*");
	config.addAllowedMethod("*");

	UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
	source.registerCorsConfiguration("/**", config);

	return new CorsWebFilter(source);
}
----

You can also easily permit all cross-origin requests for GET, HEAD, and POST requests by writing
[source,java,indent=0]

----
@Bean
CorsWebFilter corsFilter() {
	return new CorsWebFilter(exchange -> new CorsConfiguration().applyPermitDefaultValues());
}
----


[[webflux-cors-customizations]]
== Advanced Customization

{api-spring-framework}/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:

 * {api-spring-framework}/web/reactive/handler/AbstractHandlerMapping.html#setCorsConfigurations-java.util.Map-[`AbstractHandlerMapping#setCorsConfigurations()`]
   allows to specify a `Map` with several {api-spring-framework}/web/cors/CorsConfiguration.html[CorsConfiguration]
   instances mapped to path patterns like `/api/**`.
 * Subclasses can provide their own `CorsConfiguration` by overriding the
   `AbstractHandlerMapping#getCorsConfiguration(Object, ServerWebExchange)` method.
 * Handlers can implement the {api-spring-framework}/web/cors/reactive/CorsConfigurationSource.html[`CorsConfigurationSource`]
   interface in order to provide a {api-spring-framework}/web/cors/CorsConfiguration.html[CorsConfiguration]
   instance for each request.