Chapter 16. Single Sign-on in a Cluster
In a cluster, the JBoss SSO valve can be used to authenticate a user on one portal node and have that authentication automatically carried across to other nodes in the cluster.
The JBoss SSO valve is enabled by default through the following JBoss Web subsystem configuration entry in the
JPP_HOME/standalone/configuration/standalone-ha.xml file:
<sso cache-container="web" cache-name="sso" reauthenticate="false" />
When a load balancer is used in a cluster, no further configuration is needed to set up single sign-on. All portal servers in the cluster are accessed through the same URL, which is the URL of the load balancer. Automatic single sign-on is performed when the load balancer redirects client requests to individual nodes in the cluster.
16.1. Clustered Single Sign-on in a Shared DNS Domain
If multiple portal servers are accessed through different URLs in the same DNS domain, single sign-on can be configured by adding the
domain parameter to the sso configuration entry.
<sso cache-container="web" cache-name="sso" reauthenticate="false" domain="yourdomain.com"/>
The parameter must be added to the entry on all servers in the cluster and the name of the shared DNS domain must be specified as its value. This configuration ensures that the
JSESSIONIDSSO cookie will be scoped to the specified domain, which is otherwise scoped only to the host where the initial authentication was performed.
16.1.1. Configuring and Testing Single Sign-on in a Shared DNS Domain
This procedure demonstrates the configuration and testing of single sign-on for two portal server instances running in a shared domain on a single physical Linux machine.
It is expected that each instance is installed in a separate directory in the machine's file system, and that the
192.168.210.101 and 192.168.210.102 virtual IP addresses are available on the machine.
- Map the IP addresses to domain names within the same domain by adding the following lines to the /etc/hosts file:
192.168.210.101 machine1.yourdomain.com 192.168.210.102 machine2.yourdomain.com
- Open the
JPP_HOME/standalone/configuration/standalone-ha.xmlfile on both instances, add thedomainparameter to thessoentry and specify the name of the shared DNS domain in its value: <sso cache-container="web" cache-name="sso" reauthenticate="false" domain="yourdomain.com"/>
- By default, the
standalone-ha.xmlfile is configured to use a shared H2 database, which is intended to be used only for testing purposes. Start the database by issuing the following command in the JPP_HOME directory of the first instance:java -cp modules/com/h2database/h2/main/h2-<VERSION>.jar org.h2.tools.Server
- Start the first instance by issuing the following command in its
JPP_HOME/bin/directory:./standalone.sh -b machine1.yourdomain.com -c standalone-ha.xml -Djboss.node.name=node1
- Start the second instance by issuing the following command in its
JPP_HOME/bin/directory:./standalone.sh -b machine2.yourdomain.com -c standalone-ha.xml -Djboss.node.name=node2
- Access the first instance at http://machine1.yourdomain.com:8080/portal and log in as a user.
- Access the second instance at http://machine2.yourdomain.com:8080/portal. When the page loads, you will be automatically logged in with the same user account that you used on the first server.
- Log out on any of the two instances. Then switch to the other instance and verify that you have been logged out of it as well.
16.2. Reauthentication
The JBoss SSO valve can also be used to authenticate with any other web application. If that application uses the same roles as the main portal instance, no further configuration is required. Because the JBoss SSO valve includes the same JAAS principal in all HTTP requests, even in requests to other web applications, matching roles ensure successful authentication with those applications.
To enable single sign-on authentication with an application that uses different roles, set the
reauthenticate parameter of the sso JBoss Web subsystem configuration entry to true.
<sso cache-container="web" cache-name="sso" reauthenticate="true" />
The
true value ensures that re-authentication with user credentials will be performed against the web application's security domain in each HTTP request. This will enforce creation of a new principal with updated roles for the web application. As user credentials are used for authentication in this case, it is required that the same user credentials exist in both the web application and the portal instance.