Enabling Failover in J2EE Agents

The agent allows basic failover capabilities. This helps you ensure that if the primary OpenSSO Enterprise instance for which the agent has been configured becomes unavailable, the agent will switch to the next OpenSSO Enterprise instance as specified by setting the appropriate agent property. This configuration can be achieved by implementing the following steps.

To Enable Failover in J2EE Agents

1. Provide a list of OpenSSO Enterprise authentication services URLs that may be used by the agent to authenticate users who do not have sufficient credentials to access the protected resources.

   To create the list configure the property labeled OpenSSO Login URL (Tab: OpenSSO Services, Name: com.sun.identity.agents.config.login.url).

   You may specify more than one login URL to this property as follows:

   primary-OSSO-server

   Represents the URL of the primary OpenSSO Enterprise instance to which users are redirected for authentication.

   failover-OSSO-server1

   Represents the URL of the OpenSSO Enterprise instance to which users are redirected for authentication if the primary OpenSSO Enterprise instance fails.

   failover-OSSO-server2

   Represents the URL of the OpenSSO Enterprise instance to which users are redirected for authentication if the primary OpenSSO Enterprise instance fails and the first failover OpenSSO Enterprise instance fails.

   If a URL list is provided to OpenSSO Login URL property, the agent first tries to establish a connection to the first server (primary-OSSO-server) specified in the URL list. If the agent is successful in establishing this connection, it redirects the user to the OpenSSO Enterprise instance for authentication.

2. (Optional) Turn prioritization on for the failover lists by enabling the property labeled Login URL Prioritized (Tab: OpenSSO Services, Name: com.sun.identity.agents.config.login.url.prioritized).

   ---

   Note –

   Enabling this property turns prioritization on for the login URL list and the CDSSO URL list. The two cases shown in this step specifically mention the login URL list. However, this explanation of prioritization is exactly the same for the CDSSO URL list. The final step in this procedure describes how to create the CDSSO URL list in case such a scenario applies to your site's deployment.

   ---

   The following cases describe the behavior of the agent in different situations: when you enable prioritization and when you do not enable prioritization for the login URL list.

   Case 1: The Login URL Prioritized property is enabled.

   Enabling this property means that priority is established for the login URL list described in Step 1. The list was created by configuring the property labeled Login URL.

   Therefore, the first URL on the list has a higher priority than the second URL on the list, which has a higher priority than the third URL on the list, and so on. If the server (primary-OSSO-server) specified in this example as the first URL on the list is running, the agent sends all requests to this server only. However, if primary-OSSO-server fails, from that point on, subsequent requests are sent to the server (failover-OSSO-server1), which is second on the list. Furthermore, if at some point primary-OSSO-server comes back, then the subsequent requests from that point on are sent to primary-OSSO-server, since it takes priority over failover-OSSO-server1. This mechanism always fails back to the highest priority OpenSSO Enterprise instance among the OpenSSO Enterprise instances that are running at the point in time the agent must redirect requests to an OpenSSO Enterprise instance.

   Case 2: The Login URL Prioritized property is not enabled.

   In this case, no server takes priority over another. Failover occurs in a round-robin fashion. If all the servers are running, the agent sends requests to the server (primary-OSSO-server), which is first on the list. If primary-OSSO-server goes down then all subsequent requests are sent to the server (failover-OSSO-server1), which is second on the list. The agent keeps sending the requests to failover-OSSO-server1 unless that server goes down. If failover-OSSO-server1 does go down then the agent routes all the subsequent requests to the server (failover-OSSO-server2), which is third on the list, until it goes down. If it goes down, the agent tries to connect to primary-OSSO-server once again. Assuming that by then the primary-OSSO-server is running, all the subsequent requests from then on are sent to primary-OSSO-server. This is a simple round-robin mechanism without any priority involved.

3. Provide a list of OpenSSO Enterprise Naming Service URLs that may be used by the agent to get access to the various other service URLs that may be needed to serve the logged on user.

   This can be done by using the following property:

   com.iplanet.am.naming.url (accessible in the OpenSSOAgentBootstrap.properties file)

   More than one naming service URL may be specified as a space delimited list of URLs. The following example illustrates this idea:

   com.iplanet.am.naming.url = primary-OSSO-server failover-OSSO-server1

4. (Conditional) If the deployment consists of an agent instance that is on a different domain than multiple OpenSSO Enterprise instances for which you want to enable failover, provide a URL list of the remote OpenSSO Enterprise instances.

   Configure the property labeled CDSSO Servlet URL (Tab: SSO, Name: com.sun.identity.agents.config.cdsso.cdcservlet.url) to create the list, specifying multiple CDSSO URLs as such:

   primary-remoteOSSO-server

   failover-remoteOSSO-server1

   failover-remoteOSSO-server2