Home > ForgeRock, OpenAM, Single Sign-On > Understanding the iPlanetDirectoryPro Cookie

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.

SSOTokenID

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.

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

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

 

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.

  1. Renjith
    March 4, 2014 at 11:12 pm

    Good article!

    Cross Talk Example Section : …Server 02 would then become the master of the session and the Session Key would be updated to reflect this.

    Does this mean the token issued to the client which has the session key information is modified? Why should an end consumer be affected because the session was retrieved from another server since Server 01 is not available ? It must be transparent and should not affect the end consumer holding the token.

    • idmdude
      March 6, 2014 at 5:35 pm

      The session is not actually transferred, that was a mistake in my understanding and has been corrected in the current posting. The session remains intact on Server 02 and if any changes are made to the session by Server 01, then it must update the session on Server 02. Unfortunately that increases the communication even more and is an even better reason why you want to avoid cross talk.

  2. July 9, 2014 at 12:03 pm

    Nice article, Bill, I found this very useful in explaining x-talk and SFO to a customer.

    • idmdude
      July 11, 2014 at 7:25 am

      Thanks Andy, glad it helped.

  3. Haam
    July 24, 2014 at 6:18 pm

    Hi Bill,

    Just like to point out that in a site configuration, the server value in the session key is not necessarily the same as the server’s id value (as indicated in ou=http:///openam,ou=com-sun-identity-servers,ou=default,ou=GlobalConfig,ou=1.0,ou=iPlanetAMPlatformService,ou=services,dc=openam,dc=forgerock,dc=org).

    I was hoping to be able to infer the amlbcookie value (which defaults to the server Id) from the session key, but apparently it is not always possible.

    My token gives server = 02, but my serverid=03. This probably came about because I had to delete and re-install my second OpenAM instance to join an existing site.

    Just thought I would share this in case others are trying to infer something similar from the token.

    Regards,
    Haam

  4. Atif Faridi
    March 19, 2015 at 3:33 pm

    Bill,

    It’s been a while. Thanks for this useful post.

    If you recall, we have a service layer that talks to OpenAM and it extracts the amlbcookie value from the Session Key. This explains why the value is always that of the site – because I was testing with tokens from a non-site instance when I wrote the extraction code. 😛

    Regards,
    Atif

    • idmdude
      March 20, 2015 at 6:21 am

      Hey Atif, yes I remember working with you guys and use examples of that deployment often. Your use of splunk was nothing short of awesome! Hope all is well.

  1. August 14, 2015 at 10:49 am

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: