In eXo Platform 4, Cluster mode is temporarily not available for Tomcat. This content is for JBoss only. eXo Platform is trying best to support Clustering mode for Tomcat soon.
In the cluster mode, the eXo Platform SSO valve can be used to authenticate a user on one eXo Platform node and have that authentication automatically carried across to other nodes in the cluster.
Clustered SSO with Load Balancer
If you are running the cluster mode with Apache Load Balancer, you are using the same URL to access the servers
(which is actually URL of the Load Balancer).
You need to enable SSO by modifying the $PLATFORM_JBOSS_HOME/standalone/configuration/standalone-exo-cluster.xml file, as follows:
Find subsystem that has xmlns="urn:jboss:domain:web:1.4". It looks like:
<subsystem xmlns="urn:jboss:domain:web:1.4" default-virtual-server="default-host" native="false">
<connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
<connector name="ajp" protocol="AJP/1.3" scheme="http" socket-binding="ajp"/>
<virtual-server name="default-host" enable-welcome-root="true">
<alias name="localhost"/>
<alias name="example.com"/>
</virtual-server>
</subsystem>
Add <sso cache-container="web" cache-name="sso" reauthenticate="false" /> right after <alias name="example.com"/>. This will be:
<subsystem xmlns="urn:jboss:domain:web:1.4" default-virtual-server="default-host" native="false">
<connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
<connector name="ajp" protocol="AJP/1.3" scheme="http" socket-binding="ajp"/>
<virtual-server name="default-host" enable-welcome-root="true">
<alias name="localhost"/>
<alias name="example.com"/>
<sso cache-container="web" cache-name="sso" reauthenticate="false" />
</virtual-server>
</subsystem>
Clustered SSO in a Shared DNS Domain
If you are accessing the servers through different URLs in the same DNS domain, Single Sign-On can be configured by adding the domain parameter to the SSO configuration entry.
Let's see what is the difference. In case Load Balancer is used (described above):
<sso cache-container="web" cache-name="sso" reauthenticate="false" />
In this case:
<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.
The following example demonstrates how to simulate and test this case on a Linux machine. There are 2 nodes in the cluster.
Configuring and testing SSO in a shared DNS Domain
Add the following lines to the /etc/hosts file:
127.0.1.1 machine1.yourdomain.com 127.0.1.2 machine2.yourdomain.com
On both servers, modify the $PLATFORM_JBOSS_HOME/standalone/configuration/standalone-exo-cluster.xml file to have:
<subsystem xmlns="urn:jboss:domain:web:1.4" default-virtual-server="default-host" native="false">
<connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
<connector name="ajp" protocol="AJP/1.3" scheme="http" socket-binding="ajp"/>
<virtual-server name="default-host" enable-welcome-root="true">
<alias name="localhost"/>
<alias name="example.com"/>
<sso cache-container="web" cache-name="sso" reauthenticate="false" domain="yourdomain.com"/>
</virtual-server>
</subsystem>
Start the first server using the following command:
./standalone.sh -b machine1.yourdomain.com -c standalone-exo-cluster.xml -Djboss.node.name=node1
Start the second server using:
./standalone.sh -b machine2.yourdomain.com -c standalone-exo-cluster.xml -Djboss.node.name=node2
Access the first server at http://machine1.yourdomain.com:8080/portal and sign in.
Access the second server at http://machine2.yourdomain.com:8080/portal and test that you are automatically signed in.
Sign out from one server and test that you are automatically signed out from the other one.
Re-authentication
The eXo Platform SSO valve can also be used to authenticate with any other web application. If that application uses the same roles as the main eXo Platform instance, no further configuration is required. Because the eXo Platform 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 the single sing-on authentication with an application that uses different roles, you need to set the
reauthenticate parameter of the sso eXo Platform Web subsystem
configuration entry to true:
<sso cache-container="web" cache-name="sso" reauthenticate="true" />
The true value ensures that reauthentication 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 JBoss Portal Platform instance.