Best Practice
ForgeRock Identity Platform
Does not apply to Identity Cloud

Best practice for migrating Authentication Chains to Trees in AM 6.x

Last updated Jan 12, 2023

The purpose of this article is to provide some basic concepts that can be used to assist in migrating authentication chains to equivalent functionality in authentication trees.

7 readers recommend this article


Authentication trees will replace authentication chains, and provide user and device-based login services. Trees use the existing callback and endpoint integration approaches.

This article covers the following topics:

Nodes and Trees functionality

A tree contains numerous points of logic called nodes. Nodes are not comparable to authentication modules; they are more cohesive and allow for looser coupling.

See About Authentication Trees for further information.

Key design principles for trees:

  • Flexible canvas
  • One entry point, one exit point, no traversal
  • Reusable components via inner-trees

Key design principles for nodes:

  • Highly cohesive
  • Loosely coupled
  • Single task
  • Simple to create
  • Simple to deploy
  • Combinable

The tree canvas provides a “shared state” which allows nodes to store and retrieve arbitrary information. This could include things like username for example; a mandatory element needed to create a session. The shared state is easily accessible via getters or setters, and is used to pass information between nodes in the tree. 

Node types

AM ships with out of the box nodes. Each .0 and .5 release will include new nodes and improvements to existing nodes. Nodes can be broken down into different types:

  • Collector Nodes: A collector node provides a callback mechanism where input is collected. A typical example could be a username collector, which provides a single text based callback.
  • Decision Nodes: A decision node is used to analyze information presented either directly from previous nodes or via analysis of data held in the shared state. The decision process will result in an exit. The exit can either be boolean or a string.
  • Single Outcome Nodes: A single outcome node simply provides processing logic. The exit point is akin to a “complete” and provides only one wire point to downstream systems.
  • Multiple Outcome Nodes: A node can have multiple outcomes. These can be either be boolean (for example, in the case of the Data Store Decision node) or arbitrary strings (like the Browser Checker node which exits based on the detected browser type).
  • Utility Nodes: Utility nodes abstract a lot of the generic logic processing that traditionally would need to be embedded within an authentication module. Utility nodes are generic and are designed to be integrated in many parts of a tree, often with multiple inputs or used repeatedly. Utility node examples include:
  • Inner Tree Evaluator: Trees will have numerous nodes. Often over 10. To manage the complexity and allow for node combinations to be reused, the Inner Tree Evaluator essentially allows trees to be linked to other trees.
  • Marketplace Nodes: Marketplace is a central store where nodes that are not shipped with the product can be stored or downloaded. Contributions to the Marketplace come from ForgeRock staff, technology partners or system integrators.

Marketplace nodes are not supported by ForgeRock; it is your responsibility to verify that the software is suitable and safe for use. 

Building and deploying a new node

A key design principle of a node is that they are simple to build and deploy.

The build process for creating a custom node is described in: Customizing Authentication Trees.

Module methods as node methods

Module to node development is somewhat different. Fewer files are required, fewer methods need implementing and the deployment process is simpler.

The file mapping between an authentication module and authentication node is described here:

An example method mapping between the main logic carrying methods within modules and the equivalent in nodes is described here:


A webhook allows for third-party notification integration when a user navigates through a tree. Currently only a logout webhook exists, but others may be introduced in the future. Webhook configuration allows for the URL destination, headers and payload. The payload can have access to session related data via variables.

Stateless or distributed login

From AM 6, sticky load balancing is no longer required for tree-based logins. Login state can be stored either client-side in a JWT (an extended authId) or within the CTS. This is configurable at the realm level:

The encryption settings of the client-side JWT are the same as for stateless tokenIds. This functionality is not available to chains. 

See Session Storage Location and Trees for further information.

Authentication modules as nodes

Authentication nodes are not a direct replacement for authentication modules. Modules contain more logic, more code and generally do more things. It would be expected that multiple nodes would make up the functionality of an existing module.

The following sections describe how existing modules' functionality can be handled using nodes:

Step-up authentication

Step-up authentication can be handled using the Get Session Data node. This node will read in existing session data, as supplied by a previously issued iPlanetDirectoryPro tokenId. The session data can be read, then added into the shared state object for further manipulation. For example, increasing the AuthLevel:

LDAP chain as a tree

As an example, let’s look at the typical ldapChain and examine how the same functionality can be implemented via trees.

The ldapChain likely contains one module; the LDAP module:

The LDAP module contains communication and search settings for the underling LDAP store, as well as the authentication level associated with a successful login.

To access the ldapChain, a URL similar to the following would be called:

At its most basic, a tree containing the following nodes would complete this functionality:

  1. Start
  2. Page node
    1. Username collector node
    2. Password collector node
  3. LDAP decision node
  4. Modify auth level node
  5. Success/Failure nodes

The LDAP decision node maps all the required fields that the LDAP authentication would provide. The steps to collect the username and password are grouped, but could be separate, resulting in multiple callback responses. 

In addition to the basic LDAP chain configuration, the settings tab on the chain provides access to success and failure URL redirects and access to the post authentication plugin configuration:

Post authentication plugins (PAP)

PAP functionality is handled differently in trees. There are numerous utility nodes that can provide some equivalent configurations.

Setting session properties

A common use for a PAP is to set session properties. Let’s update our ldapTree and add in a Set Session Properties node, that adds an arbitrary key called “treename” with a value of “ldapTree”.

After adding the “treename” to the Session Properties Allowlist service, a successful authentication to this tree and a call to ../getSessionInfo will show something similar to:

Handling logout notifications

A PAP could also be used for sending logout notifications. This is now handled via a webhook.  

Basic webhook configuration would look like this:

The body payload can have access to the following variables and payload construction:

{   "UserId":"${UserId}",    "WebhookEventType":"${WebhookEventType}",    "Principal":"${Principal}",    "Principals":"${Principals}",    "AMCtxId":"${AMCtxId}",    "authInstant":"${authInstant}",    "AuthLevel":"${AuthLevel}",    "clientType":"${clientType}",    "Host":"${Host}",    "HostName":"${HostName}",    "IndexType":"${IndexType}",    "Locale":"${Locale}",    "Organization":"${Organization}",    "Service":"${Service}",    "successURL":"${successURL}",    "":"${}",    "UserProfile":"${UserProfile}",    "UserToken":"${UserToken}",    "webhooks":"${webhooks}" }

We can now add the Register Logout Webhook node to our ldapTree:

This node simply points to the webhook configuration object:

Setting Redirection URL on success

Within the ldapChain settings, we can specify the success redirection URL if different from the standard dashboard page. This functionality is available as a node.

Let’s add the Success URL node to our ldapTree:

The configuration simply points to the end destination after login has occurred:

Setting Redirection URL on failure

The Failure URL node works in a similar way. Let’s add that in to our ldapTree just before the Failure end node:

An example destination could be to register or perhaps initiate a password reset flow:

Realm level account lockout

When using chains, account lockout and retry functionality is handled at the realm level via the default authentication settings page:

Within a tree, we can leverage the Account Lockout and Retry Limit Decision nodes to provide modular lockout functionality.

Let’s add them in:

Here the False exhaust from the LDAP decision can be linked directly to the Retry node. Retry can now be applied at any part of the tree, for example, by first checking the syntax of the username before submission.

The retry limit is configurable:

Once the limit is reached, we can add in the Account Lockout node. This node also provides the ability to unlock an account if a recovery flow has taken place:

Linking a chain to a tree

An intermediate step when migrating chains to trees might be to spread the authentication journey between the two worlds.  

A situation may arise where custom authentication logic is held in a module, which cannot immediately be replicated within a node, or perhaps more complex adaptive steps available within trees need to augment basic chain-based authentication. 

A simple way to overcome this is to start authentication in a chain before finishing authentication within a tree.

Within the authentication chain, specify the Successful Login URL to the URL of the necessary tree:

Example URL:


When performing a federation or policy agent redirect that already contains a goto parameter, the goto value would be overwritten using this approach. You would need a custom module to capture the original goto= value before passing that into the secondary tree so that the tree can collect and re-use the value.

The Example tree performs an optional malicious bot check using the Open Threat Intelligence node. If the user agrees, they get an extra 10 points within their auth level.

Within the tree, the Get Session Data node can be used to leverage the session data that was generated via the exit from the ldapService step to allow seamless integration:

The Get Session Data node will analyze the existing iPlanetDirectoryPro cookie that is presented, extract the UserId and add that to the tree’s shared state - updating the mandatory username. This tree will of course issue a secondary session, replacing the one issued from the chain.  

An important step is to alter the AuthLevel between the chain and tree. The ldapService chain issues an AuthLevel of 0. The tree, using the Modify Auth Level node, adds another 10 to that process. This allows authorization policies to differentiate between the two login components, and prevents a user from skipping the secondary tree and assuming the same level of assurance.

The overall flow looks like this:

  1. Start login process to the default ldapService chain
  2. Seamless transfer to the Tree with a choice node asking whether the additional bot check should be performed:

New Trees design methodology

When developing a new tree, there are certain items that need to be considered and steps to follow in order to drive efficiency and reduce operational overhead.

Design Phase

  1. Identify data sources:
    • Internal (user repos)
    • External (third-party fraud, bot analysis, threat intelligence)
    • Factors (biometric, OTP, PKI)
  2. Identify device requirements:
    • Mobile characteristics
    • Desktop characteristics
  3. Identify network requirements:
    • Allowlists
    • Denylists
  4. Identify context requirements:
    • Time of day
    • Geo-fencing
    • Geo-velocity

Implementation Phase

  1. Leverage utility nodes
  2. Re-use nodes via grouping and inner-trees
  3. Leverage Marketplace nodes
  4. Build custom nodes
  5. Test via unique service URLs
  6. Use authentication levels for targeted assurance response
  7. Apply additional factors sparingly
  8. Leverage non-boolean exits:
    • Failures can be successes with caveats
      • Redirection
      • Honeypots
      • Bad actor analysis


When migrating chains to trees, there are several things to consider. Firstly, trees provide the ability to perform what is known as “stateless login” or “distributed login”. Any AM instance within a cluster can start, continue or end an authentication journey, regardless of position in the tree. This provides a cloud-friendly way of handling the login process. If a user is load balanced across AM instances, or if an existing AM instance is taken down, the login journey can be continued via any other available AM node.  

This functionality is not available in authentication chains. If a custom authentication module contains stateful logic, that needs to be considered when designing a corresponding tree and how any custom nodes may handle this logic.

At a high level, steps for migrating include:

  1. Identifying data inputs in the existing chain
  2. Identifying post login success logic
  3. Mapping any custom logic into existing utility nodes
  4. Mapping any custom logic into existing collector or decision nodes
  5. Mapping any custom logic into Marketplace nodes
  6. Mapping any custom logic into custom nodes

Authentication trees will replace authentication chains in coming releases of AM. Migration strategies need to be considered in order to allow a smooth transition to the new paradigm. The move from authentication chains to trees is not an upgradeit is a migration requiring the necessary pre-analysis and implementation.

See Also

How do I create an authentication tree in AM (All versions) using REST or Amster?

How do I modify the prompt text shown when authenticating to a tree in AM (All versions)?

How do I customize authentication tree nodes using source code in AM 6.0.x?

Authentication trees in AM

Configuring Authentication Trees

Related Training

ForgeRock Access Management Deep Dive (AM-410)

Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.