Red Hat Training

A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification

22.4. Using Clustered Single Sign-on (SSO)

JBoss supports clustered single sign-on, allowing a user to authenticate to one web application and to be recognized on all web applications that are deployed on the same virtual host, whether or not they are deployed on that same machine or on another node in the cluster. Authentication replication is handled by JBoss Cache. Clustered single sign-on support is a JBoss-specific extension of the non-clustered org.apache.catalina.authenticator.SingleSignOn valve that is a standard part of Tomcat and JBoss Web. Both the non-clustered and clustered versions allow users to sign on to any one of the web apps associated with a virtual host and have their identity recognized by all other web apps on the same virtual host. The clustered version brings the added benefits of enabling SSO failover and allowing a load balancer to direct requests for different webapps to different servers, while maintaining the SSO.

22.4.1. Configuration

To enable clustered single sign-on, you must add the ClusteredSingleSignOn valve to the appropriate Host elements of the JBOSS_HOME/server/all/deploy/jbossweb.sar/server.xml file. The valve element is already included in the standard file; you just need to uncomment it. The valve configuration is shown here: 
<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" />
The element supports the following attributes:
  • className is a required attribute to set the Java class name of the valve implementation to use. This must be set to org.jboss.web.tomcat.service.sso.ClusteredSingleSign.
  • cacheConfig is the name of the cache configuration (see Section 18.2.1, “The JBoss Enterprise Application Platform CacheManager Service”) to use for the clustered SSO cache. Default is clustered-sso.
  • treeCacheName is deprecated; use cacheConfig. Specifies a JMX ObjectName of the JBoss Cache MBean to use for the clustered SSO cache. If no cache can be located from the CacheManager service using the value of cacheConfig, an attempt to locate an mbean registered in JMX under this ObjectName will be made. Default value is jboss.cache:service=TomcatClusteringCache.
  • cookieDomain is used to set the host domain to be used for sso cookies. See Section 22.4.4, “Configuring the Cookie Domain” for more. Default is "/".
  • maxEmptyLife is the maximum number of seconds an SSO with no active sessions will be usable by a request. The clustered SSO valve tracks what cluster nodes are managing sessions related to an SSO. A positive value for this attribute allows proper handling of shutdown of a node that is the only one that had handled any of the sessions associated with an SSO. The shutdown invalidates the local copy of the sessions, eliminating all sessions from the SSO. If maxEmptyLife were zero, the SSO would terminate along with the local session copies. But, backup copies of the sessions (if they are from clustered webapps) are available on other cluster nodes. Allowing the SSO to live beyond the life of its managed sessions gives the user time to make another request which can fail over to a different cluster node, where it activates the the backup copy of the session. Default is 1800, i.e. 30 minutes.
  • processExpiresInterval is the minimum number of seconds between efforts by the valve to find and invalidate SSO's that have exceeded their 'maxEmptyLife'. Does not imply effort will be spent on such cleanup every 'processExpiresInterval', just that it won't occur more frequently than that. Default is 60.
  • requireReauthentication is a flag to determine whether each request needs to be reauthenticated to the security Realm. If "true", this Valve uses cached security credentials (username and password) to reauthenticate to the JBoss Web security Realm each request associated with an SSO session. If false, the valve can itself authenticate requests based on the presence of a valid SSO cookie, without rechecking with the Realm. Setting to true can allow web applications with different security-domain configurations to share an SSO. Default is false.