Diffusion JavaScript API 6.2.8

Class: AuthenticationHandler

AuthenticationHandler

new 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 AuthenticationHandler.Callback#allow(AuthenticationResult) may be used by the handler to supply the server with additional information that is used to set up the session.

Classes

Callback

Methods

onActive(deregister)

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.

Parameters:
Name Type Description
deregister function

A function that may be called to deregister this handler

onAuthenticate(principal, credentials, sessionDetails, callback)

Request authentication.

The server calls this to authenticate new sessions, and when a client requests the session principal is changed (e.g. using Session.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.

Parameters:
Name Type Description
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 AuthenticationHandler.Callback

single use callback

onClose()

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.

onError(error)

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.

Parameters:
Name Type Description
error Object

The error