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}