- Introduction
- Quick Start
- Using CORS Filter in Your Maven Project
- Configuring CORS Filter
- Information added by CORS Filter about request in HttpServletRequest object
- Background on CORS
- How it works
- References
CORS (Cross Origin Resource Sharing) is a mechanism to enable cross origin requests. W3C defines the standards that enable this mechanism. CORS requires support from both the server and the browser in order to work. This is a Java Servlet Filter implementation of server-side CORS for Java web containers such as Apache Tomcat. Salient features:
- Easy to integrate and use - enable CORS capability with a few lines in your web.xml!
- Protects against CRLF injection / response splitting attacks.
Here's a link to a demo application running on google app engine: https://corsdemo.appspot.com/
Include cors-filter-x.x.x.jar in your web-application's classpath. Then, add the filter configuration to your web.xml. Example:
<filter>
<filter-name>CORS Filter</filter-name>
<filter-class>org.ebaysf.web.cors.CORSFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>CORS Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>Add the cors-filter as a dependency:
<dependency>
<groupId>org.ebaysf.web</groupId>
<artifactId>cors-filter</artifactId>
<version>1.0.0</version>
</dependency>And, add the filter configuration in web.xml as demonstrated in the Quick Start section
The minimal configuration required to use CORS Filter is:
<filter>
<filter-name>CORS Filter</filter-name>
<filter-class>org.ebaysf.web.cors.CORSFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>CORS Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>The table below lists various parameters that can be used to configure CORS Filter. If a parameter is not provided a default (documented below) is used.
| param-name | description |
|---|---|
| cors.allowed.origins | A list of origins that are allowed to access the resource. A '*' can be specified to enable access to resource from any origin. Otherwise, a whitelist of comma separated origins can be provided. Ex: https://www.w3.org, https://www.apache.org. Defaults: * (Any origin is allowed to access the resource). |
| cors.allowed.methods | A comma separated list of HTTP methods that can be used to access the resource, using cross-origin requests. These are the methods which will also be included as part of 'Access-Control-Allow-Methods' header in a pre-flight response. Ex: GET,POST. Defaults: GET,POST,HEAD,OPTIONS |
| cors.allowed.headers | A comma separated list of request headers that can be used when making an actual request. These header will also be returned as part of 'Access-Control-Allow-Headers' header in a pre-flight response. Ex: Origin,Accept. Defaults: Origin,Accept,X-Requested-With,Content-Type,Access-Control-Request-Method,Access-Control-Request-Headers |
| cors.exposed.headers | A comma separated list of headers other than the simple response headers that browsers are allowed to access. These are the headers which will also be included as part of 'Access-Control-Expose-Headers' header in the pre-flight response. Ex: X-CUSTOM-HEADER-PING,X-CUSTOM-HEADER-PONG. Default: None |
| cors.preflight.maxage | The amount of seconds, browser is allowed to cache the result of the pre-flight request. This will be included as part of 'Access-Control-Max-Age' header in the pre-flight response. A negative value will prevent CORS Filter from adding this response header from pre-flight response. Defaults: 1800 |
| cors.support.credentials | A flag that indicates whether the resource supports user credentials. This flag is exposed as part of 'Access-Control-Allow-Credentials' header in a pre-flight response. It helps browser determine whether or not an actual request can be made using credentials. Defaults: true |
| cors.logging.enabled | A flag to control logging to container logs. Defaults: false |
| cors.request.decorate | A flag to control if the request should be decorated or not. Defaults: true |
To override filter configuration defaults, specify them in the init-params while configuring the filter in web.xml. Example:
<filter>
<filter-name>CORS Filter</filter-name>
<filter-class>org.ebaysf.web.cors.CORSFilter</filter-class>
<init-param>
<description>A comma separated list of allowed origins. Note: An '*' cannot be used for an allowed origin when using credentials.</description>
<param-name>cors.allowed.origins</param-name>
<param-value>https://localhost:8080,https://localhost.ebay.com:8080</param-value>
</init-param>
<init-param>
<description>A comma separated list of HTTP verbs, using which a CORS request can be made.</description>
<param-name>cors.allowed.methods</param-name>
<param-value>GET,POST,HEAD,OPTIONS,PUT</param-value>
</init-param>
<init-param>
<description>A comma separated list of allowed headers when making a non simple CORS request.</description>
<param-name>cors.allowed.headers</param-name>
<param-value>Content-Type,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers</param-value>
</init-param>
<init-param>
<description>A comma separated list non-standard response headers that will be exposed to XHR2 object.</description>
<param-name>cors.exposed.headers</param-name>
<param-value></param-value>
</init-param>
<init-param>
<description>A flag that suggests if CORS is supported with cookies</description>
<param-name>cors.support.credentials</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<description>A flag to control logging</description>
<param-name>cors.logging.enabled</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<description>Indicates how long (in seconds) the results of a preflight request can be cached in a preflight result cache.</description>
<param-name>cors.preflight.maxage</param-name>
<param-value>10</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CORS Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>CORS Filter adds information about a CORS request, in the HttpServletRequest object, for consumption downstream. Following attributes are set:
- cors.isCorsRequest: Flag to determine if a request is a CORS request.
- cors.request.origin: Origin URL.
- cors.request.type: Type of CORS request. Possible values:
- SIMPLE: A request which is not preceded by a pre-flight request.
- ACTUAL: A request which is preceded by a pre-flight request.
- PRE_FLIGHT: A pre-flight request.
- NOT_CORS: A normal same-origin request.
- INVALID_CORS: A cross-origin request, which is invalid.
- cors.request.headers: Request headers sent as 'Access-Control-Request-Headers' header, for a pre-flight request.
To prevent CORS Filter from setting above attributes, set 'cors.request.decorate' init-param to false.
A cross origin request, is a HTTP request for a resource that serves from a different origin than the origin of the application that is requesting the resource. For example, a request originating from a page served from https://www.ebay.com, to a resource on https://www.google.com.
Same origin policy in browsers prevents XMLHttpRequest to make a request to a resource, on a origin that's different from the source origin.
By enabling CORS support on server side, a resource can support cross-origin requests in a way that's supported by W3C standards. For more details, please refer: W3C CORS
Here's a list of good resources to start with CORS: