net.shibboleth.idp.session.impl

Class StorageBackedSessionManager

java.lang.Object

net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

net.shibboleth.utilities.java.support.component.AbstractIdentifiedInitializableComponent

net.shibboleth.utilities.java.support.component.AbstractIdentifiableInitializableComponent

net.shibboleth.idp.session.impl.StorageBackedSessionManager

All Implemented Interfaces:

SessionManager, SessionResolver, net.shibboleth.utilities.java.support.component.Component, net.shibboleth.utilities.java.support.component.DestructableComponent, net.shibboleth.utilities.java.support.component.IdentifiableComponent, net.shibboleth.utilities.java.support.component.IdentifiedComponent, net.shibboleth.utilities.java.support.component.InitializableComponent, net.shibboleth.utilities.java.support.resolver.Resolver<IdPSession,net.shibboleth.utilities.java.support.resolver.CriteriaSet>

public class StorageBackedSessionManager
extends net.shibboleth.utilities.java.support.component.AbstractIdentifiableInitializableComponent
implements SessionManager, SessionResolver

Implementation of SessionManager and SessionResolver interfaces that relies on a StorageService for persistence and lifecycle management of data.

The storage layout here is to store most data in a context named for the session ID. Within that context, the master IdPSession record lives under a key called "_session", with an expiration based on the session timeout value plus a configurable amount of "slop" to prevent premature disappearance in case of logout.

Each AuthenticationResult is stored in a record keyed by the flow ID. The expiration is set based on the underlying flow's timeout.

Each SPSession is stored in a record keyed by the service ID. The expiration is set based on the SPSession's own expiration plus the "slop" value.

For cross-referencing, lists of flow and service IDs are tracked within the master "_session" record, so adding either requires an update to the master record plus the creation of a new one. Post-creation, there are no updates to the AuthenticationResult or SPSession records, but the expiration of the result records can be updated to reflect activity updates.

When a SPSession is added, it may expose an optional secondary "key". If set, this is a signal to add a secondary lookup of the SPSession. This is a record containing a list of relevant IdPSession IDs stored under a context/key pair consisting of the Service ID and the exposed secondary key from the object. The expiration of this record is set based on the larger of the current list expiration, if any, and the expiration of the SPSession plus the configured slop value. In other words, the lifetime of the index record is pushed out as far as needed to avoid premature expiration while any of the SPSessions producing it remain around.

The primary purpose of the secondary list is SAML logout, and is an optional feature that can be disabled. In the case of a SAML 2 session, the secondary key is some form of the NameID issued to the service.

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	consistentAddress Indicates whether sessions are bound to client addresses.
private net.shibboleth.utilities.java.support.net.CookieManager	cookieManager Manages creation of cookies.
private String	cookieName Name of cookie used to track sessions.
protected static String	DEFAULT_COOKIE_NAME Default cookie name for session tracking.
private Map<String,AuthenticationFlowDescriptor>	flowDescriptorMap Flows that could potentially be used to authenticate the user.
private HttpServletRequest	httpRequest Servlet request to read from.
private HttpServletResponse	httpResponse Servlet response to write to.
private net.shibboleth.utilities.java.support.security.IdentifierGenerationStrategy	idGenerator Generator for XML ID attribute values.
private Logger	log Class logger.
private boolean	maskStorageFailure Indicates that storage service failures should be masked as much as possible.
private boolean	secondaryServiceIndex Indicates whether to secondary-index SPSessions.
private StorageBackedIdPSessionSerializer	serializer Serializer for sessions.
static String	SESSION_MASTER_KEY Storage key of master session records.
private long	sessionSlop Amount of time in milliseconds to defer expiration of records for better handling of logout.
private long	sessionTimeout Inactivity timeout for sessions in milliseconds.
private SPSessionSerializerRegistry	spSessionSerializerRegistry Mappings between a SPSession type and a serializer implementation.
private org.opensaml.storage.StorageService	storageService The back-end for managing data.
private boolean	trackSPSessions Indicates whether to store and track SPSessions.

Constructor Summary

Constructors

