com.tenduke.services.http
Class CookieBasedHttpSessionHandler

java.lang.Object
  com.tenduke.networking.http.ConfigurableHttpSessionHandler
      com.tenduke.services.http.CookieBasedHttpSessionHandler

All Implemented Interfaces:

HttpSessionHandler

public class CookieBasedHttpSessionHandler
extends ConfigurableHttpSessionHandler

Session handler implementation class that uses cookies to manage user session. This class signs session using a configurable secret. Session signing allows handling client session validation in a distributed system without information exchange between the participating nodes that validate requests.

Table of configuration keys defined by this class.

Key name	Description	Default value
usermanagement.ignoreloginnamecase	Controls if case should be ignored in login names. Valid values are true and false.	false
security.cookiebasedhttpsessionhandler.sessionsignaturekey	A key that is used to sign a session. Once a session has been created and signed using the configured kay it can be validated based on data in client cookies, the signature stored in a client cookie and the re-computed signature.	Randomly generated signature

Field Summary

static int	MAX_COOKIE_AGE Maximum age for a cookie for use cases where cookies are not set as session cookies.
static java.lang.String	PREFER_PERSISTENT_SESSION_PARAMETER_NAME Constant for request parameter name that defines option to use persistent cookies instead of session cookies when logging in user.

Constructor Summary

CookieBasedHttpSessionHandler()
Creates new instance of CookieBasedHttpSessionHandler.

Method Summary

