CORS Filter : Cross-Origin Resource Sharing for Your Java Web Apps

The first universal CORS implementation for Java web apps

CORS Filter is a generic solution for fitting Cross-Origin Resource Sharing (CORS) support to Java web applications. CORS is a W3C standard for enabling cross-domain requests from web browsers to servers and web APIs that opt in to handle them.

The CORS web context

The future of the web is cross-domain, not same-origin

Since the early days of the web (think Netscape 2.0) browsers have enforced, to various degrees, a same origin policy to prevent leaking of confidential user data to third party sites. The same origin policy was carried over to the revolutionary XMLHttpRequest which appeared in the early 2000's. Modern web applications, however, increasingly seek to dynamically integrate content and services from third parties, which was initially achieved through "hacks" such as JSONP. CORS was created in recognition that cross-domain requests advance the spirit of the web, are here to stay, and therefore they'd better be standardised.

The philosophy of CORS

CORS works two-fold:

From a browser script perspective: By allowing cross-domain requests, which are subject to tighter controls on the types of data that is exchanged. Cookies, for instance, are blocked unless specifically requested by the XHR author and allowed by the cross-domain web service. This is done to mitigate the risk of data leaks.
From a web service perspective: By utilising the origin URL reported by the browser the target cross-domain web service can determine, based on its origin policy, whether to allow or deny the request.

The complete CORS specification is available at http://www.w3.org/TR/cors/

Note that in order for CORS to work, it must be supported by both browser and web server.

Security

Bear in mind that CORS is not about providing server-side security. The Origin request header is set by the browser and the server has no direct means to verify it.

Browsers supporting CORS

All major browsers support CORS. The reported penetration among users is at 89% as of November 2013.


Firefox 3.5+	Internet Explorer 8+^✝	Google Chrome 3+	Apple Safari 4+	Opera 12+

^✝ Partial support via the XDomainRequest object. Version 10 of IE is expected to have full CORS support integrated into the common XMLHttpRequest object.

The CORS Filter solution - plug in and forget

CORS Filter context
The CORS Filter can be plugged into any standard Java Servlet container to handle cross-site requests to servlets, JSPs and HTML files residing on the server.

The CORS Filter, as the name implies, implements the standard javax.servlet.Filter interface. It intercepts incoming HTTP requests and if they are identified as cross-origin, it applies the proper CORS policy and headers, before passing the HTTP requests on to the actual targets (servlets, JSPs, static XML/HTML documents).

This transparent nature of the CORS Filter makes it easy to retrofit existing Java web services with a CORS capability. Just put the CORS JAR file into your CLASSPATH and enable it with a few lines of XML in your web.xml file. The CORS Filter implementation is extremely efficient too - it takes just 33K of bytecode.

CORS Filter documentation

Resources

Official W3C documents:

The W3C Working Draft on Cross-Origin Resource Sharing

Useful notes, tips and tricks:

Download

The CORS Filter source code is open and available under the terms of the Apache 2.0 licence. It is shipped as a JAR file ready for immediate deployment to your web app. A CORS demo WAR is also provided.

Download now CORS Filter

Maven

For Maven add the following dependency to your pom.xml

<dependency>
	<groupId>com.thetransactioncompany</groupId>
	<artifactId>cors-filter</artifactId>
	<version>[ version ]</version>
</dependency>

where version should be the latest stable release of the CORS Filter.

Git repo

Visit https://bitbucket.org/thetransactioncompany/cors-filter.

Reporting issues

Please use the CORS Filter issue tracker to report bugs or submit suggestions. Pull requests should include tests if possible, to demonstrate the bug and prevent future regression after the fix.

For general questions or feedback you can get in touch with me directly.

Credits

Thanks to Anne van Kesteren and Adam Barth for answering my queries on the W3C mailing list during the development of the CORS Filter. Also thanks to the greater community for the effort to come up with a web standard to solve the issue of cross-origin HTTP requests.

Joost Cassee contributed the Maven POM for the CORS Filter and the Java Property Utils dependency.

Jared Ottley and Luis Sala of Alfresco contributed the Origin subdomains matching feature which appeared in version 1.4.

Gervasio Amy contributed a response wrapper to preserve the CORS headers on a HttpServletResponse.reset() called by the web application or framework.

Alexey Zvolinsky contributed the CORS Filter variant that can automatically detect changes to the configuration file and reconfigure itself.