Archive for the ‘ForgeRock’ Category

Understanding the iPlanetDirectoryPro Cookie

February 26, 2014 10 comments

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

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.

How to Configure OpenAM Signing Keys

February 9, 2014 8 comments

The exchange of SAML assertions between an Identity Provider (IdP) and a Service Provider (SP) uses Public-key Cryptography to validate the identity of the IdP and the integrity of the assertion.  

Securing SAML Assertions

SAML assertions passed over the public Internet will include a digital signature signed by an Identity Provider’s private key.  Additionally, the assertion will include the IdP’s public key contained in the body of a digital certificate.  Service Providers receiving the assertion can be assured that it has not been tampered with by comparing the unencrypted (hashed) message obtained from the digital signature with a hashed version of the message created by the Service Provider using the same hashing algorithm.

The process can be demonstrated by the following diagram where the Signing process is performed by the IdP and the Verification process is performed by the SP.  The “Data” referred to in the diagram is the assertion and the “Hash function” is the hashing algorithm used by both the Identity Provider and the Service Provider.


In order for an Identity Provider to sign the assertion, they must first have a digital certificate.

OpenAM includes a default certificate that can use for testing purposes.  This certificate is common to all installations and while convenient, should not be used for production deployments.  Instead, you should either use a certificate obtained from a trusted certificate authority (such as Thawte or Entrust) or generate your own self-signed certificate.

Note:  For the purposes of this article, $CONFIG refers to the location of the configuration folder specified during the installation process.  $URI refers to the URI of the OpenAM application; also specified during the installation process (i.e. /openam).

OpenAM’s Default Signing Key

OpenAM stores its certificates in a Java Keystore file located in the $CONFIG/$URI folder by default.  This can be found in the OpenAM Console as follows:

  1. Log in to the OpenAM Console as the administrative user.
  2. Select the Configuration tab.
  3. Select the Servers and Sites subtab.
  4. In the Servers panel, select the link for the appropriate server instance.
  5. Select the Security tab.
  6. Select the Key Store link at the top of the page.

You will see that the default location for the Java Keystore file, all passwords, and the alias of the default test certificate as follows:


Viewing the Contents of OpenAM’s Default Certificate

You can view the contents of this file as follows:

  1. Change to the $CONFIG/$URI folder.
  2. Use the Java keytool utility to view the contents of the file.  (Note:  The contents of the file are password protected.  The default password is:  changeit)

# keytool –list –keystore keystore.jks

Enter keystore password:   changeit

Keystore type: JKS

Keystore provider: SUN

Your keystore contains 1 entry

Alias name: test

Creation date: Jul 16, 2008

Entry type: PrivateKeyEntry

Certificate chain length: 1


Owner: CN=test, OU=OpenSSO, O=Sun, L=Santa Clara, ST=California, C=US

Issuer: CN=test, OU=OpenSSO, O=Sun, L=Santa Clara, ST=California, C=US

Serial number: 478d074b

Valid from: Tue Jan 15 19:19:39 UTC 2008 until: Fri Jan 12 19:19:39 UTC 2018

Certificate fingerprints:

MD5:  8D:89:26:BA:5C:04:D8:CC:D0:1B:85:50:2E:38:14:EF

SHA1: DE:F1:8D:BE:D5:47:CD:F3:D5:2B:62:7F:41:63:7C:44:30:45:FE:33

SHA256: 39:DD:8A:4B:0F:47:4A:15:CD:EF:7A:41:C5:98:A2:10:FA:90:5F:4B:8F:F4:08:04:CE:A5:52:9F:47:E7:CF:29

Signature algorithm name: MD5withRSA

Version: 1



Replacing OpenAM’s Default Keystore

You should replace this file with a Java Keystore file containing your own key pair and certificate.  This will be used as the key for digitally signing assertions as OpenAM plays the role of a Hosted Identity Provider.  The process for performing this includes five basic steps:

  1. Generate a new Java Keystore file containing a new key pair consisting of the public and private keys.
  2. Export the digital certificate from the file and make it trusted by your Java installation.
  3. Generate encrypted password files that permit OpenAM to read the keys from the Java Keystore.
  4. Replace OpenAM’s default Java Keystore and password files with your newly created files.
  5. Restart OpenAM.

The following provides the detailed steps for replacing the default Java Keystore.

1.  Generate a New Java Keystore Containing the Key Pair

a)      Change to a temporary folder where you will generate your files.

# cd /tmp

b)     Use the Java keytool utility to generate a new key pair that will be used as the signing key for your Hosted Identity Provider.

# keytool -genkeypair -alias idfsigningkey -keyalg RSA -keysize 1024 -validity 730 -storetype JKS -keystore keystore.jks

Enter keystore password:   cangetin

Re-enter new password:   cangetin

