View Javadoc

1   package com.atlassian.plugins.rest.common.security.descriptor;
2   
3   import java.util.Set;
4   
5   /**
6    * Defaults to apply for Cross-Origin Resource Sharing when the
7    * {@link com.atlassian.plugins.rest.common.security.AllowCors}
8    * annotation is used.
9    *
10   * @since 2.6
11   */
12  public interface CorsDefaults
13  {
14      /**
15       * Given an origin which has already passed an {@link #allowsOrigin(String)} check, tests that origin to determine
16       * if it is whitelisted for making a <i>credentialed</i> CORS request, on behalf of a specific user.
17       *
18       * @param uri The origin that has already been allowed.  Will never be null
19       * @return True if the origin allows origin requests that contain credentials such as cookies or HTTP auth
20       * @throws IllegalArgumentException Thrown if the uri is not a valid origin or is null.
21       */
22      boolean allowsCredentials(String uri) throws IllegalArgumentException;
23  
24      /**
25       * Tests the provided origin to determine if it is whitelisted for making <i>non-credentialed</i> CORS requests.
26       * 
27       * @param uri The origin.  Will never be null
28       * @return True if the origin provided matches any values in the whitelist
29       * @throws IllegalArgumentException Thrown if the uri is not a valid URL or is null.
30       */
31      boolean allowsOrigin(String uri) throws IllegalArgumentException;
32  
33      /**
34       * For the provided origin, returns a set of HTTP headers which the browser may include when making a request.
35       * These headers are only relevant for a CORS preflight check, which is made for non-simple HTTP requests.
36       *
37       * @param uri the origin that has already been allowed.  Will never be null
38       * @return set of allowed non-simple (see spec) HTTP headers.  Must not be null
39       * @throws IllegalArgumentException Thrown if the uri is not a valid origin or is null.
40       * @see com.atlassian.plugins.rest.common.security.CorsHeaders#ACCESS_CONTROL_ALLOW_HEADERS
41       */
42      Set<String> getAllowedRequestHeaders(String uri) throws IllegalArgumentException;
43  
44      /**
45       * For the provided origin, returns a set of HTTP headers which the browser's CORS support can forward on to the
46       * underlying request. For resources accessed via CORS which have non-simple headers they return, only those
47       * headers which are allowed this set will actually be exposed by the browser after the request completes. These
48       * headers are only relevant for simple HTTP requests, which do not require a CORS preflight check.
49       *
50       * @param uri the origin that has already been allowed.  Will never be null
51       * @return set of allowed simple (see spec) HTTP headers.  Must not be null
52       * @throws IllegalArgumentException Thrown if the uri is not a valid origin or is null.
53       * @see com.atlassian.plugins.rest.common.security.CorsHeaders#ACCESS_CONTROL_EXPOSE_HEADERS
54       */
55      Set<String> getAllowedResponseHeaders(String uri) throws IllegalArgumentException;
56  }