CORS Filter : Configuration

The CORS Filter can be run with no additional configuration in most situations. By default it operates in public mode: It informs the browser that requests from any origin are accepted and that they may include optional credentials such as cookies.

The default CORS behaviour can be overridden by adding one or more explicit init-param elements to the filter declaration in the WEB-INF/web.xml descriptor file.

For example, 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>

Have a 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.

Filter init parameters

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 * 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.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 empty list.
The names of the supported author request headers. These are advertised through the Access-Control-Allow-Headers header.
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
```

Remember to restart your web server after making CORS configuration changes!