Red Hat Training

A Red Hat training course is available for Red Hat JBoss Web Server

Chapter 16. Using Clustered Single Sign-on

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, 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.

16.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.

    Note

    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 16.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.