Installation guide

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, 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.
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. T he 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:
cla ssName 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 .
treeCache Name 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. T he 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. T he 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 backup copy of the session. Default is 1800, (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 will not occur more frequently than that.
Default is 60.
requireReaut henticat ion 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.
19.2. SSO behavior
The user will not be challenged as long as they access only unprotected resources in any of the web
applications on the virtual host.
Upon access to a protected resource in any web app, the user will be challenged to authenticate, using
the log in method defined for the web app.
Once authenticated, the roles associated with this user will be utilized for access control decisions
across all of the associated web applications, without challenging the user to authenticate themselves to
each application individually.
If the web application invalidates a session (by invoking the
javax.servlet.http.HttpSession.invalidate() method), the user's sessions in all web
applications will be invalidated.
76 Chapter 19. Using clustered Single Sign-on (SSO)