Sun OpenSSO Enterprise provides a web container-independent session failover feature that uses Sun Java™ System Message Queue, a messaging middleware product that enables distributed applications to communicate and exchange data by sending and receiving messages. OpenSSO Enterprise uses Message Queue as a communications broker, and the BerkeleyDB by Sleepycat Software, Inc. for backend session store databases. This chapter contains the following sections:
When session failover is implemented for OpenSSO Enterprise, session information is replicated in two backend session store databases. This ensures that if one OpenSSO Enterprise server fails or stops, the information stored in the backend session databases can be used to keep the user continuously authenticated. If session failover is not implemented and the OpenSSO Enterprise server in which a user's session was created fails, the user will have to reauthenticate to perform an operation that requires a session token.
For more information about OpenSSO Enterprise and session failover, see Chapter 7, Implementing OpenSSO Enterprise Session Failover, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.
Install the OpenSSO Enterprise session failover components on the mq-1 host machine and the mq-2 host machine. Use the following list of procedures as a checklist for completing the task.
As a root user, log in to the mq–1 host machine.
Create a directory into which the Message Queue and Berkeley Database bits can be downloaded and change into it.
# mkdir /export/SFO # cd /export/SFO |
Copy ssoSessionTools.zip from the osso–1 host machine to the mq–1 host machine.
ssoSessionTools.zip is included in the opensso_enterprise_80.zip file downloaded in To Generate an OpenSSO Enterprise WAR on the OpenSSO Enterprise 1 Host Machine under the tools directory.
Unzip ssoSessionTools.zip.
# cd /export/SFO # unzip ssoSessionTools.zip -d ssoSessionTools |
Modify the permissions on the setup script and run it to initialize the session failover tools.
# cd /export/SFO/ssoSessionTools # chmod +x setup # ./setup |
When prompted, enter opensso as the Directory to install the scripts (example: opensso).
The directory location should be relative to the current directory.
When the script is finished, the following messages are displayed:
The scripts are properly setup under directory /export/SFO/ssoSessionTools/opensso JMQ is properly setup under directory /export/SFO/ssoSessionTools/jmq |
Change to the bin directory.
# cd /export/SFO/ssoSessionTools/jmq/mq/bin |
Run the imqbrokerd command to create a new broker instance named msgqbroker.
# ./imqbrokerd -name msgqbroker -port 7777 & |
Run netstat to verify that the new Message Queue broker instance is up and running.
# netstat -an | grep 7777 *.7777 *.* 0 0 49152 0 LISTEN |
Add a new user named msgquser.
This user will connect to the Message Queue broker instance on servers where Message Queue is installed. This user will be used only for session failover purposes, and does not assume the privileges of the guest user. It is a good practice to create a custom user for such purposes, and not to rely on the known user accounts or default user accounts to help prevent brute force or DOS attacks.
# ./imqusermgr add -u msgquser -g admin -p m5gqu5er -i msgqbroker User repository for broker instance: msgqbroker User msgquser successfully added. |
Disable the guest user.
This step ensures that the guest user will not be able to access the OpenSSO Enterprise server.
# ./imqusermgr update -u guest -a false -i msgqbroker User repository for broker instance: msgqbroker Are you sure you want to update user guest? (y/n) y User guest successfully updated. |
Modify the amsfo.conf file.
amsfo.conf has parameters that are consumed by the OpenSSO Enterprise session failover startup script, amsfo.
Change to the lib directory.
# cd /export/SFO/ssoSessionTools/opensso/config/lib |
Backup amsfo.conf before you modify it.
Set the following properties:
CLUSTER_LIST=mq-1.example.com:7777,mq-2.example.com:7777 BROKER_INSTANCE_NAME=msgqbroker USER_NAME=msgquser BROKER_PORT=7777 |
The port used for BROKER_PORT should be the same as the one used in the value of the CLUSTER_LIST.
Save the file and close it.
Generate an encrypted password in a .password file with the following sub procedure.
Change to the bin directory.
# cd /export/SFO/ssoSessionTools/opensso/bin |
Run amsfopassword.
This command generates an encrypted password, creates a new file named .password, and stores the encrypted password in the new file.
amsfopassword creates the .password file in a default location based on where the scripts were installed. If a different location is used, the PASSWORDFILE property in amsfo.conf should be changed accordingly.
# ./amsfopassword -e m5gqu5er -f /export/SFO/ssoSessionTools/opensso/.password os.name=SunOS SUCCESSFUL |
(Optional) View the encrypted password for verification.
# more /export/SFO/ssoSessionTools/opensso/.password M27OGb6U4ufRu+oWAzBdWw== |
(Optional) Modify the amsessiondb script if necessary.
The amsessiondb script (located in the /export/SFO/ssoSessionTools/opensso/bin directory) starts the Berkeley Database client, creates the database, and sets specific database values. It is called when the amsfo script is run for the first time. The amsessiondb script contains variables that specify default paths and directories. If any of the following components are not installed in their default directories, edit the amsessiondb script to set the variables to the correct locations.
JAVA_HOME=/usr/jdk/entsys-j2se IMQ_JAR_PATH=/export/SFO/ssoSessionTools/jmq/mq/lib JMS_JAR_PATH=/export/SFO/ssoSessionTools/jmq/mq/lib AM_HOME=/export/SFO/ssoSessionTools |
Backup amsessiondb before you modify it.
Restart the session failover components with the following sub procedure.
Change to the bin directory.
# cd /export/SFO/ssoSessionTools/jmq/mq/bin |
Stop the Message Queue instance using the product's command line interface.
See the Message Queue documentation for more information.
Run the netstat command to verify that the mq-1 broker instance is stopped.
# netstat -an | grep 7777 |
If netstat returns no result, the mq-1 broker instance is stopped.
If the mq-1 broker instance is not stopped, kill the process using the following procedure.
Get the Java process IDs.
# ps -ef | grep java |
Kill the Java process IDs that were returned.
# kill -9 #### #### |
Run netstat again.
Restart the mq-1 broker instance.
# cd /export/SFO/ssoSessionTools/opensso/bin # ./amfso start |
Run the netstat command to verify that the Message Queue port is open and listening.
# netstat -an | grep 7777 *.7777 *.* 0 0 49152 0 LISTEN |
Log out of the mq-1 host machine.
As a root user, log in to the mq–2 host machine.
Create a directory into which the Message Queue and Berkeley Database bits can be downloaded and change into it.
# mkdir /export/SFO # cd /export/SFO |
Copy ssoSessionTools.zip from the osso–1 host machine to the mq–2 host machine.
ssoSessionTools.zip is included in the opensso_enterprise_80.zip file downloaded in To Generate an OpenSSO Enterprise WAR on the OpenSSO Enterprise 1 Host Machine under the tools directory.
Unzip ssoSessionTools.zip.
# cd /export/SFO # unzip ssoSessionTools.zip -d ssoSessionTools |
Modify the permissions on the setup script and run it to initialize the session failover tools.
# cd /export/SFO/ssoSessionTools # chmod +x setup # ./setup |
When prompted, enter opensso as the Directory to install the scripts (example: opensso).
The directory location should be relative to the current directory.
When the script is finished, the following messages are displayed:
The scripts are properly setup under directory /export/SFO/ssoSessionTools/opensso JMQ is properly setup under directory /export/SFO/ssoSessionTools/jmq |
Change to the bin directory.
# cd /export/SFO/ssoSessionTools/jmq/mq/bin |
Run the imqbrokerd command to create a new broker instance named msgqbroker.
# ./imqbrokerd -name msgqbroker -port 7777 & |
Run netstat to verify that the new Message Queue broker instance is up and running.
# netstat -an | grep 7777 *.7777 *.* 0 0 49152 0 LISTEN |
Add a new user named msgquser.
This user will connect to the Message Queue broker instance on servers where Message Queue is installed. This user will be used only for session failover purposes, and does not assume the privileges of the guest user. It is a good practice to create a custom user for such purposes, and not to rely on the known user accounts or default user accounts to help prevent brute force or DOS attacks.
# ./imqusermgr add -u msgquser -g admin -p m5gqu5er -i msgqbroker User repository for broker instance: msgqbroker User msgquser successfully added. |
Disable the guest user.
This step ensures that the guest user will not be able to access the OpenSSO Enterprise server.
# ./imqusermgr update -u guest -a false -i msgqbroker User repository for broker instance: msgqbroker Are you sure you want to update user guest? (y/n) y User guest successfully updated. |
Modify the amsfo.conf file with the following sub procedure.
amsfo.conf has parameters that are consumed by the OpenSSO Enterprise session failover startup script, amsfo.
Change to the lib directory.
# cd /export/SFO/ssoSessionTools/opensso/config/lib |
Backup amsfo.conf before you modify it.
Set the following properties:
CLUSTER_LIST=mq-1.example.com:7777,mq-2.example.com:7777 BROKER_INSTANCE_NAME=msgqbroker USER_NAME=msgquser BROKER_PORT=7777 |
The port used for BROKER_PORT should be the same as the one used in the value of the CLUSTER_LIST.
Save the file and close it.
Generate an encrypted password in a .password file with the following sub procedure.
Change to the bin directory.
# cd /export/SFO/ssoSessionTools/opensso/bin |
Run amsfopassword.
This command generates an encrypted password, creates a new file named .password, and stores the encrypted password in the new file.
amsfopassword creates the .password file in a default location based on where the scripts were installed. If a different location is used, the PASSWORDFILE property in amsfo.conf should be changed accordingly.
# ./amsfopassword -e m5gqu5er -f /export/SFO/ssoSessionTools/opensso/.password os.name=SunOS SUCCESSFUL |
(Optional) View the encrypted password for verification.
# more /export/SFO/ssoSessionTools/opensso/.password M27OGb6U4ufRu+oWAzBdWw== |
(Optional) Modify the amsessiondb script if necessary.
The amsessiondb script (located in the /export/SFO/ssoSessionTools/opensso/bin directory) starts the Berkeley Database client, creates the database, and sets specific database values. It is called when the amsfo script is run for the first time. The amsessiondb script contains variables that specify default paths and directories. If any of the following components are not installed in their default directories, edit the amsessiondb script to set the variables to the correct locations.
JAVA_HOME=/usr/jdk/entsys-j2se IMQ_JAR_PATH=/export/SFO/ssoSessionTools/jmq/mq/lib JMS_JAR_PATH=/export/SFO/ssoSessionTools/jmq/mq/lib AM_HOME=/export/SFO/ssoSessionTools |
Backup amsessiondb before you modify it.
Restart the session failover components.
Change to the bin directory.
# cd /export/SFO/ssoSessionTools/jmq/mq/bin |
Stop the Message Queue instance using the product's command line interface.
See the Message Queue documentation for more information.
Run the netstat command to verify that the mq-2 broker instance is stopped.
# netstat -an | grep 7777 |
If netstat returns no result, the mq-2 broker instance is stopped.
If the mq-2 broker instance is not stopped, kill the process using the following procedure.
Get the Java process IDs.
# ps -ef | grep java |
Kill the Java process IDs that were returned.
# kill -9 #### #### |
Run netstat again.
Restart the mq-2 broker instance.
# cd /export/SFO/ssoSessionTools/opensso/bin # ./amfso start |
Run the netstat command to verify that the Message Queue port is open and listening.
# netstat -an | grep 7777 *.7777 *.* 0 0 49152 0 LISTEN |
Log out of the mq-2 host machine.
Use the following list of procedures as a checklist for completing this task.
Access https://osso-1.example.com:1081/opensso/console from a web browser.
Log in to the OpenSSO Enterprise console as the administrator.
amadmin
ossoadmin
Click the Configuration tab.
Under Global properties, click Session.
Under Secondary Configuration Instance, click New.
In the Add Sub Configuration page, provide the following information.
Select External
Enter msgquser
Enter m5gqu5er
Enter m5gqu5er
Keep the default value of 5000.
Enter mq-1.example.com:7777,mq-2.example.com:7777.
This is the Message Queue broker address list. Enter multiple values using a comma and no space.
Click Add.
Click Save.
Log out of the OpenSSO Enterprise console.
Restart the Application Server 1 instance with the following sub procedure.
As a root user, log in to the osso–1 host machine.
Switch to the non-root user and change to the bin directory.
# su osso80adm # cd /export/osso80adm/domains/ossodomain/bin |
Restart the Application Server 1 instance.
# ./stopserv; ./startserv admin username:domain2adm admin password:domain2pwd master password:domain2master Redirecting output to /export/osso80adm/domains/ossodomain/logs/server.log |
Log out of the osso–1 host machine.
Restart the Application Server 2 instance with the following sub procedure.
As a root user, log in to the osso–2 host machine.
Switch to the non-root user and change to the bin directory.
# su osso80adm # cd /export/osso80adm/domains/ossodomain/bin |
Restart the Application Server 2 instance.
# ./stopserv; ./startserv admin username:domain2adm admin password:domain2pwd master password:domain2master Redirecting output to /export/osso80adm/domains/ossodomain/logs/server.log |
Log out of the osso-2 host machine.
Both OpenSSO Enterprise 1 and OpenSSO Enterprise 2 should be up and running before you begin this verification procedure.
As a root user, log in to the osso–2 host machine.
Change to the bin directory.
# cd /export/osso80adm/domains/ossodomain/bin |
Stop OpenSSO Enterprise 2.
# ./stopserv |
Access https://lb-2.example.com:1081/opensso/console from a web browser.
Log in to the OpenSSO Enterprise console as the administrator.
amadmin
ossoadmin
Click the Sessions tab.
In the View field, select osso-1.example.com:1081 from the drop down list.
Verify that only amadmin exists in the Sessions table.
In the View field, select osso-2.example.com:1081 from the drop down list.
You will see an error message indicating the server is down.
Leave this browser window 1 open.
Start OpenSSO Enterprise 2.
# ./startserv admin username:domain2adm admin password:domain2pwd master password:domain2master Redirecting output to /export/osso80adm/domains/ossodomain/logs/server.log |
As a root user, log in to the osso-1 host machine.
Change to the bin directory.
# cd /export/osso80adm/domains/ossodomain/bin |
Stop OpenSSO Enterprise 1.
# ./stopserv |
Going back to the OpenSSO Enterprise console in browser window 1, under the Sessions tab, select osso-1.example.com:1081 from the View drop down list.
You will see an error message indicating the server is down.
Now select osso-2.example.com:1081 from the View drop down list.
Verify that only amadmin exists in the Sessions table. This indicates that although OpenSSO Enterprise 1 was stopped, the OpenSSO Enterprise Load Balancer 2 directed the request to OpenSSO Enterprise 2 and a session for amadmin was successfully created by OpenSSO Enterprise 2. If session failover was not enabled, it would have resulted in a login page.
This procedure assumes that you have just completed To Verify That the Administrator Session Fails Over.
Access https://lb-2.example.com:1081/opensso/UI/Login from a second browser window.
Log in to the OpenSSO Enterprise console as testuser1.
testuser1
password
A page with a message that reads You're logged in is displayed. Since the User Profile attribute was set to Ignored, the user's profile is not displayed following a successful login. Because OpenSSO Enterprise 1 was stopped, the user session is created in OpenSSO Enterprise 2.
Leave browser window 2 open.
Using browser window 1, click the Sessions tab.
In the View field, select osso-2.example.com:1081 from the drop down list.
Verify that amadmin and testuser1 exist in the Sessions table.
On the osso–1 host machine, change to the bin directory.
# cd /export/osso80adm/domains/ossodomain/bin |
Start OpenSSO Enterprise 1.
# ./startserv |
Both OpenSSO Enterprise 1 and OpenSSO Enterprise 2 are up and running.
On the osso–2 host machine, change to the bin directory.
# cd /export/osso80adm/domains/ossodomain/bin |
Stop OpenSSO Enterprise 2.
# ./stopserv |
Using browser window 1, click the Sessions tab and do the following sub procedure.
In the View field, select osso-1.example.com:1081.
Verify that amadmin and testuser1 exist in the Sessions table. This indicates that the session successfully failed over to OpenSSO Enterprise 1.
If testuser1 is not displayed, refresh the browser window 2 page.
In the View field, select osso-2.example.com:1081
You will see an error message indicating the server is down.
Log out of the consoles and the host machines.