- Cross-Origin Resource Sharing (CORS)
for your Java web apps
- Implements the new W3C mechanism
for cross-domain requests
- Quick and transparent fit to new
and existing Java web apps
CORS Filter is the first universal solution for fitting Cross-Origin Resource Sharing (CORS) support to Java web applications. CORS is a recent W3C effort to introduce a standard mechanism for enabling cross-domain requests from web browsers to servers that wish to handle them.
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.
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.
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 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
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
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
file. The CORS Filter implementation is extremely efficient too - it takes
just 33K of bytecode.
- Request tagging
- Technical specification
- Tips and tricks
- Browser bugs and quirks
Official W3C documents:
Useful notes, tips and tricks:
- How to detect CORS support in a browser
- How to debug CORS requests with FireBug
- Mozilla notes on cross-domain XHR
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.CORS Filter
For Maven add the following dependency to your
<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.
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.
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
Alexey Zvolinsky contributed the CORS Filter variant that can automatically detect changes to the configuration file and reconfigure itself.