Package org.springframework.web.cors

# Class CorsConfiguration

java.lang.Object
org.springframework.web.cors.CorsConfiguration

public class CorsConfiguration extends Object
A container for CORS configuration along with methods to check against the actual origin, HTTP methods, and headers of a given request.

By default a newly created `CorsConfiguration` does not permit any cross-origin requests and must be configured explicitly to indicate what should be allowed. Use `applyPermitDefaultValues()` to flip the initialization model to start with open defaults that permit all cross-origin requests for GET, HEAD, and POST requests.

Since:
  4.2
Author:
  Sebastien Deleuze, Rossen Stoyanchev, Juergen Hoeller, Sam Brannen, Ruslan Akhundov
See Also:
  - CORS spec

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`ALL`
Wildcard representing all origins, methods, or headers.

## Constructor Summary

Constructors
Constructor
Description
`CorsConfiguration()`
Construct a new `CorsConfiguration` instance with no cross-origin requests allowed for any origin by default.
`CorsConfiguration(CorsConfiguration other)`
Construct a new `CorsConfiguration` instance by copying all values from the supplied `CorsConfiguration`.

## Method Summary

Modifier and Type
Method
Description
`void`
`addAllowedHeader(String allowedHeader)`
Variant of `setAllowedHeaders(List)` for adding one allowed header at a time.
`void`
`addAllowedMethod(String method)`
Variant of `setAllowedMethods(java.util.List<java.lang.String>)` for adding one allowed method at a time.
`void`
`addAllowedMethod(HttpMethod method)`
Variant of `setAllowedMethods(java.util.List<java.lang.String>)` for adding one allowed method at a time.
`void`
`addAllowedOrigin(String origin)`
Variant of `setAllowedOrigins(java.util.List<java.lang.String>)` for adding one origin at a time.
`void`
`addAllowedOriginPattern(String originPattern)`
Variant of `setAllowedOriginPatterns(java.util.List<java.lang.String>)` for adding one origin at a time.
`void`
`addExposedHeader(String exposedHeader)`
Variant of `setExposedHeaders(java.util.List<java.lang.String>)` for adding one exposed header at a time.
`CorsConfiguration`
`applyPermitDefaultValues()`
By default `CorsConfiguration` does not permit any cross-origin requests and must be configured explicitly.
`List<String>`
`checkHeaders(List<String> requestHeaders)`
Check the supplied request headers (or the headers listed in the `Access-Control-Request-Headers` of a pre-flight request) against the configured allowed headers.
`List<HttpMethod>`
`checkHttpMethod(HttpMethod requestMethod)`
Check the HTTP request method (or the method from the `Access-Control-Request-Method` header on a pre-flight request) against the configured allowed methods.
`String`
`checkOrigin(String origin)`
Check the origin of the request against the configured allowed origins.
`CorsConfiguration`
`combine(CorsConfiguration other)`
Combine the non-null properties of the supplied `CorsConfiguration` with this one.
`Boolean`
`getAllowCredentials()`
Return the configured `allowCredentials` flag, or `null` if none.
`List<String>`
`getAllowedHeaders()`
Return the allowed actual request headers, or `null` if none.
`List<String>`
`getAllowedMethods()`
Return the allowed HTTP methods, or `null` in which case only `"GET"` and `"HEAD"` allowed.
`List<String>`
`getAllowedOriginPatterns()`
Return the configured origins patterns to allow, or `null` if none.
`List<String>`
`getAllowedOrigins()`
Return the configured origins to allow, or `null` if none.
`Boolean`
`getAllowPrivateNetwork()`
Return the configured `allowPrivateNetwork` flag, or `null` if none.
`List<String>`
`getExposedHeaders()`
Return the configured response headers to expose, or `null` if none.
`Long`
`getMaxAge()`
Return the configured `maxAge` value, or `null` if none.
`void`
`setAllowCredentials(Boolean allowCredentials)`
Whether user credentials are supported.
`void`
`setAllowedHeaders(List<String> allowedHeaders)`
Set the list of headers that a pre-flight request can list as allowed for use during an actual request.
`void`
`setAllowedMethods(List<String> allowedMethods)`
Set the HTTP methods to allow, for example, `"GET"`, `"POST"`, `"PUT"`, etc.
`CorsConfiguration`
`setAllowedOriginPatterns(List<String> allowedOriginPatterns)`
Alternative to `setAllowedOrigins(java.util.List<java.lang.String>)` that supports more flexible origins patterns with "*" anywhere in the host name in addition to port lists.
`void`
`setAllowedOrigins(List<String> origins)`
A list of origins for which cross-origin requests are allowed where each value may be one of the following: a specific domain, for example, `"https://domain1.com"` comma-delimited list of specific domains, for example, `"https://a1.com,https://a2.com"`; this is convenient when a value is resolved through a property placeholder, for example, `"${origin}"`; note that such placeholders must be resolved externally.
`void`
`setAllowPrivateNetwork(Boolean allowPrivateNetwork)`
Whether private network access is supported for user-agents restricting such access by default.
`void`
`setExposedHeaders(List<String> exposedHeaders)`
Set the list of response headers that an actual response might have and can be exposed to the client.
`void`
`setMaxAge(Long maxAge)`
Configure how long, in seconds, the response from a pre-flight request can be cached by clients.
`void`
`setMaxAge(Duration maxAge)`
Configure how long, as a duration, the response from a pre-flight request can be cached by clients.
`void`
`validateAllowCredentials()`
Validate that when `allowCredentials` is `true`, `allowedOrigins` does not contain the special value `"*"` since in that case the "Access-Control-Allow-Origin" cannot be set to `"*"`.
`void`
`validateAllowPrivateNetwork()`
Validate that when `allowPrivateNetwork` is `true`, `allowedOrigins` does not contain the special value `"*"` since this is insecure.

