• Public
  • Public/Protected
  • All

Interface AuthenticationHandler

Handler for session authentication events. Must be implemented by user.

Authentication handlers implementing this interface can be registered with the server. The server calls the authentication handlers when a client application creates a session, or changes the principal associated with a session, allowing the handler to veto individual requests.

Authentication handlers are configured in precedence order. Authentication will succeed if a handler returns allow and all higher precedence handlers (earlier in the order) return abstain. Authentication will fail if a handler returns deny and all higher precedence handlers return 'abstain'. If all authentication handlers return 'abstain', the request will be denied. Once the outcome is known, the server may choose not to call the remaining handlers.

The special variant of allow may be used by the handler to supply the server with additional information that is used to set up the session.


since 6.3

This interface is part of the deprecated AuthenticationHandler API. Use the new Authenticator API instead.


  • AuthenticationHandler




  • onActive(deregister: function): void
  • Called when the handler has been successfully registered with the server.

    A session can register a single handler. If there is already a handler registered, the operation will fail and onClose will be called.

    To deregister the handler, call the deregister function supplied.


    • deregister: function

      a function that may be called to deregister this handler

        • (): void
        • Returns void

    Returns void


  • Request authentication.

    The server calls this to authenticate new sessions, and when a client requests the session principal is changed (e.g. using Security.changePrincipal.

    For each call to onAuthenticate, the authentication handler should respond by calling one of the methods of the provided callback. The handler may return immediately and process the authentication request asynchronously. The client session will be blocked until a callback method is called.


    • principal: string

      the requested principal, or '' if none was supplied.

    • credentials: string | Buffer

      credentials authenticating the principal

    • sessionDetails: SessionDetails

      the information the server has about the client

    • callback: AuthenticationHandlerCallback

      single use callback

    Returns void


  • onClose(): void
  • Called when the handler is closed. The handler will be closed if the session is closed, or if the handler is unregistered.

    Once closed, no further calls will be made for the handler.

    Returns void


  • onError(error: Error): void
  • Notification of a contextual error related to this handler. This is analogous to an unchecked exception being raised. Situations in which onError is called include the session being closed before the handler is registered, a communication timeout, or a problem with the provided parameters. No further calls will be made to this handler.


    • error: Error

      the error

    Returns void