io.mats3.matssocket

Interface AuthenticationPlugin.AuthenticationContext

Enclosing interface:

AuthenticationPlugin

public static interface AuthenticationPlugin.AuthenticationContext

Method Summary

Modifier and Type	Method and Description
AuthenticationPlugin.AuthenticationResult	authenticated(java.security.Principal principal, java.lang.String userId) Good Authentication! Return the result from this method from SessionAuthenticator.initialAuthentication(..) to denote good authentication, supplying a Principal representing the accessing user, and the UserId of this user.
AuthenticationPlugin.AuthenticationResult	authenticated(java.security.Principal principal, java.lang.String userId, java.util.EnumSet<AuthenticationPlugin.DebugOption> allowedDebugOptions) Good Authentication! Variant of authenticated(Principal, String) that grants the authenticated user special abilities to ask for debug info of the performed call.
javax.websocket.server.HandshakeRequest	getHandshakeRequest()
MatsSocketServer.LiveMatsSocketSession	getMatsSocketSession()
AuthenticationPlugin.AuthenticationResult	invalidAuthentication(java.lang.String reason) Bad Authentication! Return the result from this method from SessionAuthenticator.initialAuthentication(..) or SessionAuthenticator#reevaluateAuthentication(AuthenticationContext, String, Principal) SessionAuthenticator.reevaluateAuthentication(..)} to denote BAD authentication, supplying a reason string which will be sent all the way to the client (so do not include sensitive information).
void	setOriginatingRemoteAddr(java.lang.String originatingRemoteAddr) Sets the Originating Remote Address, as exposed via MatsSocketServer.ActiveMatsSocketSession.getOriginatingRemoteAddr() - read that JavaDoc.
void	setRemoteAddr(java.lang.String remoteAddr) Sets (or overrides) the Remote Address, as exposed via MatsSocketServer.ActiveMatsSocketSession.getRemoteAddr() - read that JavaDoc, in particular that if this server is behind a proxy, this will be the proxy's address.
AuthenticationPlugin.AuthenticationResult	stillValid() Existing Authentication is still good! Return the result from this method from SessionAuthenticator#reevaluateAuthentication(AuthenticationContext, String, Principal) if the 'existingPrincipal' (and implicitly the userId) is still good to go.

Method Detail

getHandshakeRequest

javax.websocket.server.HandshakeRequest getHandshakeRequest()

Returns:

the HandshakeRequest that was provided to the JSR 356 WebSocket API's Endpoint Configurator when the client connected. Do realize that there is only a single HTTP request involved in setting up the WebSocket connection: The initial "Upgrade: WebSocket" request.

getMatsSocketSession

MatsSocketServer.LiveMatsSocketSession getMatsSocketSession()

Returns:

the current MatsSocketSession. Until Initial Authentication (happening with the HELLO message from the Client), all the Optional-returning methods will return Optional.empty() - it is basically the responsibility of the authentication mechanism to supply values for these.

setRemoteAddr

void setRemoteAddr(java.lang.String remoteAddr)

Sets (or overrides) the Remote Address, as exposed via MatsSocketServer.ActiveMatsSocketSession.getRemoteAddr() - read that JavaDoc, in particular that if this server is behind a proxy, this will be the proxy's address. Also see setOriginatingRemoteAddr(String) where any X-Forwarded-For resolved address should be set.

Note that if the MatsSocketServer handles getting the remote address itself (via hacks, since JSR 356 Java API for WebSockets does not expose it), it will already be available in the getMatsSocketSession().

Parameters:

remoteAddr - what should be replied by MatsSocketServer.ActiveMatsSocketSession.getRemoteAddr().

See Also:

MatsSocketServer.ActiveMatsSocketSession.getRemoteAddr(), setOriginatingRemoteAddr(String)

setOriginatingRemoteAddr

void setOriginatingRemoteAddr(java.lang.String originatingRemoteAddr)