### Methods inherited from class java.lang.Object

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

## Field Details

### ALL

public static final String ALL
Wildcard representing all origins, methods, or headers.

See Also:
  - Constant Field Values

## Constructor Details

### CorsConfiguration

public CorsConfiguration()
Construct a new `CorsConfiguration` instance with no cross-origin requests allowed for any origin by default.

See Also:
  - `applyPermitDefaultValues()`

### CorsConfiguration

public CorsConfiguration(CorsConfiguration other)
Construct a new `CorsConfiguration` instance by copying all values from the supplied `CorsConfiguration`.

## Method Details

### setAllowedOrigins

public void setAllowedOrigins(@Nullable List<String> origins)
A list of origins for which cross-origin requests are allowed where each value may be one of the following:

- a specific domain, for example, `"https://domain1.com"`
- comma-delimited list of specific domains, for example, `"https://a1.com,https://a2.com"`; this is convenient when a value is resolved through a property placeholder, for example, `"${origin}"`; note that such placeholders must be resolved externally.
- the CORS defined special value `"*"` for all origins

For matched pre-flight and actual requests the `Access-Control-Allow-Origin` response header is set either to the matched domain value or to `"*"`. Keep in mind however that the CORS spec does not allow `"*"` when `allowCredentials` is set to `true`, and does not recommend `"*"` when `allowPrivateNetwork` is set to `true`. As a consequence, those combinations are rejected in favor of using `allowedOriginPatterns` instead.

By default this is not set which means that no origins are allowed. However, an instance of this class is often initialized further, for example, for `@CrossOrigin`, via `applyPermitDefaultValues()`.

### getAllowedOrigins

@Nullable public List<String> getAllowedOrigins()
Return the configured origins to allow, or `null` if none.

### addAllowedOrigin

public void addAllowedOrigin(@Nullable String origin)
Variant of `setAllowedOrigins(java.util.List<java.lang.String>)` for adding one origin at a time.

### setAllowedOriginPatterns

public CorsConfiguration setAllowedOriginPatterns(@Nullable List<String> allowedOriginPatterns)
Alternative to `setAllowedOrigins(java.util.List<java.lang.String>)` that supports more flexible origins patterns with "*" anywhere in the host name in addition to port lists. Examples:

- https://*.domain1.com -- domains ending with domain1.com
- https://*.domain1.com:[8080,8081] -- domains ending with domain1.com on port 8080 or port 8081
- https://*.domain1.com:[*] -- domains ending with domain1.com on any port, including the default port
- comma-delimited list of patters, for example, `"https://*.a1.com,https://*.a2.com"`; this is convenient when a value is resolved through a property placeholder, for example, `"${origin}"`; note that such placeholders must be resolved externally.

In contrast to `allowedOrigins` which only supports "*" and cannot be used with `allowCredentials` or `allowPrivateNetwork`, when an `allowedOriginPattern` is matched, the `Access-Control-Allow-Origin` response header is set to the matched origin and not to `"*"` nor to the pattern. Therefore, `allowedOriginPatterns` can be used in combination with `setAllowCredentials(java.lang.Boolean)` and `setAllowPrivateNetwork(java.lang.Boolean)` set to `true`.

