This storage service is a drop-in replacement for the standard Shibboleth IdP storage service. It provides session persistence and sharing across multiple servers by using a database to persist session data. It is designed to continue to operate even when the database server is unavailable, it will simply require a login if the user's session does not happen to exist on the node servicing the request. All session related data must be Serializable by the JVM. The storage service does not persist the login context information to the database. You must use session affinity during the login process so that the user's session remains on a single server in the cluster.
The service itself uses Hibernate as the data access layer. It has been tested with MySQL and Oracle, but should work with other RDMS systems. You may need to modify the included index and trigger statements, they are written for MySQL. The table structure itself is generated during the Maven build as target/db-storage-service-tables.sql. The default settings are for MySQL 5.x. If you need another RDMS, then you will need to edit the src/main/conf/hibernate.properties file to reflect the proper dialect. You may configure the Hibernate database access at any level you desire that works with your container. Hibernate will search the class path for the file hibernate.properties to decide how it accesses the database. That properties file can contain the direct database access information (server, user, password), or can be configured to use a container managed connection. Please refer to the Hibernate website for detailed information on configuring Hibernate.
Only use of the storage service API is replaced by this. Artifact resolution and attribute query resolution for a transient identifier, regardless of SAML version, rely on a "session cache" API and will not be enabled in a clustered environment just by use of this storage service. |
The complete project is available from BitBucket Code Project.
Modify the Shibboleth web.xml file to load the filter for the storage service:
<!-- Add filter for storage service --> <!-- DB version --> <filter> <filter-name>ClareityStorageFilter</filter-name> <filter-class>net.clareitysecurity.shibboleth.storage.ClusterFilter</filter-class> </filter> <filter-mapping> <filter-name>ClareityStorageFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> |
Modify your Shibboleth internal.xml to load the new storage service:
<!-- The Clareity DB based storage service. You must disable all other storage services to use this one --> <bean id="shibboleth.StorageService" class="net.clareitysecurity.shibboleth.storage.DbStorageService" depends-on="shibboleth.LogbackLogging"> <constructor-arg value="shibboleth" /> <!-- this value separates systems --> <!-- optional argument to not run the storage cleanup thread <constructor-arg value="false" /> --> </bean> |
Optional. To be able to get logging messages, add this to your logging.xml file:
<logger name="net.clareitysecurity.shibboleth"> <level value="DEBUG" /> <appender-ref ref="IDP_PROCESS" /> </logger> |
A few additional notes:
Please direct all usage/support questions to the Shibboleth Users mailing list.
This code has been contributed under the Apache 2.0 license by Clareity Security.