test

Deployment Example 1: Access Manager 7.1 Load Balancing, Distributed Authentication UI, and Session Failover

Chapter 11 Implementing Session Failover

Sun Java™ System Access Manager provides a web container-independent session failover feature that uses Sun Java System Message Queue. Message Queue is a messaging middleware product that enables distributed applications to communicate and exchange data by sending and receiving messages. Access Manager uses Message Queue as a communications broker, and uses the Berkeley DB by Sleepycat Software, Inc. for the backend session store databases. This chapter contains the following sections:

11.1 Session Failover Architecture

When session failover is implemented for Access Manager, session information is replicated in two backend session store databases. This ensures that if one Access Manager 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 Access Manager 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. The following diagram illustrates the session failover architecture.

Figure 11–1 Session Failover

The Message Queue Broker cluster contains two Message Queue servers. Each Message Queue server contains a Berkeley database.

Note –

For more information about Access Manager and session failover, see Chapter 6, Implementing Session Failover, in Sun Java System Access Manager 7.1 Postinstallation Guide.

11.2 Installing the Access Manager Session Failover Components

Use the following list of procedures as a checklist for installing the Access Manager session failover components.

  1. To Install Access Manager Session Failover Components on Message Queue 1

  2. To Install Access Manager Session Failover Components on Message Queue 2

ProcedureTo Install Access Manager Session Failover Components on Message Queue 1

  1. As a root user, log in to the MessageQueue–1 host machine.

  2. Create a directory into which the Message Queue and Berkeley Database bits can be downloaded and change into it.


    # mkdir /export/AMSFO
# cd /export/AMSFO

  3. Copy amSessionTools.zip from the AccessManager–1 host machine to the MessageQueue–1 host machine.

    Note –

    amSessionTools.zip is included in the AccessManager7_1RTM.zip file downloaded in To Generate an Access Manager WAR File on the Access Manager 1 Host Machine. amSessionTools.zip can be found under the tools directory.

  4. Unzip amSessionTools.zip.


    # cd /export/AMSFO
# unzip amSessionTools.zip -d amSessionTools

  5. Modify the permissions on the setup script and run it to initialize the session failover tools.


    # cd /export/AMSFO/amSessionTools
# chmod +x setup
# ./setup

  6. When prompted, enter amserver as the Directory to install the scripts (example: amserver).

    Note –

    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/AMSFO/amSessionTools/amserver
JMQ is properly setup under directory jmq.
BerkeleyDB is properly setup under directory bdb.

  7. Change to the bin directory.


    # cd /export/AMSFO/amSessionTools/jmq/imq/bin

  8. Run the imqbrokerd command to create a new broker instance named msgqbroker.


    # ./imqbrokerd -name msgqbroker -port 7777 &

  9. 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

  10. 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

  11. Disable the guest user.

    This step ensures that the guest user will not be able to access the Access Manager 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.

  12. Modify the amsfo.conf file.

    amsfo.conf has parameters that are consumed by the Access Manager session failover startup script, amsfo.

    1. Change to the lib directory.


      # cd /export/AMSFO/amSessionTools/amserver/config/lib
      Tip –

      Backup amsfo.conf before you modify it.

    2. Set the following properties:


      CLUSTER_LIST=MessageQueue-1.example.com:7777,MessageQueue-2.example.com:7777
BROKER_INSTANCE_NAME=msgqbroker
USER_NAME=msgquser
BROKER_PORT=7777
      Note –

      The port used for BROKER_PORT should be the same as the one used in the value of the CLUSTER_LIST.

    3. Save the file and close it.

  13. Run the amsfopassword command.

    This command generates an encrypted password, creates a new file named .password, and stores the encrypted password in the new file.

    Caution – Caution –

    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.

    1. Change to the bin directory.


      # cd /export/AMSFO/amSessionTools/amserver/bin

    2. Run amsfopassword.


      # cd /export/AMSFO/amSessionTools/amserver/bin
# ./amsfopassword -e m5gqu5er -f /export/AMSFO/amSessionTools/amserver/.password