By default this is not set.

Since:
  5.3

### getAllowedOriginPatterns

@Nullable public List<String> getAllowedOriginPatterns()
Return the configured origins patterns to allow, or `null` if none.

Since:
  5.3

### addAllowedOriginPattern

public void addAllowedOriginPattern(@Nullable String originPattern)
Variant of `setAllowedOriginPatterns(java.util.List<java.lang.String>)` for adding one origin at a time.

Since:
  5.3

### setAllowedMethods

public void setAllowedMethods(@Nullable List<String> allowedMethods)
Set the HTTP methods to allow, for example, `"GET"`, `"POST"`, `"PUT"`, etc. The special value `"*"` allows all methods.

`Access-Control-Allow-Methods` response header is set either to the configured method or to `"*"`. Keep in mind however that the CORS spec does not allow `"*"` when `allowCredentials` is set to `true`, that combination is handled by copying the method specified in the CORS preflight request.

If not set, only `"GET"` and `"HEAD"` are allowed.

By default, this is not set.

### getAllowedMethods

@Nullable public List<String> getAllowedMethods()
Return the allowed HTTP methods, or `null` in which case only `"GET"` and `"HEAD"` allowed.

See Also:
  - `setAllowedMethods(List)`
  - `addAllowedMethod(HttpMethod)`
  - `addAllowedMethod(String)`

### addAllowedMethod

public void addAllowedMethod(HttpMethod method)
Variant of `setAllowedMethods(java.util.List<java.lang.String>)` for adding one allowed method at a time.

### addAllowedMethod

public void addAllowedMethod(String method)
Variant of `setAllowedMethods(java.util.List<java.lang.String>)` for adding one allowed method at a time.

### setAllowedHeaders

public void setAllowedHeaders(@Nullable List<String> allowedHeaders)
Set the list of headers that a pre-flight request can list as allowed for use during an actual request. The special value `"*"` allows actual requests to send any header.

`Access-Control-Allow-Headers` response header is set either to the configured list of headers or to `"*"`. Keep in mind however that the CORS spec does not allow `"*"` when `allowCredentials` is set to `true`, that combination is handled by copying the headers specified in the CORS preflight request.

A header name is not required to be listed if it is one of: `Cache-Control`, `Content-Language`, `Expires`, `Last-Modified`, or `Pragma`.

By default this is not set.

### getAllowedHeaders

@Nullable public List<String> getAllowedHeaders()
Return the allowed actual request headers, or `null` if none.

See Also:
  - `addAllowedHeader(String)`
  - `setAllowedHeaders(List)`

### addAllowedHeader

public void addAllowedHeader(String allowedHeader)
Variant of `setAllowedHeaders(List)` for adding one allowed header at a time.

### setExposedHeaders

public void setExposedHeaders(@Nullable List<String> exposedHeaders)
Set the list of response headers that an actual response might have and can be exposed to the client. The special value `"*"` allows all headers to be exposed.

`Access-Control-Expose-Headers` response header is set either to the configured list of headers or to `"*"`. While the CORS spec does not allow `"*"` when `Access-Control-Allow-Credentials` is set to `true`, most browsers support it and the response headers are not all available during the CORS processing, so as a consequence `"*"` is the header value used when specified regardless of the value of the `allowCredentials` property.

A header name is not required to be listed if it is one of: `Cache-Control`, `Content-Language`, `Expires`, `Last-Modified`, or `Pragma`.

By default this is not set.

### getExposedHeaders

@Nullable public List<String> getExposedHeaders()
Return the configured response headers to expose, or `null` if none.

See Also:
  - `addExposedHeader(String)`
  - `setExposedHeaders(List)`

### addExposedHeader

public void addExposedHeader(String exposedHeader)
Variant of `setExposedHeaders(java.util.List<java.lang.String>)` for adding one exposed header at a time.

### setAllowCredentials

public void setAllowCredentials(@Nullable Boolean allowCredentials)
Whether user credentials are supported.

Setting this property has an impact on how `origins`, `originPatterns`, `allowedMethods` and `allowedHeaders` are processed, see related API documentation for more details.

NOTE: Be aware that this option establishes a high level of trust with the configured domains and also increases the surface attack of the web application by exposing sensitive user-specific information such as cookies and CSRF tokens.

By default, this is not set (i.e. user credentials are not supported).

### getAllowCredentials

@Nullable public Boolean getAllowCredentials()
Return the configured `allowCredentials` flag, or `null` if none.

See Also:
  - `setAllowCredentials(Boolean)`

