io.mats3.matssocket

Interface AuthenticationPlugin

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface AuthenticationPlugin

Plugin that must evaluate whether a WebSocket connection shall be allowed, and then authenticate the resulting MatsSocketSession.

1. Upon WebSocket connection, the methods checkOrigin(..), checkHandshake(..) and onOpen(..) are invoked in succession.
2. During the initial set of messages received from the MatsSocket Client, the initialAuthentication(..) is invoked, which evaluates whether the supplied Authorization "Header" value is good, and if so returns a Principal and a UserId.
3. During the life of the MatsSocketSession, the two methods reevaluateAuthentication(..) and reevaluateAuthenticationForOutgoingMessage(..) may be invoked several times.
4. When the Client tries to subscribe to a Topic, the method authorizeUserForTopic(..) is invoked to decide whether to allow or deny the subscription.

Read through all methods' JavaDoc in succession to get an understanding of how it works!

Thread Safety: Concurrency issues wrt. to multiple threads accessing a AuthenticationPlugin.SessionAuthenticator: Seen from the MatsSocketServer, only one thread will ever access any of the methods at any one time, and memory consistency is handled (i.e. the AuthenticationPlugin.SessionAuthenticator instance is effectively synchronized on): You do not need to synchronize on anything within an instance of AuthenticationPlugin.SessionAuthenticator, and any fields set on the instance by some method will be correctly available for subsequent invocations of the same or any other methods.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	AuthenticationPlugin.AuthenticationContext
static interface	AuthenticationPlugin.AuthenticationResult You are NOT supposed to implement this interface! Instances of this interface are created by methods on the AuthenticationPlugin.AuthenticationContext, which you are supposed to return from the AuthenticationPlugin.SessionAuthenticator to inform the MatsSocketServer about your verdict of the authentication attempt.
static class	AuthenticationPlugin.DebugOption These bit-field enums (bit-field) is used by the Client to request different types of debug/meta information from Server-side, and used by the AuthenticationPlugin to tell the MatsSocketServer which types of information the specific user is allowed to request - the resulting debug/meta information provided is the intersection of the requested + allowed.
static interface	AuthenticationPlugin.SessionAuthenticator An instance of this interface shall be returned upon invocation of newSessionAuthenticator().

Method Summary

Modifier and Type	Method and Description
AuthenticationPlugin.SessionAuthenticator	newSessionAuthenticator() Invoked by the MatsSocketServer upon each WebSocket connection that wants to establish a MatsSocket - that is, you may provide a connections-specific instance per connection.

Method Detail

newSessionAuthenticator

AuthenticationPlugin.SessionAuthenticator newSessionAuthenticator()

Invoked by the MatsSocketServer upon each WebSocket connection that wants to establish a MatsSocket - that is, you may provide a connections-specific instance per connection. The server will then invoke the different methods on the returned AuthenticationPlugin.SessionAuthenticator.

Returns:

an instance of AuthenticationPlugin.SessionAuthenticator, where the implementation may choose whether it is a singleton, or if a new instance is returned per invocation (which then means there is a unique instance per connection, thus you can hold values for the connection there).