org.springframework.web.cors

Class CorsConfiguration

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


  • public class CorsConfiguration
    extends java.lang.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
    See Also:
    CORS spec
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static java.lang.String ALL
      Wildcard representing all origins, methods, or headers.
    • Constructor Summary

      Constructors 
      Constructor and 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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method and Description
      void addAllowedHeader(java.lang.String allowedHeader)
      Add an actual request header to allow.
      void addAllowedMethod(HttpMethod method)
      Add an HTTP method to allow.
      void addAllowedMethod(java.lang.String method)
      Add an HTTP method to allow.
      void addAllowedOrigin(java.lang.String origin)
      Add an origin to allow.
      void addExposedHeader(java.lang.String exposedHeader)
      Add a response header to expose.
      CorsConfiguration applyPermitDefaultValues()
      By default a newly created CorsConfiguration does not permit any cross-origin requests and must be configured explicitly to indicate what should be allowed.
      java.util.List<java.lang.String> checkHeaders(java.util.List<java.lang.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.
      java.util.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.
      java.lang.String checkOrigin(java.lang.String requestOrigin)
      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.
      java.lang.Boolean getAllowCredentials()
      Return the configured allowCredentials flag, or null if none.
      java.util.List<java.lang.String> getAllowedHeaders()
      Return the allowed actual request headers, or null if none.
      java.util.List<java.lang.String> getAllowedMethods()
      Return the allowed HTTP methods, or null in which case only "GET" and "HEAD" allowed.
      java.util.List<java.lang.String> getAllowedOrigins()
      Return the configured origins to allow, or null if none.
      java.util.List<java.lang.String> getExposedHeaders()
      Return the configured response headers to expose, or null if none.
      java.lang.Long getMaxAge()
      Return the configured maxAge value, or null if none.
      void setAllowCredentials(java.lang.Boolean allowCredentials)
      Whether user credentials are supported.
      void setAllowedHeaders(java.util.List<java.lang.String> allowedHeaders)
      Set the list of headers that a pre-flight request can list as allowed for use during an actual request.
      void setAllowedMethods(java.util.List<java.lang.String> allowedMethods)
      Set the HTTP methods to allow, e.g.
      void setAllowedOrigins(java.util.List<java.lang.String> allowedOrigins)
      Set the origins to allow, e.g.
      void setExposedHeaders(java.util.List<java.lang.String> exposedHeaders)
      Set the list of response headers other than simple headers (i.e.
      void setMaxAge(java.lang.Long maxAge)
      Configure how long, in seconds, the response from a pre-flight request can be cached by clients.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • ALL

        public static final java.lang.String ALL
        Wildcard representing all origins, methods, or headers.
        See Also:
        Constant Field Values
    • Constructor Detail

      • 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 Detail

      • setAllowedOrigins

        public void setAllowedOrigins(@Nullable
                                      java.util.List<java.lang.String> allowedOrigins)
        Set the origins to allow, e.g. "http://domain1.com".

        The special value "*" allows all domains.

        By default this is not set.

      • addAllowedOrigin

        public void addAllowedOrigin(java.lang.String origin)
        Add an origin to allow.
      • setAllowedMethods

        public void setAllowedMethods(@Nullable
                                      java.util.List<java.lang.String> allowedMethods)
        Set the HTTP methods to allow, e.g. "GET", "POST", "PUT", etc.

        The special value "*" allows all methods.

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

        By default this is not set.

        Note: CORS checks use values from "Forwarded" (RFC 7239), "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers, if present, in order to reflect the client-originated address. Consider using the ForwardedHeaderFilter in order to choose from a central place whether to extract and use, or to discard such headers. See the Spring Framework reference for more on this filter.

      • addAllowedMethod

        public void addAllowedMethod(HttpMethod method)
        Add an HTTP method to allow.
      • addAllowedMethod

        public void addAllowedMethod(java.lang.String method)
        Add an HTTP method to allow.
      • setAllowedHeaders

        public void setAllowedHeaders(@Nullable
                                      java.util.List<java.lang.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.

        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.

      • addAllowedHeader

        public void addAllowedHeader(java.lang.String allowedHeader)
        Add an actual request header to allow.
      • setExposedHeaders

        public void setExposedHeaders(@Nullable
                                      java.util.List<java.lang.String> exposedHeaders)
        Set the list of response headers other than simple headers (i.e. Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, or Pragma) that an actual response might have and can be exposed.

        Note that "*" is not a valid exposed header value.

        By default this is not set.

      • addExposedHeader

        public void addExposedHeader(java.lang.String exposedHeader)
        Add a response header to expose.

        Note that "*" is not a valid exposed header value.

      • setAllowCredentials

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

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

      • setMaxAge

        public void setMaxAge(@Nullable
                              java.lang.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 java.lang.Long getMaxAge()
        Return the configured maxAge value, or null if none.
        See Also:
        setMaxAge(Long)
      • applyPermitDefaultValues

        public CorsConfiguration applyPermitDefaultValues()
        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 this method to flip the initialization model to start with open defaults that permit all cross-origin requests for GET, HEAD, and POST requests. Note however that this method will not override any existing values already set.

        The following defaults are applied if not already set:

        • Allow all origins.
        • Allow "simple" methods GET, HEAD and POST.
        • Allow all headers.
        • Set max age to 1800 seconds (30 minutes).
      • combine

        @Nullable
        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"], but keep in mind that combining ["GET", "POST"] with ["*"] results in ["*"].

        Notice that default permit values set by applyPermitDefaultValues() are overridden by any value explicitly defined.

        Returns:
        the combined CorsConfiguration or this configuration if the supplied configuration is null
      • checkOrigin

        @Nullable
        public java.lang.String checkOrigin(@Nullable
                                                      java.lang.String requestOrigin)
        Check the origin of the request against the configured allowed origins.
        Parameters:
        requestOrigin - 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 java.util.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 java.util.List<java.lang.String> checkHeaders(@Nullable
                                                                       java.util.List<java.lang.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