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<@NonNull HttpMethod, @NonNull 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

    • acceptAllInstance

      static @NonNull CorsAuthorizer acceptAllInstance()
      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 fromWhitelistedOrigins(Set) or fromWhitelistAuthorizer(Function) for production systems.

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

    • rejectAllInstance

      static @NonNull CorsAuthorizer rejectAllInstance()
      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

    • fromWhitelistedOrigins

      static @NonNull CorsAuthorizer fromWhitelistedOrigins(@NonNull Set<@NonNull 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 fromWhitelistedOrigins(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

    • fromWhitelistedOrigins

      static @NonNull CorsAuthorizer fromWhitelistedOrigins(@NonNull Set<@NonNull 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 fromWhitelistAuthorizer(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

    • fromWhitelistAuthorizer

      static @NonNull CorsAuthorizer fromWhitelistAuthorizer(@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 fromWhitelistAuthorizer(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

    • fromWhitelistAuthorizer

      static @NonNull CorsAuthorizer fromWhitelistAuthorizer(@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