Version 21

    The JBoss web tier offers basic single-sign-on support for web clients, using a mechanism based on Tomcat valves.  This SSO solution comes in two flavors, clustered and non-clustered:


    Non-Clustered SSO


    This is provided using the standard Tomcat SingleSignOn valve. Non-clustered SSO allows users to:


    • sign on to any one of the web apps associated with a virtual host

    • have their identity recognized by all other web apps on the same virtual host.


    This is a single server solution; if there is a cluster the SSO is not propagated to other cluster nodes.  Therefore, if a user fails over to another server or the load balancer directs a request for another webapp to another server, the SSO context will not be available and the user will have to log in again.



    In the deploy/jbossweb.sar/server.xml file, inside the Host element of any virtual hosts for which you want single sign-on support, uncomment the following element:


    <Valve className="org.apache.catalina.authenticator.SingleSignOn"/>


    The element supports the following attributes:




    Java class name of the valve implementation to use.  This MUST be set to org.apache.catalina.authenticator.SingleSignOn or to org.jboss.web.tomcat.service.sso.ClusteredSingleSign.
    requireReauthenticationFlag 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 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. In early releases (e.g. 3.2.3), setting this to "true" was required to allow for propagation of the web app security context to the ejb container and other secured resources, although that requirement was soon eliminated. Default is "false".

    Since 4.0.4. Sets the host domain to be used for sso cookies. See "Configuring the Cookie Domain" below.

    debug4.0.2 and earlier; since eliminated; see "SSO Valve Logging" below. Specifies the detail level of debugging messages created by the valve. By default, this was set to zero (0), which means no debug output. A value of two (2) produces a large amount of output, similar to DEBUG or TRACE level logging with Log4j.



    Clustered SSO


    Beginning with the JBoss-3.2.4 release, JBoss AS supports single sign-on to web applications across a cluster, using JBoss Cache for SSO credential caching and replication.  This feature uses the org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn valve, which extends the functionality of the standard Tomcat SSO valve to allow the SSO to span multiple nodes in a cluster.


    • Enables SSO failover

    • Allows a load balancer to direct requests for different webapps to different servers, while maintaining the SSO.




    In the jbossweb.sar/server.xml file, inside the Host element of any virtual hosts for which you want single sign-on support, uncomment the following element:


    <Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn"/>             </Valve>


    If using the ClusteredSingleSignOn valve, be sure the standard single sign on valve described above is commented out.


    In addition to the non-clustered SSO valve configuration attributes described above, the clustered valve supports the following attributes:


    Header 1Header 2
    cacheConfigSince 5.0.0. Name of the CacheManager service cache configuration to use for the clustered SSO cache. Default is clustered-sso.
    treeCacheNameDeprecated; use cacheConfig. JMX ObjectName of the JBossCache MBean used to support credential caching and replication across the cluster. If no cache can be located from the CacheManager service using cacheConfig, an attempt to locate an mbean registered under this name will be made. Default value is jboss.cache:service=TomcatClusteringCache.
    maxEmptyLifeSince 4.0.5. 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 <distributable/> 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 activate the the backup copy of the session. Default is 1800, i.e. 30 minutes.
    processExpiresIntervalThe 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.




    SSO Behavior (clustered and non-clustered)


    The user will not be challenged as long as he accesses 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 login 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 user logs out of one web application (for example, by invalidating the corresponding session if form based login is used), the user's sessions in all web applications will be invalidated.


    A session timeout does not invalidate the SSO if other sessions are still valid.




    There are a number of known limitations to this Tomcat valve-based SSO implementation:


    • Only useful within a cluster of JBoss Web servers; SSO does not propagate to other resources.


    • Requires use of container managed authentication (via <login-config> element in web.xml)


    • Requires Cookies.  SSO is maintained via a cookie and URL rewriting is not supported.


    • Prior to release 4.0.4.CR2, the SSO cookie is scoped to a single hostname (i.e. "/").


    • Unless requireReauthentication is set to true, all web applications configured for the same SSO valve must share the same JBoss Web Realm and JBoss Security security-domain.
      • So, you can nest the Realm element inside the Host element (or the surrounding Engine element), but not inside a context.xml element for one of the involved web applications.

      • The security-domain configured in jboss-web.xml or jboss-app.xml must be consistent for all of the web applications.
      • Even if you set requireReauthentication to true and use a different security-domain (or, less likely, a different Realm) for different webapps, the varying security integrations must all accept the same credentials (e.g. username and password).


    Configuring the Cookie Domain


    Beginning with JBoss 4.0.4.CR2, a new cookieDomain configuration attribute has been added to the Tomcat SSO valve (and inherited by the ClusteredSingleSignOn subclass).  This attribute allows configuration of the SSO cookie's domain (i.e. the set of hosts to which the browser will present the cookie).  By default the domain is "/", meaning the browser will only present the cookie to the host that issued it.  The cookieDomain attribute allows the cookie to be scoped to a wider domain.


    For example, suppose we have a case where two apps, with URLs and, that wish to share an SSO context. These apps could be running on different servers in a cluster (if ClusteredSingleSignOn is used) or the virtual host with which they are associated could have multiple aliases. This can now be supported with the following configuration:


    <Valve className="org.apache.catalina.authenticator.SingleSignOn"


    or, for the clustered case


    <Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn"


    In versions prior to 4.0.4, if a company wanted to use SSO across two webapps:




    SSO Valve Logging


    Beginning with JBoss 4.0.2, the debug attribute discussed above was disabled in the standalone Tomcat SingleSignOn valve and in the ClusteredSingleSignOn valve.  The valve's logging is now controlled via the jboss-log4j.xml (fka log4j.xml) file in the JBoss conf folder.  Unfortunately, the log category that controls the valve is a little obscure -- the valve shares a logger with the Tomcat container that contains it.  Use the following to get DEBUG level logging:


    <category name="org.apache.catalina.core.ContainerBase">
       <priority value="DEBUG"></priority>


    This will log somewhat more than just the SSO valve's output, but not excessively so.


    Check KeyJBossSubsystemCategories for more information on categories needed to debug SSO issues.


    Clustered SSO With Just One Application: Solving the "Must Login After Session Failover" Problem


    The ClusteredSingleSignOn valve can be useful even when only a single web application is deployed. This is because, since it uses a replicated cache of authentication credentials, it provides a workaround to the problem where if the server handling a user's clustered web session fails or is shut down, when the user fails over to another server their replicated session data is available but they are forced to log in again. (See JBAS-1900). If the ClusteredSingleSignOn valve is configured, the user will not have to log in again.


    Change History


    The above discussion is focused on the most recent JBoss AS release. A number of configuration and behavior changes have been added over the years, so with earlier releases things may work somewhat differently. The following summarizes the changes:


    JBoss 5.0.0


    Beginning with JBoss 5.0.0 the server.xml file is found in the deploy/jbossweb.sar directory. The cacheConfig attribute and CacheManager service integration was added to Clustered SSO, and treeCacheName was deprecated.

    JBoss 4.2.0


    Beginning with JBoss 4.2.0 the server.xml file is found in the deploy/jboss-web.deployer directory. The package name of the ClusteredSingleSignOn class was changed from the original org.jboss.web.tomcat.tc5.sso to org.jboss.web.tomcat.service.sso.


    JBoss 4.0.5


    That maxEmptyLife and processExpiresInterval attributes were added to the ClusteredSingleSignOn valve, along with the associated behavior described above.


    Buddy replication was introduced for the HttpSession replication service, although not enabled by default.  If buddy replication is enabled in the cache used for session replication, the Clustered SSO valve should be configured to use a separate JBoss Cache instance, as buddy replication is generally not a valid configuration for a Clustered SSO cache. See "Buddy replication and Clustered SSO" discussion below.


    JBoss 4.0.4


    Configuration of the cookieDomain added; prior to this the SSO cookie was always scoped to the individual host.

    JBoss 4.0.2


    The server.xml file is found in the deploy/jbossweb-tomcat55.sar directory.


    Logging changes introduced, eliminating the "debug" attribute on the valve. Logging now comes from the org.apache.catalina.core.ContainerBase category, as discussed above.


    JBoss 3.2.6 and 4.0


    Beginning with the JBoss-3.2.6 and 4.0 releases, the ClusteredSingleSignOn valve by default shares a JBossCache MBean with the clustered Http Session replication service.  This means users do not themselves need to deploy a cache (e.g. the attached tc5-cluster-service.xml file); it is already deployed as part of the standard JBoss "all" configuration.


    Setting the treeCacheName attribute is no longer necessary, as the valve defaults to using the JBossCache MBean deployed via the tc5-cluster-service.xml file found in the server/all/deploy directory.  If you wish to use a different JBossCache MBean, the configuration method used in JBoss-3.2.4 is still available; just deploy a service.xml file for your JBossCache and set the clustered single sign on valve's treeCacheName attribute to point to it.

    JBoss 3.2.4


    The server.xml file is found in the deploy/jbossweb-tomcat50.sar directory.  The security propagation fix from JBoss 3.2.3 was ported into the regular Tomcat org.apache.catalina.authenticator.SingleSignOn

    valve, so there is no longer any reason to use the special JBoss patched version (see "JBoss 3.2.3" below).


    ClusteredSingleSignOn valve introduced. For this release through the AS 4.0.x series, the classname of the valve is org.jboss.web.tomcat.tc5.sso.ClusteredSingleSignOn. Valve depends on the existence of a JBossCache MBean, but the cache is not deployed as part of any standard JBoss configuration; users must deploy it themselves. An example service.xml file for such an MBean is attached to this page; to deploy the JBossCache MBean, just copy the attached file to the server/all/deploy directory.  Note that the value of the treeCacheName attribute of Clustered Single Sign On valve element in server.xml must be set and must match the JMX object name of the JBossCache MBean.


    JBoss 3.2.3


    The Tomcat SSO behavior was updated to allow for propagation of the web app security context to the ejb container and other secured resources. To get this behavior in this release, use a special JBoss patched version of the standard Tomcat SSO valve by using the following valve config:


    <Valve className="org.jboss.web.tomcat.tc4.authenticator.SingleSignOn" debug="0"/>


    For this release and earlier releases, no server.xml was used. Rather an equivalent configuration was declared inside the jbossweb-tomcat41.sar/META-INF/jboss-service.xml file



    Other Issues


    Buddy replication and Clustered SSO


    Buddy replication is a feature available for HttpSession replication beginning in 4.0.5.  Clustered SSO will generally not work properly if buddy replication is enabled for the cache that the Clustered SSO valve by default shares with the HttpSession replication service.  If buddy replication is enabled Clustered SSO will need to use a separate cache; see above for how to configure that.  The Buddy replication and Clustered SSO page has further details on why buddy replication is generally inappropriate for Clustered SSO.


    The exception to the above statement is when Clustered SSO is used solely as a workaround to the "Must Login After Session Failover" problem (JBAS-1900) as described above and only a single webapp is deployed. In this case, buddy replication for the SSO cache can work, because, since there is only one webapp and sticky-sessions are used, all requests for a given SSO will be handled by a single server. The problem of different servers fighting for ownership of the SSO data described on the Buddy replication and Clustered SSO page will not occur.


    Custom Principals and ClassLoader-issues


    If you use custom principal implementations in your login modules in isolated EAR-files, you need to make sure that their classloaders will use exactly the  same  library.

    You can guarantee this by putting the principal object (and other associated objects) into server/default/lib directory and removing them from your WAR/EAR files.

    You can track this by looking into the isolated loader-repositories in the JMX-console and make sure the libraries used are located in server/default/lib.


    Mixing Authentication Schemes


    (Note: the following discussion is only relevant if requireReauthentication is set to true).


    There are some differences between the way SSO works and the way the standard Tomcat valve works in standalone Tomcat in a situation where different webapps under the same virtual host use different authentication schemes. In this scenario JBoss requires that each request from the user be reauthenticated, so requireReauthentication must be set to true. Therefore when each request comes in, the SingleSignOn valve needs to have available in its cache sufficient security information to reauthenticate the user.


    If when accessing a virtual host the user first visits a webapp that uses FORM or BASIC authentication, and then they visit another webapp that requires DIGEST, the cached username/password from the FORM/BASIC authentication will not be sufficient information to do a digest authentication, so the user will be prompted for a digest login. Once a digest login succeeds, the browser automatically sends authentication information with each request, so thereafter the user can switch between DIGEST and FORM/BASIC webapps without issue.