com.caplin.server.auth

Interface SessionManager

public interface SessionManager

Provides an interface to allow management (ejection and invalidation) of connected sessions and checking of KeyMaster tokens.

An instance of this class is passed to the Authenticator in the initialise method Authenticator.initialise(com.caplin.server.auth.SessionManager, com.caplin.server.auth.DelayedResultReceiver, com.caplin.server.auth.ServerNode, java.lang.String). This can then be used at a later time to eject or invalidate sessions.

Sessions may be ejected or invalidated by a number of criteria such as machine ID and application ID. Invalidation of a session forces the Liberator to re-check all (or a subset, depending on the InvalidationType specified) permissions for that session.

KeyMaster tokens can be checked using the checkSignature(String, String) method.

Default session and individual object throttle levels can be set using the adjustThrottleForSession(UserSession, ThrottleCommand) and adjustThrottleForObject(UserSession, String, ThrottleCommand) methods.

Method Summary

Methods

Modifier and Type	Method and Description
void	adjustThrottleForObject(UserSession session, java.lang.String subscribedObjectName, ThrottleCommand command) Provides a mechanism to control the throttling level of a single subscription of a session.
void	adjustThrottleForSession(UserSession session, ThrottleCommand command) Provides a mechanism to control the throttling level of all subscriptions of a session.
AuthenticationResult	checkSignature(java.lang.String keyIdentifier, java.lang.String token) Provides a mechanism for validating a KeyMaster-generated encrypted single-use token.
int	ejectSessions(AuthenticationUser user, int numberToEject) Ejects one or more of a user's sessions.
int	ejectSessionsByApplicationId(AuthenticationUser user, int numberToEject, java.lang.String applicationId) Ejects one or more of a user's sessions based on machine application identifier.
int	ejectSessionsByMachineId(AuthenticationUser user, int numberToEject, java.lang.String machineId) Ejects one or more of a user's sessions based on machine identifier.
void	invalidateAllSessions(InvalidationType type) Provides the mechanism for invalidating all connected sessions.
void	invalidateObject(java.lang.String objectName, InvalidationType type) Performs invalidation of an object, affecting all users subscribed to it.
void	invalidateSessions(AuthenticationUser user, int numberToInvalidate, InvalidationType type) Performs invalidation of all or a number of a user's sessions.
Subscription	newSubscription(java.lang.String prefix, java.lang.String objectName, SubscriptionListener subscriptionListener) Returns a Subscription allowing the Liberator Auth Module subscribe to subjects.
AuthenticationResult	verifySignatureUsername(java.lang.String username, java.lang.String token) Provides a mechanism for verifying the username embedded within a KeyMaster token.

Method Detail

ejectSessions

int ejectSessions(AuthenticationUser user,
                int numberToEject)

Ejects one or more of a user's sessions.

Parameters:

user - the AuthenticationUser instance whose sessions are to be ejected.

numberToEject - the number of sessions to eject, or -1 for all sessions.

Returns:

the number of sessions successfully ejected

ejectSessionsByApplicationId

int ejectSessionsByApplicationId(AuthenticationUser user,
                               int numberToEject,
                               java.lang.String applicationId)

Ejects one or more of a user's sessions based on machine application identifier.

Parameters:

user - the AuthenticationUser instance whose sessions are to be ejected.

numberToEject - the number of sessions to invalidate, or -1 for all sessions.

applicationId - the application identifier to match for ejecting sessions. This string is provided to the Liberator by the connecting client.

Returns:

the number of sessions successfully ejected

ejectSessionsByMachineId

int ejectSessionsByMachineId(AuthenticationUser user,
                           int numberToEject,
                           java.lang.String machineId)

Ejects one or more of a user's sessions based on machine identifier.

Parameters:

user - the AuthenticationUser instance whose sessions are to be ejected.

numberToEject - the number of sessions to invalidate, or -1 for all sessions.

machineId - the machine identifier to match for ejecting sessions. This string is provided to the Liberator by the connecting client and is typically the hostname.

Returns:

the number of sessions successfully ejected.

invalidateObject

void invalidateObject(java.lang.String objectName,
                    InvalidationType type)

Performs invalidation of an object, affecting all users subscribed to it.

Depending on the InvalidationType passed in, calls to mapObject and checkRead will be made for each object subscription.

Parameters:

objectName - the name of the object to invalidate

type - the invalidation scheme to use (one of InvalidationType.READ or InvalidationType.READ_CHECK_OBJECT).

invalidateSessions

void invalidateSessions(AuthenticationUser user,
                      int numberToInvalidate,
                      InvalidationType type)

Performs invalidation of all or a number of a user's sessions.

