---
title: Migrate authentication modules and chains to trees
description: Modules and chains were removed in AM 8.0. If you're still using modules and chains for authentication, you must migrate to nodes and trees as soon as possible.
component: pingam
version: 8.1
page_id: pingam:am-authentication:migrate-to-auth-trees
canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/migrate-to-auth-trees.html
section_ids:
  key_conceptual_changes: Key conceptual changes
  authentication_trees: Authentication trees
  default_trees: Default trees
  node-types: Node types
  stateless-journeys: Stateless and distributed journeys
  shared-state: Expanded shared state
  hooks: Hooks for post-authentication logic
---

# Migrate authentication modules and chains to trees

Modules and chains were removed in AM 8.0. If you're still using modules and chains for authentication, you must migrate to nodes and trees as soon as possible.

The high-level steps for migrating are:

1. **Analyze your existing configuration**

   Review existing modules, chains, and post-authentication plugins (PAP) to understand their functionality and what needs to be migrated. Determine what you can replace with existing nodes and hooks, and what requires [custom node development](customize-nodes.html).

2. **Design your new trees**

   Map the functionality of your old modules and chains to new authentication journeys. Learn more in [Map module and chain functionality to trees](map-modules-chains-to-trees.html) and [Trees](auth-trees.html).

3. **Create your trees**

   Create the new trees. Use existing nodes where possible and add custom nodes where necessary.

4. **Test and deploy**

   Test the new trees to make sure they work as expected. When you're satisfied, deploy them to your production environment to complete the migration.

## Key conceptual changes

Before designing your new trees, it's important to understand their key improvements and differences compared to legacy modules and chains.

### Authentication trees

Authentication *trees* (also referred to as *journeys*) provide fine-grained authentication by allowing multiple paths and decision points throughout the authentication flow. Use them to build complex authorization scenarios, while offering users a streamlined sign-on experience.

Trees are made up of authentication *nodes*, which define actions taken during authentication. Each node performs a single task during authentication, such as, collecting a username or making a simple decision based on a cookie.

Nodes can have multiple outcomes rather than just success or failure. This lets you create complex yet end user-friendly authentication experiences by linking nodes together, creating loops, branching the tree for different authentication scenarios, and nesting nodes within a tree:

![Create multiple paths for authentication by linking nodes within trees.](_images/trees-ui-example.png)Figure 1. Example authentication tree

#### Default trees

AM provides the following default trees, which are direct replacements for the corresponding default modules and chains:

* `ldapService`: replaces the `ldapService` chain.

* `Agent`: replaces the `Application` module.

* `amsterService`: replaces the `amsterService` chain.

Learn more in [Default trees](authn-introduction-authn.html#default-trees).

#### Node types

There are five types of node you can use in your journeys:

* Collector Nodes

  A collector node provides a callback mechanism where input is collected. For example, the [Username Collector node](https://docs.pingidentity.com/auth-node-ref/8.1/am-only/username-collector.html), which provides a single text-based callback.

* Decision Nodes

  A decision node analyzes information received from previous nodes and determines the appropriate outcome as a result.

* Single Outcome Nodes

  A single outcome node provides processing logic and has one possible outcome.

* Multiple Outcome Nodes

  A node can have multiple outcomes. Some nodes, such as the [Data Store Decision node](https://docs.pingidentity.com/auth-node-ref/8.1/data-store-decision.html) have simple boolean outcomes (`True`, `False`). Others have more specific outcomes. For example, the [MFA Registration Options node](https://docs.pingidentity.com/auth-node-ref/8.1/mfa-registration-options.html) has outcomes such as `Register`, `Get App` and `Opt-out`.

* Utility Nodes

  Utility nodes abstract a lot of the generic logic processing that was previously embedded within a module. Utility nodes are generic and can be used multiple times in a tree.

  Examples of utility nodes include:

  * [Account Lockout node](https://docs.pingidentity.com/auth-node-ref/8.1/account-lockout.html)

  * [Email Suspend node](https://docs.pingidentity.com/auth-node-ref/8.1/email-suspend.html)

  * [Message node](https://docs.pingidentity.com/auth-node-ref/8.1/message.html)

  * [Meter node](https://docs.pingidentity.com/auth-node-ref/8.1/meter.html)

  * [Page node](https://docs.pingidentity.com/auth-node-ref/8.1/page.html)

  * [Set Session Properties node](https://docs.pingidentity.com/auth-node-ref/8.1/set-session-properties.html)

  * [Inner Tree Evaluator node](https://docs.pingidentity.com/auth-node-ref/8.1/inner-tree-evaluator.html)

    Trees often include numerous nodes. To manage the complexity and allow for reuse of certain node combinations, the Inner Tree Evaluator node lets you embed trees within other trees.

### Stateless and distributed journeys

Trees provide the ability to perform *stateless login*, also known as *distributed login*. Any AM instance within a cluster can start, continue, or end an authentication journey, regardless of the end user's location in the tree. This provides a more resilient way of handling the login process. If an end user is load balanced across AM instances, or if an existing AM instance is taken down, the login journey can continue on any other available AM instance.

This functionality isn't available with modules and chains. If a custom module contains stateful logic, you must consider this when designing a corresponding tree and how any custom nodes will handle that state.

### Expanded shared state

Nodes use the shared state of the tree to store and pass information. This is similar to how modules could store user credentials in a shared state, but nodes can access and store a wider variety of data. For example, the [Device Profile Collector node](https://docs.pingidentity.com/auth-node-ref/8.1/device-profile-collector.html) writes the device metadata to the shared state for subsequent nodes to use.

There are three types of state:

* Shared

  Non-sensitive state.

* Transient

  Sensitive state.

  Transient state data is never sent back to the user's browser in a callback so doesn't need to be encrypted. The transient state is for sensitive data and for data not required after the next callback.

* Secure

  Encrypted sensitive state.

  Secure state data is sent back to the user's browser encrypted as part of the shared state object.

Transient state data is *promoted* to secure state data when:

* A callback to the user is about to occur.

* A downstream node is detected in the journey, requesting data in the transient state as script input.

### Hooks for post-authentication logic

Hooks provide a way to extend the functionality of trees, similar to the functionality of PAP, without modifying the core tree structure.

There are three types of hooks available:

* [Webhooks](auth-tree-webhooks.html)

  Use webhooks to send contextual information about authenticated sessions on predefined events, for example, logging out.

* [Tree hooks](post-authn-plugins-treehook.html)

  Use tree hooks to perform post-authentication tasks, like setting persistent cookies or logging detailed audit events.

* [Logout hooks](create-logout-hook.html)

  Use logout hooks to perform tasks like redirecting the user on logout or adding information to the logout response that's sent to the client.