com.pushtechnology.diffusion.client.features.control.clients

Interface AuthenticationControl

All Superinterfaces:

Feature

public interface AuthenticationControl
extends Feature

This feature allows a client session to authenticate the credentials of other sessions.

Sessions are authenticated by a chain of authentication handlers. A client session can participate in the authentication process by creating an authentication handler and registering it with the server.

Each authentication handler is registered under a particular handler name. For registration to succeed, the server's security configuration must include a matching control-authentication-handler entry for the name, otherwise registration will fail and the authentication handler will be closed immediately.

Each client session can register a single authentication handler for a given handler name.

For each authentication event, the server will use its configuration to determine the handler priority order. The server may call authentication handlers in serial or parallel. The server may stop the authentication process as soon as it has an allow or deny response from an authentication handler and all higher priority authentication handlers have abstained.

For a configured control authentication handler, the server will select a single handler from those registered for the handler name. If no authenticators are currently registered, the server will consult the next configured authentication handler in priority order.

Access control

In order to register an authentication handler a session needs both REGISTER_HANDLER and AUTHENTICATE permissions.

Accessing the feature

This feature may be obtained from a session as follows:

 
 AuthenticationControl authenticationControl = session.feature(AuthenticationControl.class);
 
 

Since:

5.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	AuthenticationControl.ControlAuthenticator A control authenticator.

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Registration>	setAuthenticationHandler(String handlerName, AuthenticationControl.ControlAuthenticator authenticator) Register an authentication handler for client authentication events.

Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature

getSession

Method Detail

setAuthenticationHandler

CompletableFuture<Registration> setAuthenticationHandler(String handlerName,
                                                         AuthenticationControl.ControlAuthenticator authenticator)

Register an authentication handler for client authentication events.

Parameters:

handlerName - the handler name which must match an entry in the server's security configuration

authenticator - specifies the authentication handler

Returns:

a CompletableFuture that completes when the authentication handler has been registered, returning a Registration which can be used to unregister the authentication handler.

Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

• SessionClosedException – if the session is closed;
• PermissionsException – if the session does not have REGISTER_HANDLER or AUTHENTICATE permission;
• SessionException – will occur if the server configuration does not contain a control-authentication-handler element with the given name.

Since:

6.2