Depending on the InvalidationType passed in, calls to mapObject and checkRead will be made for each object subscription.

Parameters:

user - the AuthenticationUser instance whose sessions are to be invalidated.

numberToInvalidate - the number of sessions to invalidate, or -1 for all sessions.

type - the invalidation scheme to use (one of InvalidationType.READ or InvalidationType.READ_CHECK_OBJECT).

invalidateAllSessions

void invalidateAllSessions(InvalidationType type)

Provides the mechanism for invalidating all connected sessions.

This method is useful when the whole set of user permissions has been updated and you need the Liberator to re-validate all sessions. Depending on the InvalidationType passed in, calls to mapObject and checkRead will be made for each object subscription.

Parameters:

type - the invalidation scheme to use (one of InvalidationType.READ or InvalidationType.READ_CHECK_OBJECT).

adjustThrottleForSession

void adjustThrottleForSession(UserSession session,
                            ThrottleCommand command)

Provides a mechanism to control the throttling level of all subscriptions of a session.

This will adjust the throttle level for any future subscriptions during the life of this session and all current subscriptions (if they haven't had an overridden throttle level set using adjustThrottleForObject(UserSession, String, ThrottleCommand)).

Parameters:

session - the session to invoke the throttle command on.

command - the throttling command to invoke.

adjustThrottleForObject

void adjustThrottleForObject(UserSession session,
                           java.lang.String subscribedObjectName,
                           ThrottleCommand command)

Provides a mechanism to control the throttling level of a single subscription of a session.

This will set the throttle level for a single object that is subscribed by a session.

A call to this method will mean that this object will no longer be controlled by calls to adjustThrottleForSession(UserSession, ThrottleCommand), unless that call is issued using the ThrottleCommand.DEFAULT.

Parameters:

session - the session to invoke the throttle command on.

subscribedObjectName - the subscription name of the object to be throttled.

command - the throttling command to invoke.

checkSignature

AuthenticationResult checkSignature(java.lang.String keyIdentifier,
                                  java.lang.String token)

Provides a mechanism for validating a KeyMaster-generated encrypted single-use token.

The token is usually provided during a Authenticator.checkUser(UserSession) call as a password (AuthenticationUser.getPassword()). This method can then be used to check that the provided token is valid.

The keyIdentifier parameter is used to uniquely identify which key the Liberator should use when decrypting the token (this matches the corresponding key-id option within the add-sigkey section of the Liberator configuration file. The Liberator may be configured to use multiple decryption keys, identified by the key-id option.

The AuthenticationResult returned by this method can then be used as a return from the Authenticator.checkUser(UserSession) call or handled appropriately.

Parameters:

keyIdentifier - a String that is used by the Liberator to identify the correct public key to use to decrypt the token.

token - a KeyMaster-generated encrypted logon token.

Returns:

an AuthenticationResult instance - one of:

• AuthenticationResult.OK if the token is valid.
• AuthenticationResult.DENY if the token is invalid.
• AuthenticationResult.INVALID_USER if the keyIdentifier is not found in the Liberator.
• AuthenticationResult.USER_LC_EXCEEDED if the token has already been used.
• AuthenticationResult.ERROR if an unexpected error occured.

verifySignatureUsername

AuthenticationResult verifySignatureUsername(java.lang.String username,
                                           java.lang.String token)

Provides a mechanism for verifying the username embedded within a KeyMaster token.

Parameters:

username - the username that we expect to be embedded within the token.

token - a KeyMaster-generated encyrpted logon token.

Returns:

an AuthenticationResult instance - one of:

• AuthenticationResult.OK if the username within the token is valid.
• AuthenticationResult.DENY if the username within the token is invalid.

newSubscription

Subscription newSubscription(java.lang.String prefix,
                           java.lang.String objectName,
                           SubscriptionListener subscriptionListener)

Returns a Subscription allowing the Liberator Auth Module subscribe to subjects. If the subject is a container its constituents will also be subscribed to (with prefix prepended). Data from all permission objects subscribed to will be passes to Authenticator.globalPermissionUpdate(com.caplin.server.auth.RTTPObject, java.lang.String, java.util.Map<java.lang.String, java.lang.String>, com.caplin.server.auth.PermissionUpdateType). As there is no other way to access the data you should only subscribe to permissions or containers of permissions. If there is no response the request will fail after the configured request-timeout. If the subscription fails it is automaticly unsubscribed.

Parameters:

prefix - Subject prefix to be prepended to all subjects subscribed to.

objectName - Subject without prefix.

subscriptionListener - SubscriptionListener to notify the caller the data has been loaded or the subscrition has failed.

Returns:

Subscription to alow the subscription to be subscribed to and unsubscribed from.