Package 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, and optionally revoke such authentications.

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

Each authenticator is registered under a particular authenticator 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 authenticator will be closed immediately.

Each client session can register a single authenticator for a given authenticator name.

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

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

Access control

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

In order to revoke a session's authentication a session needs both MODIFY_SESSION 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
Author:
DiffusionData Limited

  • Method Details

    • setAuthenticationHandler

      CompletableFuture<Registration> setAuthenticationHandler(String name, AuthenticationControl.ControlAuthenticator authenticator)
      Register an authenticator for client authentication events.
      Parameters:
      name - the authenticator name which must match an entry in the server's security configuration
      authenticator - specifies the authenticator
      Returns:
      a CompletableFuture that completes when the authenticator has been registered, returning a Registration which can be used to unregister the authenticator.

      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 and AUTHENTICATE permission;
      • SessionException – will occur if the server configuration does not contain a control-authentication-handler element with the given name.
      Since:
      6.2

    • revokeAuthentication

      CompletableFuture<?> revokeAuthentication(SessionId sessionId)
      Revokes a session's authentication.

      This will immediately close the specified client session.

      Parameters:
      sessionId - identifies the client session to revoke
      Returns:
      a CompletableFuture that completes when a response is received from the server.

      If the identified session was revoked, the CompletableFuture will complete successfully. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

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

      Since:
      6.12