Tuesday, February 25, 2014

OpenAM Data Store - High-Availability and Load-Balancing

It has been an interesting day trying to explain how the high-availability (failover) and load-balancing work in OpenAM for a customer.


In OpenAM administration console, the following is shown in the Data Stores tab:

This is unlike the authentication module where administrator can key in a Primary LDAP and a Secondary LDAP as shown below.

I am not able to find any useful documentation from ForgeRock at the moment. The below is an extract from old Sun OpenSSO documentation:

LDAP Server
Enter the name of the LDAP server to which OpenSSO will be connected in the format host.domain:portnumber. If more than one entry is entered, an attempt is made to connect to the first host in the list. The next entry in the list is tried only if the attempt to connect to the current host fails.   
Optionally, a server identifier and site identifier can be appended to the value of the LDAP Server attribute for redundancy. In this case, the format is host.domain:portnumber|serverID|siteID. These identifiers are assigned to the server when they are configured globally. 
  • serverID specifies a particular server as the primary LDAP server and others as secondary and tertiary (as defined) fallback servers. (If no number is specified, the LDAP server is primary.) The identifier is displayed in the OpenSSO console. 
  • siteID is not currently displayed in the OpenSSO console. It is a two digit number generated internally by OpenSSO — for example, 02. 
My colleague pointed me to the source code for OpenAM 10.0.0 - LDAPv3Repo.java. We dived into the getLDAPServerName() method.

private void getLDAPServerName(Map configParams) {
  List firstChoiceList = new ArrayList();
  List secondChoiceList = new ArrayList();
  // put ldapServer from list into a string seperated by space for
  // failover purposes. LDAPConnection will automatcially handle failover.
  // hostname:portnumber | severID | siteID
  // serverID is optional. if omitted, it means any(don't care).
  // siteID is optional. if omitted, it means any(don't care).
  // host whose siteID and serverID matches webtop naming's serverid and
  // siteid are put in the front of the list as well as those host which
  // did not specify a siteid/serverid because of backward compatibliity.
  // otherwise it will go to the end of the list.

Hey, good comment there inside the codes! This complement the documentation from OpenSSO.

So, I spent some time reading the codes and tracing it through with examples.


If your setting is as follows, then it only caters for High-Availability (failover/redundancy), but not load-balancing. The second AD (AD2) is always idle waiting in case of failover.

To put in simply, refer to the diagram below:


If your setting is as follows, then it caters for High-Availability as well as load-balancing. Both ADs (AD1 and AD2) are at work at the same time.



  1. And for 11.0.0 here is the code that deals with the data store settings:
    http://sources.forgerock.org/browse/openam/trunk/openam/openam-ldap-utils/src/main/java/org/forgerock/openam/ldap/LDAPUtils.java?hb=true#to263 :)

  2. hey my friend, no diagrams for me? :)