Chapter 19. Using clustered Single Sign-on (SSO)

JBoss supports clustered single sign-on (SSO), 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, regardless of whether 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.

19.1. Configuration

To enable clustered single sign-on, you must add the ClusteredSingleSignOn valve to the appropriate Host elements of the JBOSS_HOME/server/PROFILE/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 to use for the clustered SSO cache. Default is clustered-sso.


    For more information about cache configuration, refer to The JBoss Enterprise Application Platform CacheManager Service section in the Administration and Configuration Guide .
  • 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 19.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 which cluster nodes are managing sessions related to an SSO. When a node is shutdown, all local copies of a session are invalidated. If a further user request is made within the time specified by maxEmptyLife, the request will fail over to another cluster node, activating the backup copy of the session. If maxEmptyLife is set to 0, the SSO valve terminates together with the local session copies. Default is 1800, (30 minutes).
  • processExpiresInterval is the minimum number of seconds between efforts by the valve to find and invalidate SSOs that have exceeded their maxEmptyLife. Does not imply effort will be spent on such cleanup every processExpiresInterval, just that it will not 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 for 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.