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.

Configuration:

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:

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.

Configuration:

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:

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.

Limitations

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 http://app1.xyz.com and http://app2.xyz.com, 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"
       cookieDomain="xyz.com"/>

or, for the clustered case

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

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

• SSO will work if URLs like the following are used:

  • http://www.xyz.com/app1

  • http://www.xyz.com/app2

• SSO will not work if the apps use different hostnames:

  • http://app1.xyz.com

  • http://app2.xyz.com

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>
</category>

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.