### setAllowPrivateNetwork

public void setAllowPrivateNetwork(@Nullable Boolean allowPrivateNetwork)
Whether private network access is supported for user-agents restricting such access by default.

Private network requests are requests whose target server's IP address is more private than that from which the request initiator was fetched. For example, a request from a public website (https://example.com) to a private website (https://router.local), or a request from a private website to localhost.

Setting this property has an impact on how `origins` and `originPatterns` are processed, see related API documentation for more details.

By default, this is not set (i.e. private network access is not supported).

Since:
  5.3.32
See Also:
  - Private network access specifications

### getAllowPrivateNetwork

@Nullable public Boolean getAllowPrivateNetwork()
Return the configured `allowPrivateNetwork` flag, or `null` if none.

Since:
  5.3.32
See Also:
  - `setAllowPrivateNetwork(Boolean)`

### setMaxAge

public void setMaxAge(Duration maxAge)
Configure how long, as a duration, the response from a pre-flight request can be cached by clients.

Since:
  5.2
See Also:
  - `setMaxAge(Long)`

### setMaxAge

public void setMaxAge(@Nullable Long maxAge)
Configure how long, in seconds, the response from a pre-flight request can be cached by clients.

By default this is not set.

### getMaxAge

@Nullable public Long getMaxAge()
Return the configured `maxAge` value, or `null` if none.

See Also:
  - `setMaxAge(Long)`

### applyPermitDefaultValues

public CorsConfiguration applyPermitDefaultValues()
By default `CorsConfiguration` does not permit any cross-origin requests and must be configured explicitly. Use this method to switch to defaults that permit all cross-origin requests for GET, HEAD, and POST, but not overriding any values that have already been set.

The following defaults are applied for values that are not set:

- Allow all origins with the special value `"*"` defined in the CORS spec. This is set only if neither `origins` nor `originPatterns` are already set.
- Allow "simple" methods `GET`, `HEAD` and `POST`.
- Allow all headers.
- Set max age to 1800 seconds (30 minutes).

### validateAllowCredentials

public void validateAllowCredentials()
Validate that when `allowCredentials` is `true`, `allowedOrigins` does not contain the special value `"*"` since in that case the "Access-Control-Allow-Origin" cannot be set to `"*"`.

Throws:
  `IllegalArgumentException` - if the validation fails
Since:
  5.3

### validateAllowPrivateNetwork

public void validateAllowPrivateNetwork()
Validate that when `allowPrivateNetwork` is `true`, `allowedOrigins` does not contain the special value `"*"` since this is insecure.

Throws:
  `IllegalArgumentException` - if the validation fails
Since:
  5.3.32

### combine

public CorsConfiguration combine(@Nullable CorsConfiguration other)
Combine the non-null properties of the supplied `CorsConfiguration` with this one.

When combining single values like `allowCredentials` or `maxAge`, `this` properties are overridden by non-null `other` properties if any.

Combining lists like `allowedOrigins`, `allowedMethods`, `allowedHeaders` or `exposedHeaders` is done in an additive way. For example, combining `["GET", "POST"]` with `["PATCH"]` results in `["GET", "POST", "PATCH"]`. However, combining `["GET", "POST"]` with `["*"]` results in `["*"]`. Note also that default permit values set by `applyPermitDefaultValues()` are overridden by any explicitly defined values.

Returns:
  the combined `CorsConfiguration`, or `this` configuration if the supplied configuration is `null`

### checkOrigin

@Nullable public String checkOrigin(@Nullable String origin)
Check the origin of the request against the configured allowed origins.

Parameters:
  `origin` - the origin to check
Returns:
  the origin to use for the response, or `null` which means the request origin is not allowed

### checkHttpMethod

@Nullable public List<HttpMethod> checkHttpMethod(@Nullable HttpMethod requestMethod)
Check the HTTP request method (or the method from the `Access-Control-Request-Method` header on a pre-flight request) against the configured allowed methods.

Parameters:
  `requestMethod` - the HTTP request method to check
Returns:
  the list of HTTP methods to list in the response of a pre-flight request, or `null` if the supplied `requestMethod` is not allowed

### checkHeaders

@Nullable public List<String> checkHeaders(@Nullable List<String> requestHeaders)
Check the supplied request headers (or the headers listed in the `Access-Control-Request-Headers` of a pre-flight request) against the configured allowed headers.

Parameters:
  `requestHeaders` - the request headers to check
Returns:
  the list of allowed headers to list in the response of a pre-flight request, or `null` if none of the supplied request headers is allowed