CORS Filter
Specification
Cross-origin resource sharing (CORS) support
The CORS filter allows a Java web application to handle cross-site HTTP requests from web browsers according to the Cross-Origin Resource Sharing (CORS) mechanism specified by the W3C recommendation from 2014-01-16.
Supported CORS request types:
Supported CORS headers:
- Request headers:
- Response headers:
Java Servlet Filter
The software is implemented as a Java servlet filter that can be plugged into any web application running in a standard Java servlet container, such as the popular open source Apache Tomcat server. The CORS filter does its job in a wholly transparent manner; no modifications to existing Java application code are required.
Configuration
The CORS filter can be run in the default policy mode (all origins allowed, credentials allowed), or it may be optionally configured to impose a specific access policy.
The configuration can be passed as standard
init-param
elements in the web.xml descriptor file or in a
properties file.
Available configuration parameters:
- cors.allowGenericHttpRequests
- cors.allowOrigin
- cors.allowSubdomains
- cors.supportedMethods
- cors.supportedHeaders
- cors.exposedHeaders
- cors.supportsCredentials
- cors.maxAge
- cors.tagRequests
HTTP request tagging
Each filtered HTTP request can be tagged to provide optional CORS-related information to downstream handlers (other filters or the target resource).
Applied tags:
System requirements and dependencies
- Java 7+
- Java servlet container, conforming to version 3.0+ of the servlet API.
- PropertyUtil 1.9+ Utility library for typed retrieval of properties, developed in-house.
Source code
The CORS Filter source code, build script and demo code is included in the download package.
JavaDocs
Browse the CORS Filter JavaDocs.
Change log
- version 1.0 (2010-09-29)
- First official release.
- version 1.1 (2010-10-10)
- Tags CORS requests for downstream notification using HttpServletRequest.addAttribute().
- version 1.2 (2010-12-13)
- Released under the Apache Open Source License 2.0.
- version 1.2.1 (2011-07-29)
- Updates Property Util JAR to 1.4.
- Updates documentation to reflect the latest W3C CORS terminology.
- version 1.3 (2011-12-02)
- Fixes improper detection of actual HTTP OPTIONS CORS requests.
- Updates Property Util JAR to 1.5.
- version 1.3.1 (2011-12-02)
- Removes improper filter chain for preflight HTTP OPTIONS CORS requests.
- version 1.3.2 (2012-07-31)
- Updates Property Util JAR to 1.6.
- Adds Maven POM.
- Updates Ant build.xml script.
- version 1.4 (2012-10-19)
- Adds new optional cors.allowSubdomains configuration parameter to enable domain suffix matching (contributed by Jared Ottley and Luis Sala of Alfresco).
- Removes support of file:// CORS scheme.
- Refactors Origin processing.
- version 1.5 (2012-10-19)
- Removes support of multivalued Origin headers according to the latest CORS spec from 2012-04-03.
- version 1.5.1 (2013-04-03)
- Updates CORS spec reference.
- Switches build to Apache Maven and enables publishing to Maven Central.
- version 1.6 (2013-04-18)
- Permits any URI scheme, not just http and https, according to RFC 6454.
- version 1.7 (2013-05-20)
- Corrects handling of same-origin requests that specify an Origin header.
- Augments the cors.supportedHeader configuration option to enable specification of an allow-any-header policy.
- Upgrades to Property Utils JAR 1.9.
- version 1.7.1 (2013-06-18)
- Fixes a NullPointerException bug in CORSRequestHandler.
- version 1.8 (2013-11-05)
- Switches to ServletContext.getResourceAsStream(String) for loading the configuration properties file in a more reliable manner.
- Updates the CORS specification references.
- version 1.9 (2013-12-29)
- Adds cors.tagRequests configuration option to enable / disable tagging of handled HTTP requests with CORS information, to be passed to downstream filters and servlets.
- Adds support for loading the configuration properties file relative to the application classpath.
- Upgrades to Property Utils JAR 1.9.1.
- version 1.9.1 (2014-01-10)
- Makes '*' the preferred value of Access-Control-Allow-Origin response headers (see issue #16).
- version 1.9.2 (2014-01-13)
- Adds Vary: Origin header to preflight and actual requests if credentials are allowed or the allowed origin list is bounded (see issue #16).
- version 1.9.3 (2014-05-13)
- Fixes validation of HTTP Header names (issue #19).
- version 2.0 (2014-06-21)
- Upgrades to Servlet API 3.0.
- Annotates CORSFilter to enable asynchronous requests.
- Adds HttpServletResponseWrapper to preserve CORS response headers on HttpServletResponse.reset().
- version 2.1 (2014-06-22)
- Narrows down CORS response headers to preserve in CORSResponseWrapper.
- Removes bound on supported HTTP methods.
- version 2.1.1 (2014-07-07)
- Fixes regression bug affecting Access-Control-Allow-Headers (issue #22).
- version 2.1.2 (2014-08-08)
- Removes @WebFilter(asyncSupported = true) annotation, asynchronous support should be specified in web.xml instead (issue #26).
- version 2.2 (2014-10-07)
- Adds support for constructor-based initialisation (issue #24).
- version 2.2.1 (2014-10-08)
- Restores public CORSFilter constructor (issue #27).
- version 2.3 (2015-02-06)
- Adds origin verification to CORSOriginDeniedException to prevent potential XSS (issue #29).
- version 2.4 (2015-03-29)
- Adds support for automatic reconfiguration (iss #23).
- version 2.5 (2015-11-13)
- Adds host check to ValidatedOrigin constructor (iss #32).
- Simplifies and improves performance of CORS exception handling.
- version 2.6 (2017-07-24)
- The CORS Filter configuration file can now also be specified with an absolute path.