001/*
002 * Copyright 2002-2020 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.web.bind.annotation;
018
019import java.lang.annotation.Documented;
020import java.lang.annotation.ElementType;
021import java.lang.annotation.Retention;
022import java.lang.annotation.RetentionPolicy;
023import java.lang.annotation.Target;
024
025import org.springframework.core.annotation.AliasFor;
026import org.springframework.web.cors.CorsConfiguration;
027
028/**
029 * Annotation for permitting cross-origin requests on specific handler classes
030 * and/or handler methods. Processed if an appropriate {@code HandlerMapping}
031 * is configured.
032 *
033 * <p>Both Spring Web MVC and Spring WebFlux support this annotation through the
034 * {@code RequestMappingHandlerMapping} in their respective modules. The values
035 * from each type and method level pair of annotations are added to a
036 * {@link CorsConfiguration} and then default values are applied via
037 * {@link CorsConfiguration#applyPermitDefaultValues()}.
038 *
039 * <p>The rules for combining global and local configuration are generally
040 * additive -- e.g. all global and all local origins. For those attributes
041 * where only a single value can be accepted such as {@code allowCredentials}
042 * and {@code maxAge}, the local overrides the global value.
043 * See {@link CorsConfiguration#combine(CorsConfiguration)} for more details.
044 *
045 * @author Russell Allen
046 * @author Sebastien Deleuze
047 * @author Sam Brannen
048 * @since 4.2
049 */
050@Target({ElementType.TYPE, ElementType.METHOD})
051@Retention(RetentionPolicy.RUNTIME)
052@Documented
053public @interface CrossOrigin {
054
055        /** @deprecated as of Spring 5.0, in favor of {@link CorsConfiguration#applyPermitDefaultValues} */
056        @Deprecated
057        String[] DEFAULT_ORIGINS = {"*"};
058
059        /** @deprecated as of Spring 5.0, in favor of {@link CorsConfiguration#applyPermitDefaultValues} */
060        @Deprecated
061        String[] DEFAULT_ALLOWED_HEADERS = {"*"};
062
063        /** @deprecated as of Spring 5.0, in favor of {@link CorsConfiguration#applyPermitDefaultValues} */
064        @Deprecated
065        boolean DEFAULT_ALLOW_CREDENTIALS = false;
066
067        /** @deprecated as of Spring 5.0, in favor of {@link CorsConfiguration#applyPermitDefaultValues} */
068        @Deprecated
069        long DEFAULT_MAX_AGE = 1800;
070
071
072        /**
073         * Alias for {@link #origins}.
074         */
075        @AliasFor("origins")
076        String[] value() default {};
077
078        /**
079         * The list of allowed origins that be specific origins, e.g.
080         * {@code "https://domain1.com"}, or {@code "*"} for all origins.
081         * <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
082         * response header of preflight actual CORS requests.
083         * <p>By default all origins are allowed.
084         * <p><strong>Note:</strong> CORS checks use values from "Forwarded"
085         * (<a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a>),
086         * "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
087         * if present, in order to reflect the client-originated address.
088         * Consider using the {@code ForwardedHeaderFilter} in order to choose from a
089         * central place whether to extract and use, or to discard such headers.
090         * See the Spring Framework reference for more on this filter.
091         * @see #value
092         */
093        @AliasFor("value")
094        String[] origins() default {};
095
096        /**
097         * The list of request headers that are permitted in actual requests,
098         * possibly {@code "*"}  to allow all headers.
099         * <p>Allowed headers are listed in the {@code Access-Control-Allow-Headers}
100         * response header of preflight requests.
101         * <p>A header name is not required to be listed if it is one of:
102         * {@code Cache-Control}, {@code Content-Language}, {@code Expires},
103         * {@code Last-Modified}, or {@code Pragma} as per the CORS spec.
104         * <p>By default all requested headers are allowed.
105         */
106        String[] allowedHeaders() default {};
107
108        /**
109         * The List of response headers that the user-agent will allow the client
110         * to access on an actual response, other than "simple" headers, i.e.
111         * {@code Cache-Control}, {@code Content-Language}, {@code Content-Type},
112         * {@code Expires}, {@code Last-Modified}, or {@code Pragma},
113         * <p>Exposed headers are listed in the {@code Access-Control-Expose-Headers}
114         * response header of actual CORS requests.
115         * <p>The special value {@code "*"} allows all headers to be exposed for
116         * non-credentialed requests.
117         * <p>By default no headers are listed as exposed.
118         */
119        String[] exposedHeaders() default {};
120
121        /**
122         * The list of supported HTTP request methods.
123         * <p>By default the supported methods are the same as the ones to which a
124         * controller method is mapped.
125         */
126        RequestMethod[] methods() default {};
127
128        /**
129         * Whether the browser should send credentials, such as cookies along with
130         * cross domain requests, to the annotated endpoint. The configured value is
131         * set on the {@code Access-Control-Allow-Credentials} response header of
132         * preflight requests.
133         * <p><strong>NOTE:</strong> Be aware that this option establishes a high
134         * level of trust with the configured domains and also increases the surface
135         * attack of the web application by exposing sensitive user-specific
136         * information such as cookies and CSRF tokens.
137         * <p>By default this is not set in which case the
138         * {@code Access-Control-Allow-Credentials} header is also not set and
139         * credentials are therefore not allowed.
140         */
141        String allowCredentials() default "";
142
143        /**
144         * The maximum age (in seconds) of the cache duration for preflight responses.
145         * <p>This property controls the value of the {@code Access-Control-Max-Age}
146         * response header of preflight requests.
147         * <p>Setting this to a reasonable value can reduce the number of preflight
148         * request/response interactions required by the browser.
149         * A negative value means <em>undefined</em>.
150         * <p>By default this is set to {@code 1800} seconds (30 minutes).
151         */
152        long maxAge() default -1;
153
154}