Shadow Session Creation To Ease Application Migration to ForgeRock Identity Cloud

By Darinder Shokar
Originally posted on


During migration to a new Identity and Access Management platform, relying applications typically need to re-point from their existing IdP to the new IdP for login and token validation interactions. Application owners may have different release cycles and priorities so it’s advantageous to look for opportunities to ease migration, while maintaining the seamless login experience users are accustomed to.

One technique which can help is creating a “shadow session” in the existing IdP as part of the login journey of the new IdP. In this scenario, two session cookies are stored against the user-agent; one for the new IdP and one for the existing. This enables new applications to leverage the session from the new IdP, while allowing applications yet to migrate to make use of legacy sessions seamlessly.

This blog will dive into this approach using the powerful flexible journeys of ForgeRock Identity Cloud against a self-managed implementation of the ForgeRock platform via a single additional node.

Configuration Steps

The following will configure ForgeRock Identity Cloud to request a session from a self-managed ForgeRock implementation seamlessly via the user credentials acquired earlier in the login journey.

As a prerequisite, bidirectional sync needs to be enabled between the self-managed ForgeRock implementation and ForgeRock Identity Cloud. Also, session lifetimes between the two systems should be aligned to ensure a consistent user experience.

Note to get up and running quickly you can just import the complete journey with script from here; the “Create Environment Secrets and Variables (ESVs) step is still required though.

Import the set-fr-cookie script

  1. From the ForgeRock Identity Cloud Platform UI, goto Scripts on the left panel > Auth Scripts > Blue New Script button > Configuration Provider Node > Next. Provide a Name of set-fr-cookie, Description of Script to request a shadow session from the self-managed ForgeRock implementation and copy and paste the contents of set-fr-cookie.js into the editor and hit Save. Example below:

Create Environment Secrets and Variables (ESVs)

ESVs are a great way to set values which need to be different per environment and also allows administrators to change values in the ESV configuration (via UI or REST) rather than editing scripts directly. Let’s go ahead and configure some ESVs which reference the existing ForgeRock implementation

  1. From the Platform UI click the name at the top right > Tenant settings > Environment Secrets & Variables > Variable tab > Blue Add Secret and add the following:

Name: esv-legacy-fr-cookie

Type: string

Value: Name of the cookie from the existing system e.g. iPlanetDirectoryPro

  1. Repeat step 1 for the following string ESVs:

ESV Configuration table

Build the Login Journey

  1. From the Platform UI goto Journeys > Click the ellipses next to the default Login journey and hit Duplicate > Provide a name of setFRCookie and hit Save. The new journey will then render in the UI.
  2. Search for Configuration Provider onto the top left Filter Nodes box and drag the node onto the canvas
  3. Provide a name of Set Legacy FR Session Cookie , select the set-fr-cookie script we created above, set the Node Type to Set Custom Cookie and connect the journey as below (note for simplicity I’ve also removed the Inner Tree and added a Message Node to pause authentication but you don’t need to do these steps):

Journey to acquire a shadow session from the existing system and set as a cookie

Note the Configuration failure path for this new node is not connected to the red error; this is intentional as we want authentication to continue on even if the existing system has an issue to decouple the two platforms.

Execute the Journey

Now the fun bit! Let’s execute the journey and make sure everything hangs together as expected.

  1. Copy the Preview URL link from the top right of the Journey Editor. It will look something like this: https://<tenant>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=setFRCookie
  2. Open a new Incognito Window or fire up a different browser app and paste in the URL from above, login with a valid username and password
  3. Assuming the user exists on both systems, you’ll now see an additional cookie set as below, which applications yet to migrate to the new IdP can consume. Nice!

Journey illustrating a cookie being set via shadow session execution


There you have it, one technique which can help ease application migration to ForgeRock Identity Cloud via a single additional node. While this is a great approach to add to the toolbox, it should only be leveraged for a short period of time. Applications should still be migrated quickly to the new platform for a number or reasons:

  • Operational overhead — Running two systems at the same time incurs additional operational overhead.
  • Increased response times — The login journey now needs to interact with an external system, this will increase response times and the impact should be quantified.
  • Introduces an additional dependency — The solution is dependent on accounts being synchronised on both systems.

In addition, this example uses the default ldapService login chain when interacting with the existing system. To improve the security posture and add additional control, a stronger login journey or chain should be defined in the existing system, such as consumption of a signed and encrypted JWT token from ForgeRock Identity Cloud. Perhaps a blog for another day.

Lastly, this example uses a self-managed ForgeRock implementation to mimic the existing system, the node can also be adapted for use against another IdP which supports REST based authentication.

Thanks for reading!

More from Darinder Shokar