Understanding the iPlanetDirectoryPro Cookie

So you have run into problems with OpenAM and you are now looking at the interaction between the Browser and the OpenAM server.  To assist you in your efforts you are using a plug-in like LiveHttpHeaders, SAML Tracer, or Fiddler and while you are intently studying “the dance” (as I like to call it), you come across a cookie called iPlanetDirectoryPro that contains a value that looks like something your two year old child randomly typed on the keyboard.


So what is this cookie and what do its contents actually mean?

I’m glad that you asked.  Allow me to explain.

OpenAM Sessions

When a user successfully authenticates against an OpenAM server, a session is generated on that server.  The session is nothing more than an object stored in the memory of the OpenAM server where it was created.  The session contains information about the interaction between the client and the server.  In addition to other things, the session will contain a session identifier, session times, the method used by the user to authenticate, and the user’s identity.  The following is a snippet of the information contained in a user’s OpenAM session.

sessionID:  AQIC5wM…
maxSessionTime:  120
maxIdleTime:  30
timeLeft:  6500
userID:  bnelson
authLevel: 1
service: ldapService
locale: en_US

Sessions are identified using a unique token called SSOTokenID.  This token contains the information necessary to locate the session on the server where it is currently being maintained.  The entire value of the iPlanetDirectoryPro cookie is the SSOTokenID.


While this may look like gibberish, it actually has meaning (and is actually quite useful).

The period (.) in the middle of the SSOTokenID is a delimiter that separates the SSOToken from the Session Key.


The SSOToken is a C66Encoded string that points to the session in memory.  The Session Key is a Base64 Encoded string that identifies the location of the site and server where the session is being maintained.  Additionally, the Session Key contains the storage key of the session should you need to identify it in a persistent storage location (such as the amsessiondb [OpenAM v10.0 or lower] or the OpenDJ CTS Store [OpenAM v10.1 or higher]).

So separating the SSOTokenID into its two components you will find the following:

SSOToken:  AQIC5wM2LY4Sfcy954IRN6Ixz7ZMwVdJkGlqr9urGirFNMQ


As previously indicated, the Session Key is a Base64 Encoded value.  That means that you can decode the Session Key into meaningful information using Base64 Decoders.

Note:  A useful site for this is http://www.base64decode.org/.

Running the Session Key listed above through a Base64 decoder yields the following


And can be broken down as follows:

Site:  SI03
Server:  S102
Storage Key:  SK1822248024


Note:  The session key is a Base64 encoded Java DataInputStream.  As such, the decoded data includes a combination of both discernible and non-discernible data. The output of running the session key through a Base64 decoder is similar to performing a UNIX ‘strings’ command on a binary database.  The good thing is that the key bits of data are discernible (as shown above).

This information tells you that the session identified by the SSOToken (AQIC5wM2LY4Sfcy954IRN6Ixz7ZMwVdJkGlqr9urGirFNMQ) is being maintained on server 02 in site 03 and is being persisted to the database and may be identified by storage key 1822248024.

IMPORTANT:The SI and S1 keys have different meanings depending on whether the server belongs to a site or not.  If the server belongs to a site, then SI contains the primary site’s ID and S1 contains the server’s ID.  This is shown in the example, above.  If the server does not belong to a site, then SI contains the server’s ID.Since 10.1.0-Xpress the Storage Key is always part of the session ID.

This may be useful information for debugging, but it is essential information for OpenAM – especially in cases where a load balancer may be configured incorrectly.

Session Stickiness

Another important cookie in OpenAM is amlbcookie.  This cookie defines the server where the session is being maintained (i.e. amlbcookie=02) and should be used by load balancers to maintain client stickiness with that server.  When used properly, the amlbcookie allows a client to be directed to the server where the session is available.  If, however, a client ends up being sent to a different server (due to an incorrectly configured load balancer or the primary server being down) then the new OpenAM server can simply look at the information contained in the Session Key to determine the session’s location and request the session from that server.

Note:  Obtaining the session from another properly working OpenAM server is referred to as “cross talk” and should be avoided if at all possible.  The additional overhead placed on both the OpenAM servers and the network can reduce overall performance and can be avoided by simply configuring the load balancer properly.

Cross Talk Example

If Server 02 in Site 03 is maintaining the session and the client is sent to Server 01, then Server 01 can query Server 02 and ask for the session identified by the SSOToken value.  Server 02 would send the session information to Server 01 where the request can now be serviced.  If Server 01 needs to update any session information , then it does so by updating the session stored on Server 02.  As long as Server 02 remains available, the session is maintained on that server and as such, the communication between Server 01 and Server 02 can become quite “chatty”.

Session Failover Example

If Server 02 in Site 03 is maintaining the session and the client is sent to Server 01, then Server 01 can query Server 02 and ask for the session identified by the SSOToken value.  If Server 02 is offline (or doesn’t respond), then Server 01 can obtain the session from the session store (amsessiondb or OpenDJ CTS) using the Storage Key value.

Note:  Session persistence is not enabled by default.

So now you know and you can stop blaming your two year old child.