Interface CorsAuthorizer

public interface CorsAuthorizer
Contract for types that authorize CORS requests.

Standard threadsafe implementations can be acquired via these factory methods:

See https://www.soklet.com/docs/cors for detailed documentation.
Author:
Mark Allen

  • Method Details

    • authorize

      @Nonnull Optional<CorsResponse> authorize(@Nonnull Request request, @Nonnull Cors cors)
      Authorizes a non-preflight CORS request.
      Parameters:
      request - the request to authorize
      cors - the CORS data provided in the request
      Returns:
      a CorsResponse if authorized, or Optional.empty() if not authorized

    • authorizePreflight

      @Nonnull Optional<CorsPreflightResponse> authorizePreflight(@Nonnull Request request, @Nonnull CorsPreflight corsPreflight, @Nonnull Map<HttpMethod, ResourceMethod> availableResourceMethodsByHttpMethod)
      Authorizes a CORS preflight request.
      Parameters:
      request - the preflight request to authorize
      corsPreflight - the CORS preflight data provided in the request
      availableResourceMethodsByHttpMethod - Resource Methods that are available to serve requests according to parameters specified by the preflight data
      Returns:
      a CorsPreflightResponse if authorized, or Optional.empty() if not authorized

    • withAcceptAllPolicy

      @Nonnull static CorsAuthorizer withAcceptAllPolicy()
      Acquires a threadsafe CorsAuthorizer configured to permit all cross-domain requests regardless of Origin.

      The returned instance is guaranteed to be a JVM-wide singleton.

      Note: the returned instance is generally unsafe for production - prefer withWhitelistedOrigins(Set) or withWhitelistAuthorizer(Function) for production systems.

      Returns:
      a CorsAuthorizer configured to permit all cross-domain requests

    • withRejectAllPolicy

      @Nonnull static CorsAuthorizer withRejectAllPolicy()
      Acquires a threadsafe CorsAuthorizer configured to reject all cross-domain requests regardless of Origin.

      The returned instance is guaranteed to be a JVM-wide singleton.

      Returns:
      a CorsAuthorizer configured to reject all cross-domain requests

    • withWhitelistedOrigins

      @Nonnull static CorsAuthorizer withWhitelistedOrigins(@Nonnull Set<String> whitelistedOrigins)
      Acquires a threadsafe CorsAuthorizer configured to accept only those cross-domain requests whose Origin matches a value in the provided set of whitelistedOrigins.

      The returned CorsAuthorizer will set Access-Control-Allow-Credentials header to true. This behavior can be customized via withWhitelistedOrigins(Set, Function).

      Callers should not rely on reference identity; this method may return a new or cached instance.

      Parameters:
      whitelistedOrigins - the set of whitelisted origins
      Returns:
      a credentials-allowed CorsAuthorizer configured to accept only the specified whitelistedOrigins

    • withWhitelistedOrigins

      @Nonnull static CorsAuthorizer withWhitelistedOrigins(@Nonnull Set<String> whitelistedOrigins, @Nonnull Function<String,Boolean> allowCredentialsResolver)
      Acquires a threadsafe CorsAuthorizer configured to accept only those cross-domain requests whose Origin matches a value in the provided set of whitelistedOrigins.

      The provided allowCredentialsResolver is used to control the value of Access-Control-Allow-Credentials: it's a function which takes a normalized Origin as input and should return true if clients are permitted to include credentials in cross-origin HTTP requests and false otherwise.

      The returned CorsAuthorizer will omit the Access-Control-Allow-Credentials response header to reduce CSRF attack surface area. This behavior can be customized via withWhitelistAuthorizer(Function, Function).

      Callers should not rely on reference identity; this method may return a new or cached instance.

      Parameters:
      whitelistedOrigins - the set of whitelisted origins
      allowCredentialsResolver - function which takes a normalized Origin as input and should return true if clients are permitted to include credentials in cross-origin HTTP requests and false otherwise
      Returns:
      a CorsAuthorizer configured to accept only the specified whitelistedOrigins, with allowCredentialsResolver dictating whether credentials are allowed

    • withWhitelistAuthorizer

      @Nonnull static CorsAuthorizer withWhitelistAuthorizer(@Nonnull Function<String,Boolean> whitelistAuthorizer)
      Acquires a threadsafe CorsAuthorizer configured to accept only those cross-domain requests whose Origin is allowed by the provided whitelistAuthorizer function.

      The whitelistAuthorizer function should return true if the supplied Origin is acceptable and false otherwise.

      The returned CorsAuthorizer will omit the Access-Control-Allow-Credentials response header to reduce CSRF attack surface area. This behavior can be customized via withWhitelistAuthorizer(Function, Function).

      Callers should not rely on reference identity; this method may return a new or cached instance.

      Parameters:
      whitelistAuthorizer - a function that returns true if the input is a whitelisted origin and false otherwise
      Returns:
      a credentials-allowed CorsAuthorizer configured to accept only the origins permitted by whitelistAuthorizer

    • withWhitelistAuthorizer

      @Nonnull static CorsAuthorizer withWhitelistAuthorizer(@Nonnull Function<String,Boolean> whitelistAuthorizer, @Nonnull Function<String,Boolean> allowCredentialsResolver)
      Acquires a threadsafe CorsAuthorizer configured to accept only those cross-domain requests whose Origin is allowed by the provided whitelistAuthorizer function.

      The whitelistAuthorizer function should return true if the supplied Origin is acceptable and false otherwise.

      The provided allowCredentialsResolver is used to control the value of Access-Control-Allow-Credentials: it's a function which takes a normalized Origin as input and should return true if clients are permitted to include credentials in cross-origin HTTP requests and false otherwise.

      Callers should not rely on reference identity; this method may return a new or cached instance.

      Parameters:
      whitelistAuthorizer - a function that returns true if the input is a whitelisted origin and false otherwise
      allowCredentialsResolver - function which takes a normalized Origin as input and should return true if clients are permitted to include credentials in cross-origin HTTP requests and false otherwise
      Returns:
      a CorsAuthorizer configured to accept only the origins permitted by whitelistAuthorizer, with allowCredentialsResolver dictating whether credentials are allowed