CORS Filter : Configuration

The CORS Filter can be run with no additional configuration in most situations. By default it operates in public mode, informing the browser that:

Requests from any origin are accepted.
The requests may include any author (custom) request headers.
The requests may include credentials such as cookies.

If the default public CORS mode doesn't satisfy your requirements, you can override it by specifying your own configuration. Two configuration formats are supported:

A Java properties text file;
Filter init-params specified in the WEB-INF/web.xml descriptor of the web application.

The CORS Filter applies the following precedence when resolving the configuration properties:

Checks for a cors.configurationFile system property and if set loads the CORS Filter properties file from the referenced location (must be relative to the web application root directory, e.g. /WEB-INF/cors.properties, relative to the classpath, or an absolute file path). Omitted configuration properties are given a sensible default value.
Checks for a filter init-param cors.configurationFile and if set loads the CORS Filter properties file from the referenced location (must be relative to the web application root directory, e.g. /WEB-INF/cors.properties, relative to the classpath, or an absolute file path). Omitted configuration properties are given a sensible defaultvalue.
Checks for CORS configuration properties in the filter init-params section. Omitted configuration properties are given a default value.
Finally, a Java system property matching a CORS configuration property name has ultimate preference.

For example, here is a web.xml snippet to allow CORS requests from the http://example.com origin only:

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

        <init-param>
                <param-name>cors.allowOrigin</param-name>
                <param-value>http://example.com</param-value>
        </init-param>
</filter>

Or as an external properties file, referenced by the cors.configurationFile environment variable or filter init-param:

cors.allowOrigin = http://example.com

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

Configuration parameters

This is a description of the CORS Filter configuration properties.

cors.allowGenericHttpRequests {true|false} defaults to true.
If true generic HTTP requests will be allowed to pass through the filter, else only valid and accepted CORS requests will be allowed (strict CORS filtering).
cors.allowOrigin {"*"|origin-list} defaults to *.
Whitespace-separated list of origins that the CORS filter must allow. Requests from origins not included here will be refused with an HTTP 403 "Forbidden" response. If set to * (asterisk) any origin will be allowed.
Example: Allow any origin:
```
*
```
Example: Allow cross-domain requests from following three origins only:
```
http://example.com http://example.com:8080 https://secure.net
```
cors.allowSubdomains {true|false} defaults to false.
If true the CORS filter will allow requests from any origin which is a subdomain origin of the allowed origins. A subdomain is matched by comparing its scheme and suffix (host name / IP address and optional port number).
Example: If the explicitly allowed origin is http://example.com and subdomains are allowed, all of the following origins will be allowed too:
```
http://www.example.com
http://foo.example.com
http://bar.example.com
```
These non-matching origins, however, will be denied:
```
http://www.example.com:8080
https://foo.example.com
http://myexample.com
```
cors.supportedMethods {method-list} defaults to "GET, POST, HEAD, OPTIONS".
List of the supported HTTP methods. These are advertised through the Access-Control-Allow-Methods header and must also be implemented by the actual CORS web service. Requests for methods not included here will be refused by the CORS filter with an HTTP 405 "Method not allowed" response.
Example: Allow only GET cross-origin requests:
```
GET
```

Example: Allow the methods for a typical RESTful web service:

GET, POST, HEAD, PUT, DELETE

cors.supportedHeaders {"*"|header-list} defaults to *.
The names of the supported author request headers. These are advertised through the Access-Control-Allow-Headers header.
If the configuration property value is set to * (asterisk) any author request header will be allowed. The CORS Filter implements this by simply echoing the requested value back to the browser.

What is an author request header? This any custom header set by the browser JavaScript application through the XMLHttpRequest.setRequestHeader() method.

Example: Inform the browser that the following author request headers are supported:
```
Content-Type, X-Requested-With
```
cors.exposedHeaders {header-list} defaults to empty list.
List of the response headers other than simple response headers that the browser should expose to the author of the cross-domain request through the XMLHttpRequest.getResponseHeader() method. The CORS filter supplies this information through the Access-Control-Expose-Headers header.
Example: Inform the browser that the following custom headers are safe to be exposed to the script that initiated the cross-domain request:
```
X-Custom-1, X-Custom-2
```
cors.supportsCredentials {true|false} defaults to true.
Indicates whether user credentials, such as cookies, HTTP authentication or client-side certificates, are supported. The CORS filter uses this value in constructing the Access-Control-Allow-Credentials header.
cors.maxAge {int} defaults to -1 (unspecified).
Indicates how long the results of a preflight request can be cached by the web browser, in seconds. If -1 unspecified. This information is passed to the browser via the Access-Control-Max-Age header.
Example: Suggest the browser should cache preflight requests for 1 hour:
```
3600
```
cors.tagRequests {true|false} defaults to false (no tagging).
Enables HTTP servlet request tagging to provide CORS information to downstream handlers (filters and/or servlets).
Example: Enable request tagging:
```
true
```

Remember to restart your web application or server after changing the CORS configuration!