os.name=SunOS
SUCCESSFUL

    3. (Optional) View the encrypted password.


      # more /export/AMSFO/amSessionTools/amserver/.password

M27OGb6U4ufRu+oWAzBdWw==

  14. (Optional) Modify the amsessiondb script if necessary.

    The amsessiondb script (located in the /export/AMSFO/amSessionTools/amserver/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/AMSFO/amSessionTools/jmq/imq/lib
JMS_JAR_PATH=/export/AMSFO/amSessionTools/jmq/imq/lib
BDB_JAR_PATH=/export/AMSFO/amSessionTools/bdb/usr/lib
BDB_SO_PATH=/export/AMSFO/amSessionTools/bdb/usr/lib
AM_HOME=/export/AMSFO/amSessionTools
    Tip –

    Backup amsessiondb before you modify it.

  15. Restart the Access Manager session failover components.

    1. Change to the bin directory.


      # cd /export/AMSFO/amSessionTools/jmq/imq/bin

    2. Stop the Message Queue instance using the product's command line interface.

      See the Message Queue documentation for more information.

    3. Run the netstat command to verify that the MessageQueue-1 broker instance is stopped.


      # netstat -an | grep 7777

      If netstat returns no result, the MessageQueue-1 broker instance is stopped.

      Tip –

      If the MessageQueue-1 broker instance is not stopped, kill the process using the following procedure.

      1. Get the Java process IDs.


        # ps -ef | grep java

      2. Kill the Java process IDs that were returned.


        # kill -9 #### ####

      3. Run netstat again.

    4. Restart the MessageQueue-1 broker instance.


      # ./amfso start

    5. 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

  16. Log out of the MessageQueue–1 host machine.

ProcedureTo Install Access Manager Session Failover Components on Message Queue 2

  1. As a root user, log in to the MessageQueue–2 host machine.

  2. Create a directory into which the Message Queue and Berkeley Database bits can be downloaded and change into it.


    # mkdir /export/AMSFO
# cd /export/AMSFO

  3. Copy amSessionTools.zip from the AccessManager–1 host machine to the MessageQueue–2 host machine.

    Note –

    amSessionTools.zip is included in the AccessManager7_1RTM.zip file downloaded in To Generate an Access Manager WAR File on the Access Manager 1 Host Machine. amSessionTools.zip can be found under the tools directory.

  4. Unzip amSessionTools.zip.


    # cd /export/AMSFO
# unzip amSessionTools.zip -d amSessionTools

  5. Modify the permissions on the setup script and run it to initialize the session failover tools.


    # cd /export/AMSFO/amSessionTools
# chmod +x setup
# ./setup

  6. When prompted, enter amserver as the Directory to install the scripts (example: amserver).

    Note –

    The directory location should be relative to the current directory.

    When complete, the following messages are displayed:


    The scripts are properly setup under directory 
   /export/AMSFO/amSessionTools/amserver
JMQ is properly setup under directory jmq.
BerkeleyDB is properly setup under directory bdb.

  7. Change to the bin directory.


    # cd /export/AMSFO/amSessionTools/jmq/imq/bin

  8. Run the imqbrokerd command to create a new broker instance named msgqbroker.


    # ./imqbrokerd -name msgqbroker -port 7777 &

  9. Run netstat to verify that the new Message Queue instance is up and running.


    # netstat -an | grep 7777

*.7777		*.*			0			0	49152		0	LISTEN

  10. Add a new user named msgquser.

    This is the user that will be used to connect to the Message Queue broker 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. This helps to prevent brute force or DOS attacks. 


    # ./imqusermgr add -u msgquser -g admin -p m5gqu5er -i msgqbroker

  11. Disable the guest user.

    This step ensures that the guest user will not be able to access the Access Manager 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.

  12. Stop the Message Queue instance using the product's command line interface.

  13. Modify the amsfo.conf file.

    amsfo.conf has parameters that are consumed by the Access Manager session failover startup script, amsfo.

    1. Change to the lib directory.


      # cd /export/AMSFO/amSessionTools/amserver/config/lib
      Tip –

      Backup amsfo.conf before you modify it.

    2. Set the following properties:


      CLUSTER_LIST=MessageQueue-1.example.com:7777,MessageQueue-2.example.com:7777
BROKER_INSTANCE_NAME=msgqbroker
USER_NAME=msgquser
BROKER_PORT=7777
      Note –

      The port used for BROKER_PORT should be the same as the one used in the value of the CLUSTER_LIST.

    3. Save the file and close it.

  14. Run the amsfopassword command.

    This command generates an encrypted password, creates a new file named .password, and stores the encrypted password in the new file.

    Caution – Caution –

    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.

    1. Change to the bin directory.


      # cd /export/AMSFO/amSessionTools/amserver/bin

    2. Run amsfopassword.


      # cd /export/AMSFO/amSessionTools/amserver/bin
# ./amsfopassword -e m5gqu5er -f /export/AMSFO/amSessionTools/amserver/.password

os.name=SunOS
SUCCESSFUL

    3. (Optional) View the encrypted password.


      # more /export/AMSFO/amSessionTools/amserver/.password

M27OGb6U4ufRu+oWAzBdWw==

  15. (Optional) Modify the amsessiondb script if necessary.

    The amsessiondb script (located in the /export/AMSFO/amSessionTools/amserver/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/AMSFO/amSessionTools/jmq/imq/lib
JMS_JAR_PATH=/export/AMSFO/amSessionTools/jmq/imq/lib
BDB_JAR_PATH=/export/AMSFO/amSessionTools/bdb/usr/lib
BDB_SO_PATH=/export/AMSFO/amSessionTools/bdb/usr/lib
AM_HOME=/export/AMSFO/amSessionTools
    Tip –

    Backup amsessiondb before you modify it.

  16. Restart the Access Manager session failover components.

    1. Change to the bin directory.


      # cd /export/AMSFO/amSessionTools/amserver/bin

    2. Stop the MessageQueue-2 broker instance.


      # ./amsfo stop

      The port socket should be relinquished before you restart. If not, session failover problems may occur.

    3. Run the netstat command to verify that the MessageQueue-2 broker instance is stopped.


      # netstat -an | grep 7777

      If netstat returns no result, the MessageQueue-2 broker instance is stopped.

      Tip –

      If the MessageQueue-2 broker instance is not stopped, kill the process using the following procedure.

      1. Get the Java process IDs.


        # ps -ef | grep java

      2. Kill the Java process IDs that were returned.


        # kill -9 #### ####

      3. Run netstat again.

    4. Restart the MessageQueue-2 broker instance.


      # ./amfso start

    5. 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

  17. Log out of the MessageQueue–2 host machine.

11.3 Configuring and Verifying Session Failover

Use the following list of procedures as a checklist for configuring and verifying session failover.

  1. To Configure Access Manager for Session Failover

  2. To Verify That the Administrator Session Fails Over

  3. To Verify that the User Session Fails Over

ProcedureTo Configure Access Manager for Session Failover

  1. Access http://LoadBalancer-3.example.com:7070/amserver/UI/Login from a web browser.

  2. Log in to the Access Manager console as the administrator.

    Username

    amadmin

    Password

    4m4dmin1

  3. Click the Configuration tab.

  4. Under Global properties, click Session.

  5. Under Secondary Configuration Instance, click New.

  6. In the Add Sub Configuration page, provide the following information.

    Name

    Enter the load balancer URL https://loadbalancer-3.example.com:9443

    Tip –

    The case of the load balancer URL should match that of the Primary Site ID.

    Session Store User

    Enter msgquser

    Session Store Password

    Enter m5gqu5er

    Session Store Password (confirm)

    Enter m5gqu5er

    Maximum Wait Time

    Keep the default value of 5000.

    Database URL

    Enter MessageQueue-1.example.com:7777,MessageQueue-2.example.com:7777.

    This is the Message Queue broker address list. Enter multiple values using a comma and no space.

  7. Click Add.

  8. Click Save.

  9. Log out of the Access Manager console.

  10. Restart the Web Server 1 instance.

    1. Log in to the Access Manager 1 host machine.

    2. Restart the Web Server 1 instance.


      # cd /opt/SUNWwbsvr/https-AccessManager-1.example.com/bin
# ./stopserv; ./startserv

    3. Log out of the Access Manager 1 host machine.

  11. Restart the Web Server 2 instance.

    1. Log in to the Access Manager 2 host machine.

    2. Restart the Web Server 2 instance.


      # cd /opt/SUNWwbsvr/https-AccessManager-2.example.com/bin
# ./stopserv; ./startserv

    3. Log out of the Access Manager 2 host machine.

ProcedureTo Verify That the Administrator Session Fails Over

Before You Begin

Both Access Manager 1 and Access Manager 2 should be up and running before you begin this verification procedure.

  1. As a root user, log in to the AccessManager–2 host machine.

  2. Change to the bin directory.


    # cd /opt/SUNWwbsvr/https-AccessManager-2.example.com/bin

  3. Stop Access Manager 2.


    # ./stopserv

  4. Access http://LoadBalancer-3.example.com:7070/amserver/UI/Login from a web browser.

    1. Log in to the Access Manager console as the administrator.

      Username

      amadmin

      Password

      4m4dmin1

    2. Click the Sessions tab.

    3. In the View field, select Access Manager-1.example.com:1080 from the drop down list.

      Verify that only amadmin exists in the Sessions table.

    4. In the View field, select Access Manager-2.example.com:1080 from the drop down list.

      You will see an error message indicating the server is down.

    5. Leave this browser window 1 open.

  5. Start Access Manager 2.


    # ./startserv

  6. As a root user, log in to the AccessManager–1 host machine.

  7. Change to the bin directory.


    # cd /opt/SUNWwbsvr/https-AccessManager-1.example.com/bin

  8. Stop Access Manager 1.


    # ./stopserv

  9. Going back to the Access Manager console in browser window 1, under the Sessions tab, select Access Manager-1.example.com:1080 from the View drop down list.

    You will see an error message indicating the server is down.

  10. Now select Access Manager-2.example.com:1080 from the View drop down list.

    Verify that only amadmin exists in the Sessions table. This indicates that although AccessManager–1 was stopped, the Access Manager LoadBalancer-3 directed the request to AccessManager–2 and a session for amadmin was successfully created in AccessManager–2. If session failover was not enabled, it would have resulted in a login page.

ProcedureTo Verify that the User Session Fails Over

Before You Begin

This procedure assumes that you have just completed To Verify That the Administrator Session Fails Over.

  1. Access http://LoadBalancer-3.example.com:7070/amserver/UI/Login?realm=users from a second browser window.

  2. Log in to the Access Manager console as testuser1.

    Username

    testuser1

    Password

    password

    The Edit User page for testuser1 is displayed. Because Access Manager 1 was stopped, the user session is created in Access Manager 2.

  3. Leave browser window 2 open.

  4. Using browser window 1, click the Sessions tab.

  5. In the View field, select Access Manager-2.example.com:1080 from the drop down list.

    Verify that amadmin and testuser1 exist in the Sessions table.

  6. On the AccessManager–1 host machine, change to the bin directory.


    # cd /opt/SUNWwbsvr/https-AccessManager-1.example.com/bin

  7. Start AccessManager–1.


    # ./startserv

    Both Access Manager–1 and Access Manager–2 are up and running.

  8. On the AccessManager–2 host machine, change to the bin directory.


    # cd /opt/SUNWwbsvr/https-AccessManager-2.example.com/bin

  9. Stop Access Manager–2.


    # ./stopserv

  10. Using browser window 1, click the Sessions tab.

    1. In the View field, select Access Manager-1.example.com:1080.

      Verify that amadmin and testuser1 exist in the Sessions table. This indicates that the session successfully failed over to AccessManager–1.

      Tip –

      If testuser1 is not displayed, refresh the browser window 2 page.

    2. In the View field, select Access Manager-2.example.com:1080

      You will see an error message indicating the server is down.

  11. Log out of the consoles and the host machines.