What is your first and last name?


What is the name of your organizational unit?

  [Unknown]:  Security

What is the name of your organization?

  [Unknown]:  Identity Fusion

What is the name of your City or Locality?

  [Unknown]:  Tampa

What is the name of your State or Province?

  [Unknown]:  FL

What is the two-letter country code for this unit?

  [Unknown]:  US

Is, OU=Security, O=Identity Fusion, L=Tampa, ST=FL, C=US correct?

  [no]:  yes

Enter key password for <signingKey>

        (RETURN if same as keystore password):  cangetin

Re-enter new password:  cangetin

You have now generated a self-signed certificate but since it has been signed by you, it is not automatically trusted by other applications.  In order to trust the new certificate, you need to export it from your keystore file, and import it into the cacerts file for your Java installation.  To accomplish this, perform the following steps:

2.      Make the Certificate Trusted

a)      Export the self-signed certificate as follows:

# keytool -exportcert -alias idfsigningkey -file idfSelfSignedCert.crt -keystore keystore.jks

Enter keystore password:  cangetin

Certificate stored in file <idfSelfSignedCert.crt>

b)     Import the certificate into the Java trust store as follows:

# keytool -importcert -alias idfsigningkey -file idfSelfSignedCert.crt -trustcacerts -keystore /usr/lib/jvm/java-7-oracle/jre/lib/security/cacerts

Enter keystore password:   changeit

Owner:, OU=Security, O=Identity Fusion, L=Tampa, ST=FL, C=US

Issuer:, OU=Security, O=Identity Fusion, L=Tampa, ST=FL, C=US

Serial number: 34113557

Valid from: Thu Jan 30 04:25:51 UTC 2014 until: Sat Jan 30 04:25:51 UTC 2016

Certificate fingerprints:

         MD5:  AA:F3:60:D1:BA:1D:C6:64:61:7A:CC:16:5E:1C:12:1E

         SHA1: 4A:C3:7D:0E:4C:D6:4C:0F:0B:6B:EC:15:5A:5B:5E:EE:BB:6A:A5:08

         SHA256: A8:22:BE:79:72:52:02:6C:30:6E:86:35:DA:FD:E0:45:6A:85:2C:FE:AA:FB:69:EA:87:30:65:AF:2E:65:FB:EB

         Signature algorithm name: SHA256withRSA

         Version: 3


#1: ObjectId: Criticality=false

SubjectKeyIdentifier [

KeyIdentifier [

0000: 12 3B 83 BE 46 D6 D5 17   0F 49 37 E4 61 CC 89 BE  .;..F….I7.a…

0010: 6D B0 5B F5                                        m.[.



Trust this certificate? [no]:  yes

OpenAM needs to be able to open the truststore (keystore.jks) and read the key created in step 1.  The private key and truststore database have both been locked with a password that you entered while configuring the truststore and signing key, however.  For OpenAM to be able to read this information you need to place these passwords in files on the file system.

3.      Generate Encrypted Password Files

Note:  The passwords will start out as clear text at first, but will be encrypted to provide secure access.

a)      Create the password file for the trust store as follows:

# echo “cangetin”  >  storepass.cleartext

b)     Create the password file for the signing key as follows:

# echo “cangetin”  >  keypass.cleartext

 c)      Prepare encrypted versions of these passwords by using the OpenAM ampassword utility (which is part of the OpenAM administration tools).

# ampassword –encrypt keypass.cleartext > .keypass

# ampassword –encrypt storepass.cleartext > .storepass

Note:  Use these file names as you will be replacing the default files of the same name.

4.      Replace the Default OpenAM Files With Your New Files

a)      Make a backup copy of your existing keystore and password files.

# cp $CONFIG/$URI/.keypass $CONFIG/$URI/

# cp $CONFIG/$URI/.storepass $CONFIG/$URI/

# cp $CONFIG/$URI/keystore.jks $CONFIG/$URI/

b)     Overwrite the existing keystore and password files as follows:

# cp .keypass $CONFIG/$URI/.keypass

# cp .storepass $CONFIG/$URI/.storepass

# cp keystore.jks $CONFIG/$URI/keystore.jks

5.      Restart the container where OpenAM is currently running. 

This will allow OpenAM to use the new keystore and read the new password files.

Verifying Your Changes

You can use the keytool utility to view the contents of your Keystore as previously mentioned in this article.  Alternately, you can log in to the OpenAM Console and see that OpenAM is using the new signing key as follows:

  1. Log in to OpenAM Console.
  2. Select the Common Tasks tab.
  3. Select the Create Hosted Identity Provider option beneath the Create SAMLv2 Providers section.


Verify that you now see your new signing key appear beneath the Signing Key option as follows:


You have now successfully replaced the default OpenAM Java Keystore with your own custom version.