Package org.apache.catalina.filters

Class CorsFilter

java.lang.Object

jakarta.servlet.GenericFilter

org.apache.catalina.filters.CorsFilter

All Implemented Interfaces:

Filter, FilterConfig, Serializable

public class CorsFilter
extends GenericFilter

A Filter that enable client-side cross-origin requests by implementing W3C's CORS (Cross-Origin Resource Sharing) specification for resources. Each HttpServletRequest request is inspected as per specification, and appropriate response headers are added to HttpServletResponse.

By default, it also sets following request attributes, that help to determine the nature of the request downstream.

• cors.isCorsRequest: Flag to determine if the request is a CORS request. Set to true if a CORS request; false otherwise.
• cors.request.origin: The Origin URL, i.e. the URL of the page from where the request is originated.
• cors.request.type: Type of request. Possible values:
  • SIMPLE: A request which is not preceded by a pre-flight request.
  • ACTUAL: A request which is preceded by a pre-flight request.
  • PRE_FLIGHT: A pre-flight request.
  • NOT_CORS: A normal same-origin request.
  • INVALID_CORS: A cross-origin request which is invalid.
• cors.request.headers: Request headers sent as 'Access-Control-Request-Headers' header, for pre-flight request.

If you extend this class and override one or more of the getXxx() methods, consider whether you also need to override doFilter(ServletRequest, ServletResponse, FilterChain) and add appropriate locking so that the doFilter() method executes with a consistent configuration.

See Also:

• CORS specification
• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static enum	CorsFilter.CORSRequestType	Enumerates varies types of CORS requests.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_ALLOWED_HTTP_HEADERS	By default, following headers are supported: Origin,Accept,X-Requested-With, Content-Type, Access-Control-Request-Method, and Access-Control-Request-Headers.
static final String	DEFAULT_ALLOWED_HTTP_METHODS	By default, following methods are supported: GET, POST, HEAD and OPTIONS.
static final String	DEFAULT_ALLOWED_ORIGINS	By default, no origins are allowed to make requests.
static final String	DEFAULT_DECORATE_REQUEST	By default, request is decorated with CORS attributes.
static final String	DEFAULT_EXPOSED_HEADERS	By default, none of the headers are exposed in response.
static final String	DEFAULT_PREFLIGHT_MAXAGE	By default, time duration to cache pre-flight response is 30 mins.
static final String	DEFAULT_SUPPORTS_CREDENTIALS	By default, support credentials is disabled.
static final String	HTTP_REQUEST_ATTRIBUTE_IS_CORS_REQUEST	Boolean value, suggesting if the request is a CORS request or not.
static final String	HTTP_REQUEST_ATTRIBUTE_ORIGIN	Attribute that contains the origin of the request.
static final String	HTTP_REQUEST_ATTRIBUTE_PREFIX	The prefix to a CORS request attribute.
static final String	HTTP_REQUEST_ATTRIBUTE_REQUEST_HEADERS	Request headers sent as 'Access-Control-Request-Headers' header, for pre-flight request.
static final String	HTTP_REQUEST_ATTRIBUTE_REQUEST_TYPE	Type of CORS request, of type CorsFilter.CORSRequestType.
static final String	PARAM_CORS_ALLOWED_HEADERS	Key to retrieve allowed headers from FilterConfig.
static final String	PARAM_CORS_ALLOWED_METHODS	Key to retrieve allowed methods from FilterConfig.
static final String	PARAM_CORS_ALLOWED_ORIGINS	Key to retrieve allowed origins from FilterConfig.
static final String	PARAM_CORS_EXPOSED_HEADERS	Key to retrieve exposed headers from FilterConfig.
static final String	PARAM_CORS_PREFLIGHT_MAXAGE	Key to retrieve preflight max age from FilterConfig.
static final String	PARAM_CORS_REQUEST_DECORATE	Key to determine if request should be decorated.
static final String	PARAM_CORS_SUPPORT_CREDENTIALS	Key to retrieve support credentials from FilterConfig.
static final String	REQUEST_HEADER_ACCESS_CONTROL_REQUEST_HEADERS	The Access-Control-Request-Headers header indicates which headers will be used in the actual request as part of the preflight request.
static final String	REQUEST_HEADER_ACCESS_CONTROL_REQUEST_METHOD	The Access-Control-Request-Method header indicates which method will be used in the actual request as part of the preflight request.
static final String	REQUEST_HEADER_ORIGIN	The Origin header indicates where the cross-origin request or preflight request originates from.
static final String	RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_CREDENTIALS	The Access-Control-Allow-Credentials header indicates whether the response to request can be exposed when the omit credentials flag is unset.
static final String	RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_HEADERS	The Access-Control-Allow-Headers header indicates, as part of the response to a preflight request, which header field names can be used during the actual request.
static final String	RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_METHODS	The Access-Control-Allow-Methods header indicates, as part of the response to a preflight request, which methods can be used during the actual request.
static final String	RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN	The Access-Control-Allow-Origin header indicates whether a resource can be shared based by returning the value of the Origin request header in the response.
static final String	RESPONSE_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS	The Access-Control-Expose-Headers header indicates which headers are safe to expose to the API of a CORS API specification
static final String	RESPONSE_HEADER_ACCESS_CONTROL_MAX_AGE	The Access-Control-Max-Age header indicates how long the results of a preflight request can be cached in a preflight result cache.
static final Collection<String>	SIMPLE_HTTP_REQUEST_CONTENT_TYPE_VALUES	Collection of media type values for the Content-Type header that will be treated as 'simple'.

Constructor Summary

Constructors

Constructor	Description
CorsFilter()

Method Summary

Modifier and Type	Method	Description
protected CorsFilter.CORSRequestType	checkRequestType(HttpServletRequest request)	Determines the request type.
protected static void	decorateCORSProperties(HttpServletRequest request, CorsFilter.CORSRequestType corsRequestType)	Decorates the HttpServletRequest, with CORS attributes.
void	doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)	The doFilter method of the Filter is called by the container each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain.
Collection<String>	getAllowedHttpHeaders()	Returns a Set of headers support by resource.
Collection<String>	getAllowedHttpMethods()	Returns a Set of HTTP methods that are allowed to make requests.
Collection<String>	getAllowedOrigins()	Returns the Set of allowed origins that are allowed to make requests.
Collection<String>	getExposedHeaders()	Obtain the headers to expose.
long	getPreflightMaxAge()	Returns the preflight response cache time in seconds.
protected void	handlePreflightCORS(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)	Handles CORS pre-flight request.
protected void	handleSimpleCORS(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)	Handles a CORS request of type CorsFilter.CORSRequestType.SIMPLE.
void	init()	Convenience method for sub-classes to save them having to call super.init(config).
boolean	isAnyOriginAllowed()	Determines if any origin is allowed to make CORS request.
boolean	isDecorateRequest()	Should CORS specific attributes be added to the request.
boolean	isSupportsCredentials()	Determines is supports credentials is enabled.
protected static String	join(Collection<String> elements, String joinSeparator)	Joins elements of Set into a string, where each element is separated by the provided separator.

Methods inherited from class jakarta.servlet.GenericFilter

getFilterConfig, getFilterName, getInitParameter, getInitParameterNames, getServletContext, init

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface jakarta.servlet.Filter

destroy

Field Details

RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN

public static final String RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN

The Access-Control-Allow-Origin header indicates whether a resource can be shared based by returning the value of the Origin request header in the response.

See Also:

• Constant Field Values

RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_CREDENTIALS

public static final String RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_CREDENTIALS

The Access-Control-Allow-Credentials header indicates whether the response to request can be exposed when the omit credentials flag is unset. When part of the response to a preflight request it indicates that the actual request can include user credentials.

See Also:

• Constant Field Values

RESPONSE_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS

public static final String RESPONSE_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS

The Access-Control-Expose-Headers header indicates which headers are safe to expose to the API of a CORS API specification

See Also:

• Constant Field Values

RESPONSE_HEADER_ACCESS_CONTROL_MAX_AGE

public static final String RESPONSE_HEADER_ACCESS_CONTROL_MAX_AGE

The Access-Control-Max-Age header indicates how long the results of a preflight request can be cached in a preflight result cache.

See Also:

• Constant Field Values

RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_METHODS

public static final String RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_METHODS

The Access-Control-Allow-Methods header indicates, as part of the response to a preflight request, which methods can be used during the actual request.

See Also:

• Constant Field Values

RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_HEADERS

public static final String RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_HEADERS

The Access-Control-Allow-Headers header indicates, as part of the response to a preflight request, which header field names can be used during the actual request.

See Also:

• Constant Field Values

REQUEST_HEADER_ORIGIN

public static final String REQUEST_HEADER_ORIGIN

The Origin header indicates where the cross-origin request or preflight request originates from.

See Also:

• Constant Field Values

REQUEST_HEADER_ACCESS_CONTROL_REQUEST_METHOD

public static final String REQUEST_HEADER_ACCESS_CONTROL_REQUEST_METHOD

The Access-Control-Request-Method header indicates which method will be used in the actual request as part of the preflight request.

See Also:

• Constant Field Values

REQUEST_HEADER_ACCESS_CONTROL_REQUEST_HEADERS

public static final String REQUEST_HEADER_ACCESS_CONTROL_REQUEST_HEADERS

The Access-Control-Request-Headers header indicates which headers will be used in the actual request as part of the preflight request.

See Also:

• Constant Field Values

HTTP_REQUEST_ATTRIBUTE_PREFIX

public static final String HTTP_REQUEST_ATTRIBUTE_PREFIX

The prefix to a CORS request attribute.

See Also:

• Constant Field Values

HTTP_REQUEST_ATTRIBUTE_ORIGIN

public static final String HTTP_REQUEST_ATTRIBUTE_ORIGIN

Attribute that contains the origin of the request.

See Also:

• Constant Field Values

HTTP_REQUEST_ATTRIBUTE_IS_CORS_REQUEST

public static final String HTTP_REQUEST_ATTRIBUTE_IS_CORS_REQUEST

Boolean value, suggesting if the request is a CORS request or not.

See Also:

• Constant Field Values

HTTP_REQUEST_ATTRIBUTE_REQUEST_TYPE

public static final String HTTP_REQUEST_ATTRIBUTE_REQUEST_TYPE

Type of CORS request, of type CorsFilter.CORSRequestType.

See Also:

• Constant Field Values

HTTP_REQUEST_ATTRIBUTE_REQUEST_HEADERS

public static final String HTTP_REQUEST_ATTRIBUTE_REQUEST_HEADERS

Request headers sent as 'Access-Control-Request-Headers' header, for pre-flight request.

See Also:

• Constant Field Values

SIMPLE_HTTP_REQUEST_CONTENT_TYPE_VALUES

public static final Collection<String> SIMPLE_HTTP_REQUEST_CONTENT_TYPE_VALUES

Collection of media type values for the Content-Type header that will be treated as 'simple'. Note media-type values are compared ignoring parameters and in a case-insensitive manner.

See Also:

• http://www.w3.org/TR/cors/#terminology

DEFAULT_ALLOWED_ORIGINS

public static final String DEFAULT_ALLOWED_ORIGINS

By default, no origins are allowed to make requests.

See Also:

• Constant Field Values

DEFAULT_ALLOWED_HTTP_METHODS

public static final String DEFAULT_ALLOWED_HTTP_METHODS

By default, following methods are supported: GET, POST, HEAD and OPTIONS.

See Also:

• Constant Field Values

DEFAULT_PREFLIGHT_MAXAGE

public static final String DEFAULT_PREFLIGHT_MAXAGE

By default, time duration to cache pre-flight response is 30 mins.

See Also:

• Constant Field Values

DEFAULT_SUPPORTS_CREDENTIALS

public static final String DEFAULT_SUPPORTS_CREDENTIALS

By default, support credentials is disabled.

See Also:

• Constant Field Values

DEFAULT_ALLOWED_HTTP_HEADERS

public static final String DEFAULT_ALLOWED_HTTP_HEADERS

By default, following headers are supported: Origin,Accept,X-Requested-With, Content-Type, Access-Control-Request-Method, and Access-Control-Request-Headers.

See Also:

• Constant Field Values

DEFAULT_EXPOSED_HEADERS

public static final String DEFAULT_EXPOSED_HEADERS

By default, none of the headers are exposed in response.

See Also:

• Constant Field Values

DEFAULT_DECORATE_REQUEST

public static final String DEFAULT_DECORATE_REQUEST

By default, request is decorated with CORS attributes.

See Also:

• Constant Field Values

PARAM_CORS_ALLOWED_ORIGINS

public static final String PARAM_CORS_ALLOWED_ORIGINS

Key to retrieve allowed origins from FilterConfig.

See Also:

• Constant Field Values

PARAM_CORS_SUPPORT_CREDENTIALS

public static final String PARAM_CORS_SUPPORT_CREDENTIALS

Key to retrieve support credentials from FilterConfig.

See Also:

• Constant Field Values

PARAM_CORS_EXPOSED_HEADERS

public static final String PARAM_CORS_EXPOSED_HEADERS

Key to retrieve exposed headers from FilterConfig.

See Also:

• Constant Field Values

PARAM_CORS_ALLOWED_HEADERS

public static final String PARAM_CORS_ALLOWED_HEADERS

Key to retrieve allowed headers from FilterConfig.

See Also:

• Constant Field Values

PARAM_CORS_ALLOWED_METHODS

public static final String PARAM_CORS_ALLOWED_METHODS

Key to retrieve allowed methods from FilterConfig.

See Also:

• Constant Field Values

PARAM_CORS_PREFLIGHT_MAXAGE

public static final String PARAM_CORS_PREFLIGHT_MAXAGE

Key to retrieve preflight max age from FilterConfig.

See Also:

• Constant Field Values

PARAM_CORS_REQUEST_DECORATE

public static final String PARAM_CORS_REQUEST_DECORATE

Key to determine if request should be decorated.

See Also:

• Constant Field Values

Constructor Details

CorsFilter

public CorsFilter()

