ESOE Sessions Cache Design

Enterprise Sign On Engine Technical Architecture
Written by Bradley Beddoes
September 2006

Architecture design by Bradley Beddoes
Incorporates SAML 2.0, and (L)XACML 2.0 OASIS standards

Contributions by:
Shaun Mangelsdorf
Andre Zitelli

Edited by:
Bradley Beddoes
Shaun Mangelsdorf
Andre Zitelli

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" in this document are to be interpreted as
described in RFC 2119

Sessions Processor

The sessions processor is the overall control point for session data within the ESOE and the distributed network of SPEPs. It is responsible for creating, storing, updaing and providing all the data related to a principals session.

To facilitate this it loads a primary configuration file called sessiondata.xml, the location from which to load this configuration file is specified in the associated Spring configuration descriptor for this processor. The sessions processor configuration file is compliant with the SessionDataSchema.xsd schema.

The sessions processor is responsible for parsing this configuration file, ensuring it is valid to the schema and storing it in a bean which implements the com.qut.middleware.esoe.sessions.bean.SessionData as the value of com.qut.middleware.esoe.sessions.bean.SessionData.identity, this should be acheived by utilising the functionality of the [[https://jaxb.dev.java.net/|jaxb]] library. Any failure associated with the configuration file SHOULD result in the exception com.qut.middleware.esoe.sessions.exception.ConfigurationValidationException being populated and thrown.

The sessions processor exposes four components to the rest of the ESOE. com.qut.middleware.esoe.sessions.Create, com.qut.middleware.esoe.sessions.Query, com.qut.middleware.esoe.sessions.Update and com.qut.middleware.esoe.sessions.Terminate Each of these in turn may expose several public methods of interaction. Using Spring 2.0 and its IoC functionality each of these are injected to the sessions processor.

The Sessions Processor also stores a central session identity cache. This is indexed by the session identifier supplied with the principal has been successfully authenticated by an authentication handler.

Create

Component Lead Shaun Mangelsdorf
Package com.qut.middleware.esoe.sessions.impl.\*
Type CreateImpl
Implemented Interfaces com.qut.middleware.esoe.sessions.Create
Exceptions DataSourceException

The create component is responsible for creating new sessions within the ESOE. It exposes two public methods to fullfill this purpose createLocalSession and createDistributedSession. Using Spring 2.0 and its IoC functionality the create component has the system identity resolver injected at runtime.

createLocalSession

This function takes a unique session identifier for the session and the user identification string they used to authenticate to the system, this should be the same value which is used to resolve all their identity details from backend identity stores.

The identity resolver is responsible for assembling all portions of the identity. In order to interact with the resolver the stored reference to com.qut.middleware.esoe.sessions.bean.SessionData should be retrieved. A bean of type com.qut.middleware.esoe.sessions.bean.IdentityData should be created. The value of com.qut.middleware.esoe.sessions.bean.SessionData.identity (which corresponds to the <Identity> element in the session processor configuration) should be copied to com.qut.middleware.esoe.sessions.bean.IdentityData.identity. The value of com.qut.middleware.esoe.sessions.bean.IdentityData.sessionID should be set the supplied unique session identifier. The value of com.qut.middleware.esoe.sessions.bean.IdentityData.principalName should be set to the supplied user identifier.

com.qut.middleware.esoe.sessions.bean.IdentityData.attributes is special, it stores a hashmap with the name of the identifier as the key and an Object which implements the interface com.qut.middleware.esoe.sessions.bean.IdentityAttribute as a value. Within the identity processor ALL identity values are stored as their corresponding object data type, for example int is stored as Integer. The interface defines com.qut.middleware.esoe.sessions.bean.IdentityAttribute.type in which the string representation of the contained type is stored. It also defines com.qut.middleware.esoe.sessions.bean.IdentityAttribute.delimiter in which any configured delimiter value is stored. It also defines com.qut.middleware.esoe.sessions.bean.IdentityAttribute.values which is an Object vector to store the values of this piece of identity.

For each attribute identified by com.qut.middleware.esoe.sessions.bean.IdentityData.identity a corresponding entry MUST be created in com.qut.middleware.esoe.sessions.bean.IdentityData.Attributes. The type SHOULD be set to the value of Type for this Attribute, the delimiter SHOULD be set to the value of Delimiter.

Once this bean is prepared the execute function on the identity resolver should be called.

Handled return values

com.qut.middleware.esoe.sessions.identity.IdentityResolver.result.Successful

Once this value has been recieved from the identity resolver a bean that implements com.qut.middleware.esoe.sessions.Principal should be generated. The value of com.qut.middleware.esoe.sessions.Principal.attributes should be set to the value of com.qut.middleware.esoe.sessions.bean.IdentityData.attributes. The value of com.qut.middleware.esoe.sessions.Principal.principalName should be set to the value of com.qut.middleware.esoe.sessions.bean.IdentityData.principalName. The value of com.qut.middleware.esoe.sessions.Principal.authnTimestamp MUST be set the current value of UTC. The value of com.qut.middleware.esoe.sessions.Principal.samlAuthnIdentifier should be generated by the Identity Generator and added to the principal.

Once populated this bean should be stored in the session identity cache. Its index MUST be set to com.qut.middleware.esoe.sessions.bean.IdentityData.sessionID.

The value com.qut.middleware.esoe.sessions.Create.result.SessionCreated should be returned to the caller.

Once the session is successfully established the principal MUST be also associated with the session identity cache by the value of its samlAuthnIdentifier

Handled exceptions

com.qut.middleware.esoe.sessions.exception.DataSourceFailure

This exception should not be caught, instead it should be pased up the call stack.

createDistributedSession

Exceptions

Identity Resolver

Component Lead Shaun Mangelsdorf
Package com.qut.middleware.esoe.sessions.identity.impl.\*
Type IdentityResolverImpl
Implemented Interfaces com.qut.middleware.esoe.sessions.identity.IdentityResolver
Exceptions DataSourceException, HandlerRegistrationException

To allow the correlation of disparate identity sources the Indentity Resolver is primarily concerned with the utilisation of the identity handler pipeline. Using Spring 2.0 and its IoC functionality many unique handlers are registed with the system to handle the supported methods for retrieving identity associated with the principal. Each of these MUST implement the com.qut.middleware.esoe.sessions.identity.pipeline.Handler interface. Handlers are stored in com.qut.middleware.esoe.sessions.identity.IdentityResolver.registeredHandlers.

On initalisation the identity resolver MUST verify that at least one handler has been registered, failure to have at least one handler registered SHOULD result in the exception com.qut.middleware.esoe.sessions.exceptionHandlerRegistrationException.

Handlers are registered in a list data structure. For every request the session processor SHOULD traverse the entire list, and for each handler the execute function should be called. The com.qut.middleware.esoe.sessions.bean.IdentityData bean MUST be supplied to this interface. Handlers MAY add detail to this data structure but they MUST not remove any data from it. For each handler which is called the value of com.qut.middleware.esoe.sessions.bean.IdentityData.currentHandler must be set to value of com.qut.middleware.esoe.session.pipeline.Handler.handlerName.

Handled return values and actions

com.qut.middleware.esoe.sessions.identity.pipeline.Handler.result.Successful

When this value is returned the identity resolver must determine if any handlers remain to be evaluated in the registeredHandlers vector. If they do the next handler's execute method should be called, additionally the value of com.qut.middleware.esoe.sessions.bean.IdentityData.currentHandler must be set to the value of com.qut.middleware.esoe.authn.pipeline.Handler.handlerName.

If no further handlers are present the value com.qut.middleware.esoe.sessions.identity.IdentityResolver.result.Successful should be returned.

Handled exceptions and actions

com.qut.middleware.esoe.sessions.exception.DataSourceException

This exception should not be caught, instead it should be pased up the call stack.

Handlers

Handlers are responsible for actually carrying out some kind of action in regards to retrieving identity. All handlers in the identity pipeline are evaluated when an identity creation of update request takes place within the ESOE. In the identity sense there is only one type of handler, it is passive, the principal is not aware it is happening.

A handler MUST NOT overwrite or remove attribute data set elsewhere in the pipeline.

Handlers MAY retrieve data from any source they wish, LDAP, Databases, web services and flat files to name a few examples. Additionally they MAY be written to simply always append a static value to some piece of identity information or to create a completely new piece of identity information by combining two previously set values.

Handlers utilise the value of com.qut.middleware.esoe.sessions.bean.IdentityData.identity to iterate through all values in the identity configuration. To attempt to populate values for an attribute the handler MUST ensure that the configuration has specified the handler should handle this attribute, that is the value of <Handler> for the <Attribute> MUST match the value of com.qut.middleware.esoe.sessions.pipeline.Handler.name

LDAP Handler

Component Lead Shaun Mangelsdorf
Package com.qut.middleware.esoe.sessions.identity.pipeline.handler.impl.\*
Type LDAPHandlerImpl
Implemented Interfaces com.qut.middleware.esoe.sessions.identity.pipeline.Handler
Exceptions DataSourceFailure

The LDAP Handler is the default handler for the ESOE identity resolver in the distribution package.

The LDAP Handler utilises the functionality of Spring LDAP as an abstraction layer to make queries to the configured LDAP server, LDAP server pool or other LDAP instance and process results.

The LDAP Handler SHOULD loop through all attributes specified in com.qut.middleware.esoe.sessions.bean.IdentityData.identity. It should attempt to look for attributes which have been delegated to the handler 'com.qut.middleware.esoe.sessions.identity.pipeline.handler.impl.LDAPHandlerImpl'. If a the value of LocalIdentity has been set this should be stored as the value to query from the backend LDAP system.

Once all attributes which this handler is responsible for are located queries to the LDAP server should be made, attention should be paid to the value of Singleton and different execution paths taken for singleton vs non singleton types. Any attribute which has a unique local identity should be stored as the value for the overall attribute. Any exception which occurs in the LDAP library should be caught and the exception com.qut.middleware.esoe.sessions.exception.DataSourceException populated and thrown.

For each value returned its type should be determed by the corresponding value of com.qut.middleware.esoe.sessions.bean.IdentityAttribute.type in the corresponding object stored in com.qut.middleware.esoe.sessions.bean.IdentityData.Attributes. It should be converted to the Object type that represents it (in the case of non String) and added to com.qut.middleware.esoe.sessions.bean.IdentityAttribute.values vector.

On successful completion the handler MUST return com.qut.middleware.esoe.sessions.identity.pipeline.Handler.result.Successful

Query

Component Lead Bradley Beddoes
Package com.qut.middleware.esoe.sessions.impl.\*
Type QueryImpl
Implemented Interfaces com.qut.middleware.esoe.sessions.Query
Exceptions InvalidSessionIdentifierException

The query component is responsible for supplying information to ESOE about sessions which already exist within the system.

queryAuthnSession

This method takes the identifier assigned to the principal during authn. This identifier is used as a key to the local session cache.

Once located in the session cache the object of type com.qut.middleware.esoe.sessions.Principal should be returned to the caller. Should the identifier not exist in the cache the exception com.qut.middleware.esoe.sessions.InvalidSessionIdentifierException should be populated and thrown.

querySAMLSession

This method takes the identifier assigned to the principal as com.qut.middleware.esoe.sessions.Principal.samlAuthnIdentifier by the [authentication authority|#Authentication Authority Processor]. This identifier is used as a key to the local session cache.

Once located in the session cache the object of type com.qut.middleware.esoe.sessions.Principal should be returned to the caller. Should the identifier not exist in the cache the exception com.qut.middleware.esoe.sessions.exception.InvalidSessionIdentifierException should be populated and thrown.

Update

Component Lead Shaun Mangelsdorf
Package com.qut.middleware.esoe.sessions.impl.\*
Type UpdateImpl
Implemented Interfaces com.qut.middleware.esoe.sessions.Update
Exceptions InvalidEntityIdentifierException, InvalidSessionIdentifierException

The update component is responsible for updating the com.qut.middleware.esoe.sessions.Principal with new session information as the principal moves between the ESOE and the various SPEPs.

It exposes three methods, updateSAMLAuthnIdentifier, updateEntityList and updateEntitySessionIdentifierList.

updateSAMLAuthnIdentifier

This method takes a session identifier and SAML identifier and stores the value in the associated com.qut.middleware.esoe.sessions.Principal at the location com.qut.middleware.esoe.sessions.Principal.samlAuthnIdentifier

Once complete the retrieved com.qut.middleware.esoe.sessions.Principal should be restored in the session cache, however this time with its key set to com.qut.middleware.esoe.sessions.Principal.samlAuthnIdentifier, this will allow equally fast access to the object regardless of which identifier is presented to the ESOE componenets.

Should the identifier not exist in the cache the exception com.qut.middleware.esoe.sessions.InvalidSessionIdentifierException should be populated and thrown.

updateEntityList

This method takes a session identifier and entity identifier and stores the value in the associated com.qut.middleware.esoe.sessions.Principal at the location com.qut.middleware.esoe.sessions.Principal.activeEntities. This a hashmap which uses the descriptorID as a key and stores an object of type vector.

Should the identifier not exist in the cache the exception com.qut.middleware.esoe.sessions.exception.InvalidSessionIdentifierException should be populated and thrown.

updateEntitySessionIdentifierList

This method takes a session identifier, entity identifier and SAML session index and stores the value in the associated com.qut.middleware.esoe.sessions.Principal at the location com.qut.middleware.esoe.sessions.Principal.activeEntities. This a hashmap which uses the descriptorID as a key. The value should be ADDED to the vector referenced by the key.

Should the entity identifier not exist as a key in com.qut.middleware.esoe.sessions.Principal.activeEntities the exception com.qut.middleware.esoe.exception.InvalidEntityIdentifierException should be populated and thrown.

Should the identifier not exist in the cache the exception com.qut.middleware.esoe.sessions.exception.InvalidSessionIdentifierException should be populated and thrown.

Terminate

Component Lead Shaun Mangelsdorf
Package com.qut.middleware.esoe.sessions.impl.\*
Type CreateImpl
Implemented Interfaces com.qut.middleware.esoe.sessions.Terminate
Exceptions InvalidSessionIdentifierException

The terminate component is responsible for terminating sessions within the ESOE. It defines only a single public method terminateSession which takes a session identifier. This identifier is used as a key to the local session cache.

Once located in the session cache the object of type com.qut.middleware.esoe.sessions.Principal should be deleted. Should the identifier not exist in the cache the exception com.qut.middleware.esoe.sessions.exception.InvalidSessionIdentifierException should be populated and thrown.

Also available in: HTML TXT