Sets the Originating Remote Address, as exposed via MatsSocketServer.ActiveMatsSocketSession.getOriginatingRemoteAddr() - read that JavaDoc.

Parameters:

originatingRemoteAddr - what should be replied by MatsSocketServer.ActiveMatsSocketSession.getOriginatingRemoteAddr().

See Also:

MatsSocketServer.ActiveMatsSocketSession.getOriginatingRemoteAddr(), setRemoteAddr(String)

invalidAuthentication

AuthenticationPlugin.AuthenticationResult invalidAuthentication(java.lang.String reason)

Bad Authentication! Return the result from this method from SessionAuthenticator.initialAuthentication(..) or SessionAuthenticator#reevaluateAuthentication(AuthenticationContext, String, Principal) SessionAuthenticator.reevaluateAuthentication(..)} to denote BAD authentication, supplying a reason string which will be sent all the way to the client (so do not include sensitive information).

Parameters:

reason - a String which will be sent all the way to the client (so do not include sensitive information).

Returns:

an AuthenticationPlugin.AuthenticationResult that can be returned by the methods of AuthenticationPlugin.SessionAuthenticator.

authenticated

AuthenticationPlugin.AuthenticationResult authenticated(java.security.Principal principal,
                                                        java.lang.String userId)

Good Authentication! Return the result from this method from SessionAuthenticator.initialAuthentication(..) to denote good authentication, supplying a Principal representing the accessing user, and the UserId of this user. You can also return the result from this method from SessionAuthenticator.reevaluateAuthentication(..) if you want to change the Principal, typically just to update some meta data values, as it would be strange if such reevaluation of authentication resulted in a different user than last time.

Parameters:

principal - the Principal that will be supplied to all IncomingAuthorizationAndAdapter#handleIncoming(MatsSocketEndpointIncomingContext, Principal, Object) calls, for the MatsSocket endpoints to evaluate for authorization or to get needed user specific data from (typically thus casting the Principal to a specific class for this AuthenticationPlugin).

userId - the user id for the Principal - this is needed separately from the Principal so that it is possible to target a specific user via a send or request from server to client.

Returns:

an AuthenticationPlugin.AuthenticationResult that can be returned by the methods of AuthenticationPlugin.SessionAuthenticator.

authenticated

AuthenticationPlugin.AuthenticationResult authenticated(java.security.Principal principal,
                                                        java.lang.String userId,
                                                        java.util.EnumSet<AuthenticationPlugin.DebugOption> allowedDebugOptions)

Good Authentication! Variant of authenticated(Principal, String) that grants the authenticated user special abilities to ask for debug info of the performed call.

Parameters:

principal - the Principal that will be supplied to all IncomingAuthorizationAndAdapter#handleIncoming(MatsSocketEndpointIncomingContext, Principal, Object) calls, for the MatsSocket endpoints to evaluate for authorization or to get needed user specific data from (typically thus casting the Principal to a specific class for this AuthenticationPlugin).

userId - the user id for the Principal - this is needed separately from the Principal so that it is possible to target a specific user via a send or request from server to client.

allowedDebugOptions - Which types of Debug stuff the user is allowed to ask for. The resulting debug options is the "logical AND" between these, and what the client requests.

Returns:

an AuthenticationPlugin.AuthenticationResult that can be returned by the methods of AuthenticationPlugin.SessionAuthenticator.

stillValid

AuthenticationPlugin.AuthenticationResult stillValid()

Existing Authentication is still good! Return the result from this method from SessionAuthenticator#reevaluateAuthentication(AuthenticationContext, String, Principal) if the 'existingPrincipal' (and implicitly the userId) is still good to go.

Returns:

an AuthenticationPlugin.AuthenticationResult that can be returned by the method SessionAuthenticator#reevaluateAuthentication(AuthenticationContext, String, Principal), stating that the existing authorization is still valid.