CORS Filter : Installation

The CORS Filter can run in any Java Servlet 3.0+ compatible web container, such as the popular open source Apache Tomcat server. Installation is a straightforward 3-step process.

1. Place the CORS JAR and its dependency in the CLASSPATH

Download the cors-filter-<version>.jar file and its java-property-utils-<version>.jar dependency, and put them into the CLASSPATH of your web server.

cors-filter-2.6.jar java-property-utils-1.9.1.jar

If you have Apache Tomcat there are two CLASSPATH choices: If you intend to use CORS with a single web application put the JAR file in

$CATALINA_HOME/webapps/<your-web-app>/WEB-INF/lib/

To make CORS available globally, to all web applications, place the JAR in

$CATALINA_HOME/lib/

Alternatively, if you use Maven to build your project WAR file, 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.

2. Add CORS configuration to web.xml

Open the WEB-INF/web.xml file of the web application where you intend to enable CORS and add a CORS Filter declaration and mapping.

The XML declaration to load the CORS filter:

<filter>
	<filter-name>CORS</filter-name>
	<filter-class>com.thetransactioncompany.cors.CORSFilter</filter-class>
</filter>

To use a variant of the CORS Filter that can automatically detect changes to the configuration file and reconfigure itself use the following declaration instead:

<filter>
	<filter-name>CORS</filter-name>
	<filter-class>com.thetransactioncompany.cors.autoreconf.AutoReconfigurableCORSFilter</filter-class>
</filter>

Then declare a filter mapping to tell the web server which servlets or URLs should be cross-domain-request enabled.

Example of applying the CORS filter to a single servlet:

<filter-mapping>
        <filter-name>CORS</filter-name>
        <servlet-name>MyServlet</servlet-name>
</filter-mapping>

And how to apply the CORS filter to all web app URLs:

<filter-mapping>
        <filter-name>CORS</filter-name>
        <url-pattern>/*</url-pattern>
</filter-mapping>

Have a look at the web.xml of the demo CORS application included with the download package to see a complete CORS filter declaration and mapping example.

Finally, remember to restart your web server for the installation to take effect.

Important note: By default the CORS Filter will apply a "public access" CORS policy, allowing all cross-site requests through (including credentials/cookies). Leaving the CORS Filter at this setting would actually be fine for most situations as CORS is not about adding server security; its primary intent is to protect the browser - the legitimate JavaScript apps running in it and the user's confidential data, such as cookies.

If you want to modify the default CORS Filter behaviour, proceed to the configuration instructions.