Package com.spotfire.server.security

Interface CustomWebAuthenticator

public interface CustomWebAuthenticator
Service-provider interface for web-based custom authentication flows (based on OAuth2 or similar). The authenticateWeb(WebAuthenticationContext) method gets invoked for requests to the return endpoint (see CustomWebAuthenticatorInitContext.getReturnEndpoint()).

A custom web authenticator is an implementation of this interface.

There are several alternatives to implementing this interface:

  • If the user identity can be retrieved from an HTTP header or similar but the built-in functionality for retrieving such isn't sufficient, for example if the header contains a token that must be validated against some external service to establish the user identity, then a CustomAuthenticator is a suitable option.
  • If the user identity can be established through some built-in authentication method and all that is needed is some additional verification (to impose restrictions on the IP number of the client for example) then a custom PostAuthenticationFilter may be used.
  • If the authentication is based on username/password but some additional information needs to be collected from the user and verified it's better to combine a custom login page with a PostAuthenticationFilter and possibly a custom JAAS Login Module
If your implementation is able to handle not only requests to the authentication endpoint but also to any other resource (e.g. because it's capable of retrieving the identity from a cookie or header) then you may implement both this and the CustomAuthenticator interface (and configure it accordingly).

Implementations of this interface must be thread-safe and reentrant.

Since:
7.8
See Also:

  • Method Details

    • init

      default void init(CustomWebAuthenticatorInitContext initContext) throws CustomAuthenticatorException
      Initializes this CustomWebAuthenticator.

      The default implementation does nothing.

      Parameters:
      initContext - an initialization context containing parameters and other information that may be used by the implementing class
      Throws:
      CustomAuthenticatorException - if the initialization failed
      Since:
      7.8

    • getProviders

      List<WebAuthProviderDescription> getProviders()
      Returns a non-empty list of descriptions of available providers. The information may be displayed on the login page.
      Returns:
      a non-empty list of descriptions of available providers
      Since:
      7.8

    • getAuthenticationEndpoint

      String getAuthenticationEndpoint(Map<String,Object> sessionContext, String providerName, String targetUrl) throws CustomAuthenticatorException
      Returns an absolute URL to the authentication endpoint of the identity provider with the given name, including all relevant request parameters. The Spotfire Server will redirect the user's browser to this location.

      The targetUrl SHOULD be associated with the authentication attempt (stored in the sessionContext or included in the returned URL) so that the user can be redirected to the right target once authenticated. If the implementor has no good way of storing the targetUrl it MAY be ignored (in which case the user will be redirected to the landing page after successful authentication). Note that failure to return the targetUrl will prevent non-browser clients from authenticating.

      Note that there may be several authentication attempts ongoing at the same time so be careful what you store in the session context. For example do not store the targetUrl unless you give it a key that is unique for this authentication attempt.

      Requests within the same session are serialized during the authentication phase so the session context can be used without any further synchronization.

      Parameters:
      sessionContext - the session context
      providerName - providerName the name of the provider to return a URL to, or null if the default provider should be used (typically the case when there is only one provider available)
      targetUrl - the URL of the resource the user originally tried to access
      Returns:
      a URL, or null if there is no provider with the given name (may happen when combined with some other form of web authentication such as OpenID Connect)
      Throws:
      CustomAuthenticatorException - if an error occurs
      Since:
      7.8
      See Also:

    • authenticateWeb

      CustomWebAuthenticatorResult authenticateWeb(WebAuthenticationContext authContext) throws CustomWebAuthenticatorException
      Performs authentication based on the provided WebAuthenticationContext. If the method returns a result (with a principal), the Spotfire Server will use this identity without performing any further authentication. If the method throws an exception, the Spotfire server will not attempt to perform authentication using any other authentication method and the user's browser will be redirected to an error page.

      The targetUrl given to getAuthenticationEndpoint(Map, String, String) SHOULD be included in the CustomWebAuthenticatorResult.

      Parameters:
      authContext - the context in which the authentication takes place, containing information mainly from the HttpServletRequest
      Returns:
      a result object containing the authenticated principal and, if possible, the originally requested URL
      Throws:
      CustomWebAuthenticatorException - if the authentication failed
      Since:
      7.8