Constructor and Description
StorageBackedSessionManager() Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
IdPSession	createSession(String principalName)
void	destroySession(String sessionId)
protected void	doInitialize()
AuthenticationFlowDescriptor	getAuthenticationFlowDescriptor(String flowId) Get a matching AuthenticationFlowDescriptor.
(package private) HttpServletRequest	getHttpServletRequest() Get the servlet request to read from.
(package private) HttpServletResponse	getHttpServletResponse() Get the servlet response to write to.
long	getSessionSlop() Get the amount of time in milliseconds to defer expiration of records.
long	getSessionTimeout() Get the session inactivity timeout policy in milliseconds.
SPSessionSerializerRegistry	getSPSessionSerializerRegistry() Get the attached spSessionSerializerRegistry.
org.opensaml.storage.StorageSerializer<StorageBackedIdPSession>	getStorageSerializer() Get the serializer for the IdPSession objects managed by this implementation.
org.opensaml.storage.StorageService	getStorageService() Get the StorageService back-end to use.
protected void	indexBySPSession(IdPSession idpSession, SPSession spSession, int attempts) Insert or update a secondary index record from a SPSession to a parent IdPSession.
boolean	isConsistentAddress() Get whether sessions are bound to client addresses.
boolean	isMaskStorageFailure() Get whether to mask StorageService failures where possible.
boolean	isSecondaryServiceIndex() Get whether to create a secondary index for SPSession lookup.
boolean	isTrackSPSessions() Get whether to track SPSessions.
private IdPSession	lookupBySessionId(String sessionId) Performs a lookup and deserializes a record based on session ID.
private Iterable<IdPSession>	lookupBySPSession(SPSessionCriterion criterion) Performs a lookup and deserializes records potentially matching a SPSession.
Iterable<IdPSession>	resolve(net.shibboleth.utilities.java.support.resolver.CriteriaSet criteria)
IdPSession	resolveSingle(net.shibboleth.utilities.java.support.resolver.CriteriaSet criteria)
void	setAuthenticationFlowDescriptors(Iterable<AuthenticationFlowDescriptor> flows) Set the AuthenticationFlowDescriptor collection active in the system.
void	setConsistentAddress(boolean flag) Set whether sessions are bound to client addresses.
void	setCookieManager(net.shibboleth.utilities.java.support.net.CookieManager manager) Set the CookieManager to use.
void	setCookieName(String name) Set the cookie name to use for session tracking.
void	setHttpServletRequest(HttpServletRequest request) Set the servlet request to read from.
void	setHttpServletResponse(HttpServletResponse response) Set the servlet response to write to.
void	setIDGenerator(net.shibboleth.utilities.java.support.security.IdentifierGenerationStrategy newIDGenerator) Set the generator to use when creating XML ID attribute values.
void	setMaskStorageFailure(boolean flag) Set whether to mask StorageService failures where possible.
void	setSecondaryServiceIndex(boolean flag) Set whether to create a secondary index for SPSession lookup.
void	setSessionSlop(long slop) Set the amount of time in milliseconds to defer expiration of records.
void	setSessionTimeout(long timeout) Set the session inactivity timeout policy in milliseconds, must be greater than zero.
void	setSPSessionSerializerRegistry(SPSessionSerializerRegistry registry) Set the SPSessionSerializerRegistry to use.
void	setStorageService(org.opensaml.storage.StorageService storage) Set the StorageService back-end to use.
void	setTrackSPSessions(boolean flag) Set whether to track SPSessions.

Methods inherited from class net.shibboleth.utilities.java.support.component.AbstractIdentifiableInitializableComponent

setId

Methods inherited from class net.shibboleth.utilities.java.support.component.AbstractIdentifiedInitializableComponent

getId

Methods inherited from class net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

destroy, doDestroy, initialize, isDestroyed, isInitialized

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.shibboleth.utilities.java.support.component.IdentifiedComponent

getId

Methods inherited from interface net.shibboleth.utilities.java.support.component.InitializableComponent

initialize, isInitialized

Methods inherited from interface net.shibboleth.utilities.java.support.component.DestructableComponent

destroy, isDestroyed

Field Detail

SESSION_MASTER_KEY

@Nonnull
@NotEmpty
public static final String SESSION_MASTER_KEY

Storage key of master session records.

See Also:

Constant Field Values

DEFAULT_COOKIE_NAME

@Nonnull
@NotEmpty
protected static final String DEFAULT_COOKIE_NAME

Default cookie name for session tracking.

See Also:

Constant Field Values

log

@Nonnull
private final Logger log

Class logger.

httpRequest

@Nullable
private HttpServletRequest httpRequest

Servlet request to read from.

httpResponse

@Nullable
private HttpServletResponse httpResponse

Servlet response to write to.

sessionTimeout

@Duration
@Positive
private long sessionTimeout

Inactivity timeout for sessions in milliseconds.

sessionSlop

@Duration
@NonNegative
private long sessionSlop

Amount of time in milliseconds to defer expiration of records for better handling of logout.

maskStorageFailure

private boolean maskStorageFailure

Indicates that storage service failures should be masked as much as possible.

trackSPSessions

private boolean trackSPSessions

Indicates whether to store and track SPSessions.

secondaryServiceIndex

