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.

AQIC5wM2LY4Sfcy954IRN6Ixz7ZMwVdJkGlqr9urGirFNMQ.*AAJTSQACMDMAAlNLAAoxODIyMjQ4MDI0AAJTMQACMDI.*;

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
loginURL:/auth/UI/Login
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.

SSOTokenID = AQIC5wM2LY4Sfcy954IRN6Ixz7ZMwVdJkGlqr9urGirFNMQ.*AAJTSQACMDMAAlNLAAoxODIyMjQ4MDI0AAJTMQACMDI.*;

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

Session Key:  *AAJTSQACMDMAAlNLAAoxODIyMjQ4MDI0AAJTMQACMDI.*;

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.

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

SI03SK1822248024S102

And can be broken down as follows:

Site:  SI03
Server:  S102
Storage Key:  SK1822248024

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.

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.

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.

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