static boolean	alwaysIgnoreLoginNameCase() Checks whether login name case should always be ignored.
protected void	clearSessionDigest(javax.servlet.http.HttpServletResponse response) Clear the session signing cookie containing digest for valid session.
boolean	createSession(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.String sessionProfileId) Created and identifies session based on two cookies.
protected java.lang.String	createSessionDigest(java.lang.String principal) Create the digest to store in session.
void	endSession(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Clears all cookies used to store session data, resulting in a invalidated session.
protected java.lang.String	getSessionProfileIdByCookies(javax.servlet.http.HttpServletRequest request) Retrieves session profile id stored in cookie after checking session digest to ensure that session profile id has not been tampered.
protected byte[]	getSessionSigningBytes(boolean forceRegenerate) Gets the bytes set for signing sessions with.
java.security.Principal	getSessionUser(javax.servlet.http.HttpServletRequest request) Gets user identifier bound to session, wrapped in a Principal object.
java.security.Principal	getSessionUserPrincipal(javax.servlet.http.HttpServletRequest request, java.lang.String principalType) Get current session user principal of given type.
protected void	parseConfiguration() Reads value defined by key named observer.
void	setSessionSigningBytes(byte[] sessionSigningBytes) Sets the bytes used to sign sessions created by this handler.
protected boolean	signSession(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.String sessionPrincipal) Sign session by writing a session digest in a cookie.
LoginInformation	validateInitialLogin(javax.servlet.http.HttpServletRequest request) Validates user login using client HTTP request.
LoginInformation	validateSession(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Validates session based on two cookies.

Methods inherited from class com.tenduke.networking.http.ConfigurableHttpSessionHandler

configure, getConfiguration, setConfiguration

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_COOKIE_AGE

public static final int MAX_COOKIE_AGE

Maximum age for a cookie for use cases where cookies are not set as session cookies. Maximum age is 3 years.

See Also:

Constant Field Values

PREFER_PERSISTENT_SESSION_PARAMETER_NAME

public static final java.lang.String PREFER_PERSISTENT_SESSION_PARAMETER_NAME

Constant for request parameter name that defines option to use persistent cookies instead of session cookies when logging in user. Persistent cookies will enable implementation of "stay signed in" type UI for login screens.

See Also:

Constant Field Values

Constructor Detail

CookieBasedHttpSessionHandler

public CookieBasedHttpSessionHandler()

Creates new instance of CookieBasedHttpSessionHandler.

Method Detail

alwaysIgnoreLoginNameCase

public static boolean alwaysIgnoreLoginNameCase()

Checks whether login name case should always be ignored.

Returns:

True if login name case should always be ignored.

clearSessionDigest

protected void clearSessionDigest(javax.servlet.http.HttpServletResponse response)

Clear the session signing cookie containing digest for valid session.

Parameters:

response - The response object for client to reset session cookie.

createSession

public boolean createSession(javax.servlet.http.HttpServletRequest request,
                             javax.servlet.http.HttpServletResponse response,
                             java.lang.String sessionProfileId)

Created and identifies session based on two cookies. These cookies are:

• KeyWords.SessionParameterKeywords.SESSION_SHORT_NAME_COOKIE
• KeyWords.SessionParameterKeywords.LOGIN_STATE

In addition to the data stored in cookies a digest is computed (based on a configurable secret key) and stored in a cookie named: KeyWords.SessionParameterKeywordsSESSION_DIGEST

Parameters:

request - Client HTTP request.

response - Client HTTP response to write session to.

sessionProfileId - Profile id to bind to the session

Returns:

true for successfully created session.

createSessionDigest

protected java.lang.String createSessionDigest(java.lang.String principal)

Create the digest to store in session.

Parameters:

principal - The name to sign session for.

Returns:

Digest to store in session.

endSession

public void endSession(javax.servlet.http.HttpServletRequest request,
                       javax.servlet.http.HttpServletResponse response)

Clears all cookies used to store session data, resulting in a invalidated session.

Parameters:

request - Client HTTP request to end session for.

response - Client HTTP response to modify to apply changes in session.

getSessionProfileIdByCookies

protected java.lang.String getSessionProfileIdByCookies(javax.servlet.http.HttpServletRequest request)

Retrieves session profile id stored in cookie after checking session digest to ensure that session profile id has not been tampered.

Parameters:

request - Client HTTP request to inspect for user session.

Returns:

Profile id bound to session.

getSessionSigningBytes

protected byte[] getSessionSigningBytes(boolean forceRegenerate)

Gets the bytes set for signing sessions with. (Re)creates session signing bytes if forceRegenerate is set to true of current session signing bytes have not been created.

Parameters:

forceRegenerate - Flag to force regenerating session signing bytes.

Returns:

Byte array to use for signing session.

getSessionUser

public java.security.Principal getSessionUser(javax.servlet.http.HttpServletRequest request)

Gets user identifier bound to session, wrapped in a Principal object.

Reads cookie by name KeyWords.SessionParameterKeywords.SESSION_PROFILE_ID_COOKIE from request.

Parameters:

request - Client HTTP request for reading session user identification

Returns:

Principal object representing the user bound to client HTTP session.

getSessionUserPrincipal

public java.security.Principal getSessionUserPrincipal(javax.servlet.http.HttpServletRequest request,
                                                       java.lang.String principalType)

Get current session user principal of given type.

Parameters:

request - Client HTTP request with data to use for resolving Principal object.

principalType - Principal type. Recognized principal types are defined by UserDatabase.PrincipalType constants.

Returns:

Principal of given type, or null if not found

parseConfiguration

protected void parseConfiguration()

Reads value defined by key named observer. Value is expected to be fully qualified class path to class to load as an observer,

Specified by:

parseConfiguration in class ConfigurableHttpSessionHandler

setSessionSigningBytes

public void setSessionSigningBytes(byte[] sessionSigningBytes)

Sets the bytes used to sign sessions created by this handler.

Parameters:

sessionSigningBytes - the session signing bytes to set.

signSession

protected boolean signSession(javax.servlet.http.HttpServletRequest request,
                              javax.servlet.http.HttpServletResponse response,
                              java.lang.String sessionPrincipal)

Sign session by writing a session digest in a cookie.

Parameters:

request - Client HTTP request.

response - Client HTTP response.

sessionPrincipal - The principal name to bind to session.

Returns:

true for success.

validateInitialLogin

public LoginInformation validateInitialLogin(javax.servlet.http.HttpServletRequest request)

Validates user login using client HTTP request.

Reads username from request parameters using following order and parameter names:

• Profile.FIELD_NAME_SHORT_NAME.
• Account.FIELD_NAME_PRIMARY_PRINCIPAL.
• Account.FIELD_NAME_ACCOUNT_ID.
• "userName"

Reads password hash or plain text password from request parameters using following order and parameter names:

• "pwHash"
• "passwordHash"
• "PASSWORD" (treated as plain text password or password hash)
• "password" (treated as plain text password or password hash)

Implementation uses UserManager.loginWithPasswordHash(java.lang.String, java.lang.String) and alternatively UserManager.login(java.lang.String, java.lang.String) with user name and password found in the request.

Parameters:

request - Client HTTP request holding credentials to login with.

Returns:

instance of LoginInformation for successful login

validateSession

public LoginInformation validateSession(javax.servlet.http.HttpServletRequest request,
                                        javax.servlet.http.HttpServletResponse response)

Validates session based on two cookies. These cookies are:

• KeyWords.SessionParameterKeywords.SESSION_SHORT_NAME
• KeyWords.SessionParameterKeywords.SESSION_DIGEST

The digest is re-computed based on short name and configured secret. The cookie based digest and the computed digest are compared. Equal values for the two digest computations qualifies a valid session for the specified shortName.

Parameters:

request - Client HTTP request to validate.

response - Client HTTP response to modify to apply changes in session.

Returns:

Object that implements LoginInformationProvider and carries information of login / session status. Null if session not valid. If session is valid, LoginInformationProvider.getProfileId() return session user profile id.