Method Details

doFilter

public void doFilter(ServletRequest servletRequest,
 ServletResponse servletResponse,
 FilterChain filterChain)
              throws IOException,
ServletException

Description copied from interface: jakarta.servlet.Filter

The doFilter method of the Filter is called by the container each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain. The FilterChain passed in to this method allows the Filter to pass on the request and response to the next entity in the chain.

A typical implementation of this method would follow the following pattern:-
1. Examine the request
2. Optionally wrap the request object with a custom implementation to filter content or headers for input filtering
3. Optionally wrap the response object with a custom implementation to filter content or headers for output filtering
4. a) Either invoke the next entity in the chain using the FilterChain object (chain.doFilter()),
4. b) or not pass on the request/response pair to the next entity in the filter chain to block the request processing
5. Directly set headers on the response after invocation of the next entity in the filter chain.

Parameters:

servletRequest - The request to process

servletResponse - The response associated with the request

filterChain - Provides access to the next filter in the chain for this filter to pass the request and response to for further processing

Throws:

IOException - if an I/O error occurs during this filter's processing of the request

ServletException - if the processing fails for any other reason

init

public void init()
          throws ServletException

Description copied from class: jakarta.servlet.GenericFilter

Convenience method for sub-classes to save them having to call super.init(config). This is a NO-OP by default.

Overrides:

init in class GenericFilter

Throws:

ServletException - If an exception occurs that interrupts the Filter's normal operation

handleSimpleCORS

protected void handleSimpleCORS(HttpServletRequest request,
 HttpServletResponse response,
 FilterChain filterChain)
                         throws IOException,
ServletException

Handles a CORS request of type CorsFilter.CORSRequestType.SIMPLE.

Parameters:

request - The HttpServletRequest object.

response - The HttpServletResponse object.

filterChain - The FilterChain object.

Throws:

IOException - an IO error occurred

ServletException - Servlet error propagation

See Also:

• Simple Cross-Origin Request, Actual Request, and Redirects

handlePreflightCORS

protected void handlePreflightCORS(HttpServletRequest request,
 HttpServletResponse response,
 FilterChain filterChain)
                            throws IOException,
ServletException

Handles CORS pre-flight request.

Parameters:

request - The HttpServletRequest object.

response - The HttpServletResponse object.

filterChain - The FilterChain object.

Throws:

IOException - an IO error occurred

ServletException - Servlet error propagation

decorateCORSProperties

protected static void decorateCORSProperties(HttpServletRequest request,
 CorsFilter.CORSRequestType corsRequestType)

Decorates the HttpServletRequest, with CORS attributes.

• cors.isCorsRequest: Flag to determine if request is a CORS request. Set to true if CORS request; false otherwise.
• cors.request.origin: The Origin URL.
• cors.request.type: Type of request. Values: simple or preflight or not_cors or invalid_cors
• cors.request.headers: Request headers sent as 'Access-Control-Request-Headers' header, for pre-flight request.

Parameters:

request - The HttpServletRequest object.

corsRequestType - The CorsFilter.CORSRequestType object.

join

protected static String join(Collection<String> elements,
 String joinSeparator)

Joins elements of Set into a string, where each element is separated by the provided separator.

Parameters:

elements - The Set containing elements to join together.

joinSeparator - The character to be used for separating elements.

Returns:

The joined String; null if elements Set is null.

checkRequestType

protected CorsFilter.CORSRequestType checkRequestType(HttpServletRequest request)

Determines the request type.

Parameters:

request - The HTTP Servlet request

Returns:

the CORS type

isAnyOriginAllowed

public boolean isAnyOriginAllowed()

Determines if any origin is allowed to make CORS request.

Returns:

true if it's enabled; false otherwise.

getExposedHeaders

public Collection<String> getExposedHeaders()

Obtain the headers to expose.

Returns:

the headers that should be exposed by browser.

isSupportsCredentials

public boolean isSupportsCredentials()

Determines is supports credentials is enabled.

Returns:

true if the use of credentials is supported otherwise false

getPreflightMaxAge

public long getPreflightMaxAge()

Returns the preflight response cache time in seconds.

Returns:

Time to cache in seconds.

getAllowedOrigins

public Collection<String> getAllowedOrigins()

Returns the Set of allowed origins that are allowed to make requests.

Returns:

Set

getAllowedHttpMethods

public Collection<String> getAllowedHttpMethods()

Returns a Set of HTTP methods that are allowed to make requests.

Returns:

Set

getAllowedHttpHeaders

public Collection<String> getAllowedHttpHeaders()

Returns a Set of headers support by resource.

Returns:

Set

isDecorateRequest

public boolean isDecorateRequest()

Should CORS specific attributes be added to the request.

Returns:

true if the request should be decorated, otherwise false