private boolean secondaryServiceIndex

Indicates whether to secondary-index SPSessions.

consistentAddress

private boolean consistentAddress

Indicates whether sessions are bound to client addresses.

cookieManager

@NonnullAfterInit
private net.shibboleth.utilities.java.support.net.CookieManager cookieManager

Manages creation of cookies.

cookieName

@Nonnull
@NotEmpty
private String cookieName

Name of cookie used to track sessions.

storageService

@NonnullAfterInit
private org.opensaml.storage.StorageService storageService

The back-end for managing data.

idGenerator

@NonnullAfterInit
private net.shibboleth.utilities.java.support.security.IdentifierGenerationStrategy idGenerator

Generator for XML ID attribute values.

serializer

@Nonnull
private final StorageBackedIdPSessionSerializer serializer

Serializer for sessions.

flowDescriptorMap

@Nonnull
@NonnullElements
private final Map<String,AuthenticationFlowDescriptor> flowDescriptorMap

Flows that could potentially be used to authenticate the user.

spSessionSerializerRegistry

@Nullable
private SPSessionSerializerRegistry spSessionSerializerRegistry

Mappings between a SPSession type and a serializer implementation.

Constructor Detail

StorageBackedSessionManager

public StorageBackedSessionManager()

Constructor.

Method Detail

getHttpServletRequest

@Nullable
HttpServletRequest getHttpServletRequest()

Get the servlet request to read from.

Returns:

servlet request, or null

setHttpServletRequest

public void setHttpServletRequest(@Nullable
                         HttpServletRequest request)

Set the servlet request to read from.

Parameters:

request - servlet request

getHttpServletResponse

@Nullable
HttpServletResponse getHttpServletResponse()

Get the servlet response to write to.

Returns:

servlet response, or null

setHttpServletResponse

public void setHttpServletResponse(@Nullable
                          HttpServletResponse response)

Set the servlet response to write to.

Parameters:

response - servlet response

getSessionTimeout

@Positive
public long getSessionTimeout()

Get the session inactivity timeout policy in milliseconds.

Returns:

inactivity timeout

setSessionTimeout

public void setSessionTimeout(@Duration@Positive
                     long timeout)

Set the session inactivity timeout policy in milliseconds, must be greater than zero.

Parameters:

timeout - the policy to set

getSessionSlop

@Positive
public long getSessionSlop()

Get the amount of time in milliseconds to defer expiration of records.

Returns:

expiration deferrence time

setSessionSlop

public void setSessionSlop(@Duration@NonNegative
                  long slop)

Set the amount of time in milliseconds to defer expiration of records.

Parameters:

slop - the policy to set

isMaskStorageFailure

public boolean isMaskStorageFailure()

Get whether to mask StorageService failures where possible.

Returns:

true iff StorageService failures should be masked

setMaskStorageFailure

public void setMaskStorageFailure(boolean flag)

Set whether to mask StorageService failures where possible.

Parameters:

flag - flag to set

isTrackSPSessions

public boolean isTrackSPSessions()

Get whether to track SPSessions.

Returns:

true iff SPSessions should be persisted

setTrackSPSessions

public void setTrackSPSessions(boolean flag)

Set whether to track SPSessions.

This feature requires a StorageService that is not client-side because of space limitations.

Parameters:

flag - flag to set

isSecondaryServiceIndex

public boolean isSecondaryServiceIndex()

Get whether to create a secondary index for SPSession lookup.

Returns:

true iff a secondary index for SPSession lookup should be maintained

setSecondaryServiceIndex

public void setSecondaryServiceIndex(boolean flag)

Set whether to create a secondary index for SPSession lookup.

This feature requires a StorageService that is not client-side.

Parameters:

flag - flag to set

isConsistentAddress

public boolean isConsistentAddress()

Get whether sessions are bound to client addresses.

Returns:

true iff sessions should be bound to client addresses

setConsistentAddress

public void setConsistentAddress(boolean flag)

Set whether sessions are bound to client addresses.

Parameters:

flag - flag to set

setCookieName

public void setCookieName(@Nonnull@NotEmpty
                 String name)

Set the cookie name to use for session tracking.

Parameters:

name - cookie name to use

setCookieManager

public void setCookieManager(@Nonnull
                    net.shibboleth.utilities.java.support.net.CookieManager manager)

Set the CookieManager to use.

Parameters:

manager - the CookieManager to use.

getStorageService

@Nonnull
public org.opensaml.storage.StorageService getStorageService()

Get the StorageService back-end to use.

Returns:

the back-end to use

setStorageService

public void setStorageService(@Nonnull
                     org.opensaml.storage.StorageService storage)

Set the StorageService back-end to use.

Parameters:

storage - the back-end to use

setIDGenerator

public void setIDGenerator(@Nonnull
                  net.shibboleth.utilities.java.support.security.IdentifierGenerationStrategy newIDGenerator)

Set the generator to use when creating XML ID attribute values.

Parameters:

newIDGenerator - the new IdentifierGenerator to use

getStorageSerializer

@Nonnull
public org.opensaml.storage.StorageSerializer<StorageBackedIdPSession> getStorageSerializer()

Get the serializer for the IdPSession objects managed by this implementation.

Returns:

the serializer to use when writing back session objects

getAuthenticationFlowDescriptor

@Nullable
public AuthenticationFlowDescriptor getAuthenticationFlowDescriptor(@Nonnull@NotEmpty
                                                                    String flowId)

Get a matching AuthenticationFlowDescriptor.

Parameters:

flowId - the ID of the flow to return

Returns:

the matching flow descriptor, or null

setAuthenticationFlowDescriptors

public void setAuthenticationFlowDescriptors(@Nonnull@NonnullElements
                                    Iterable<AuthenticationFlowDescriptor> flows)

Set the AuthenticationFlowDescriptor collection active in the system.

Parameters:

flows - the flows available for possible use

getSPSessionSerializerRegistry

@Nullable
public SPSessionSerializerRegistry getSPSessionSerializerRegistry()

Get the attached spSessionSerializerRegistry.

Returns:

a registry of SPSession class to serializer mappings

setSPSessionSerializerRegistry

public void setSPSessionSerializerRegistry(@Nullable
                                  SPSessionSerializerRegistry registry)

Set the SPSessionSerializerRegistry to use.

Parameters:

registry - a registry of SPSession class to serializer mappings

doInitialize

protected void doInitialize()
                     throws net.shibboleth.utilities.java.support.component.ComponentInitializationException

Overrides:

doInitialize in class net.shibboleth.utilities.java.support.component.AbstractIdentifiedInitializableComponent

Throws:

net.shibboleth.utilities.java.support.component.ComponentInitializationException

createSession

@Nonnull
public IdPSession createSession(@Nonnull@NotEmpty
                               String principalName)
                         throws SessionException

Specified by:

createSession in interface SessionManager

Throws:

SessionException

destroySession

public void destroySession(@Nonnull@NotEmpty
                  String sessionId)
                    throws SessionException

Specified by:

destroySession in interface SessionManager

Throws:

SessionException

resolve

@Nonnull
@NonnullElements
public Iterable<IdPSession> resolve(@Nullable
                                                   net.shibboleth.utilities.java.support.resolver.CriteriaSet criteria)
                             throws net.shibboleth.utilities.java.support.resolver.ResolverException

Specified by:

resolve in interface net.shibboleth.utilities.java.support.resolver.Resolver<IdPSession,net.shibboleth.utilities.java.support.resolver.CriteriaSet>

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException

resolveSingle

@Nullable
public IdPSession resolveSingle(@Nullable
                                net.shibboleth.utilities.java.support.resolver.CriteriaSet criteria)
                         throws net.shibboleth.utilities.java.support.resolver.ResolverException

Specified by:

resolveSingle in interface net.shibboleth.utilities.java.support.resolver.Resolver<IdPSession,net.shibboleth.utilities.java.support.resolver.CriteriaSet>

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException

indexBySPSession

protected void indexBySPSession(@Nonnull
                    IdPSession idpSession,
                    @Nonnull
                    SPSession spSession,
                    int attempts)
                         throws SessionException

Insert or update a secondary index record from a SPSession to a parent IdPSession.

Parameters:

idpSession - the parent session

spSession - the SPSession to index

attempts - number of times to retry operation in the event of a synchronization issue

Throws:

SessionException - if a fatal error occurs

lookupBySessionId

@Nullable
private IdPSession lookupBySessionId(@Nonnull@NotEmpty
                                    String sessionId)
                              throws net.shibboleth.utilities.java.support.resolver.ResolverException

Performs a lookup and deserializes a record based on session ID.

Parameters:

sessionId - the session to lookup

Returns:

the IdPSession object, or null

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException - if an error occurs during lookup

lookupBySPSession

@Nonnull
@NonnullElements
private Iterable<IdPSession> lookupBySPSession(@Nonnull
                                                             SPSessionCriterion criterion)
                                        throws net.shibboleth.utilities.java.support.resolver.ResolverException

Performs a lookup and deserializes records potentially matching a SPSession.

Parameters:

criterion - the SPSessionCriterion to apply

Returns:

collection of zero or more sessions

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException - if an error occurs during lookup