Nodes are designed to have a single responsibility. Where appropriate, they should be loosely coupled with other nodes, enabling reuse in multiple situations.

For example, if a newly written node requires a username value, it should not collect it itself, but rely on another node, namely the Username Collector node.

There are two broad node types: collector nodes and decision nodes.

Authentication modules contain multiple states, with the associated inputs and outputs of each state resulting in either callbacks returned to the user, or state changes inside either AM or at a third party service.

States within a module either collect input from the user or process it. For example, a module can collect the username and the password from the user, then authenticate the user against the data store. When finished, the module decides whether to return a boolean success or failure flag.

The outcome of an authentication module can only be success or failure. Any branching or looping must be handled within the module. An authentication mechanism is implemented in full within a single module, rather than across multiple modules. Therefore, authentication modules can become large - handling multiple steps within the flow of an authentication journey.

Authentication nodes, however, can have an arbitrary number of outcomes that do not need to represent success or failure. Branching and looping are handled by connecting nodes within the tree and are fully controlled by the tree administrator, rather than the node developer. Nodes are often considerably smaller in terms of code size, and are responsible for handling a single step within the authentication flow. For example, an individual node could capture user input, another could make a decision based on available state, and another could invoke an external API.

Nodes expose this approach to the tree administrator. Unlike modules, where the journey through the module’s states is defined by the module’s developer, a journey through a collection of nodes may be different for each user.

Node developers should be aware of the expectations for a node to deliver a limited amount of specific functionality, which tree administrators can connect together in a variety of ways.

The ease of transitioning from a module to a node depends on the amount of functionality provided in the module. As nodes are more fine-grained than modules, split the functionality of the module into individual nodes which can then work together to provide functionality similar to the module, but in a more flexible manner.

An example of this approach was applied to the one-time password nodes, which were developed from the HOTP authentication module. The module performs the following duties:

The four distinct functions are encapsulated into separate nodes, allowing greater control over the one-time password process.

For example, a tree administrator who is only interested in sending one-time passwords by using SMS messages can omit the SMTP node. Separating out the decision functionality means that it can be combined with another decision node, or simply routed to an alternative authentication process.

Some authentication modules delegate their functionality to utility classes in AM, which simplifies the process of creating a similarly functioning node.

For example, the LDAP authentication module and LDAP Decision node share the LDAPAuthUtils class for LDAP authentication. In cases where such utility classes do not exist, consider extracting the common functionality used by the module into such a class, so that it can be more easily used by nodes. For information on sharing configuration, see Share configuration between nodes.

To determine the functionality of a node, reduce the node’s responsibility to its core purpose, while ensuring it performs sufficient tasks to be useful as a step in an authentication journey.

Before you create a set of nodes, assess the level of granularity the nodes should produce. For example, a customer’s environment may require a series of utility nodes which, on their own, do not perform authentication actions, but have multiple use cases in many authentication journeys. In this case, you can create nodes that take values from the shared state and save it to the user’s profile.

Individual nodes can respond to a variety of inputs and outputs, and return different sets of callbacks to the user without leaving the node. (This is similar to the state mechanism used by modules.)

The following guidelines help a node developer determine the best point at which to split a node into multiple instances:

ForgeRock provides a Maven archetype that creates a starter project, suitable for building an authentication node. You can also download the projects used to build the authentication nodes included with AM and modify those to match your requirements.

Complete either of the following steps to set up or download a Maven project to build custom authentication nodes:

When you configure a project for creating custom nodes, consider the following points:

To help protect against some of these issues, consider the following recommendations:

Configure the node properties using methods. To provide a default value to the tree administrator, mark the method as default and define both a method and a value. To omit a default value, define the method’s signature but not the implementation.

For example:

For this Config example, a custom enum named LockStatus is returned.

The defined properties appear as configurable options in the tree designer view when adding a node of the relevant type. The options display to the user automatically.

Attribute names are used when localizing the node’s text. For further information, refer to Internationalization.

For more information, refer to the Config annotation type in the AM Public API Javadoc.

The @Attribute annotation is required. You must specify an integer value for order, which determines the position of the attribute in the UI.

Optionally, specify one or more validators to validate the attribute values provided.

To include a validator:

For example:

1 The domain attribute defines a String-typed node property for display in the UI. Access the attribute in the process method by using a reference to the config interface; for example, config.domain().

2 Specify one or more validator classes as the validators parameter.

3 The boolean attribute is defined as a required value. Specifying requiredValue=true is equivalent to including the parameter validators = RequiredValueValidator.class.

4 Use the Password annotation to mask the input characters and encrypt the value of the attribute.

5 A custom enum attribute. This provides type safety and negates the misuse of Strings as generic type-unsafe value holders. The UI will correctly handle the enum and only let the tree administrator choose from the defined enum values.

For more information, refer to the Attribute annotation type in the AM Public API Javadoc.

You can share configuration between nodes that have common properties. For example, a number of nodes may call out to an external service that requires a username, password, IP address, and port setting.

Instead of repeating the same configuration in each of these nodes, create a shared, auxiliary service to hold the common properties in one node. You can then reference that service from other nodes.

The following sections explain how to create and reference this auxiliary service. The sections also describe how to run more than one instance of an auxiliary service if required, and how to obtain the configuration from services built-in to AM.

You can use Guice injection to cache information in a node by annotating the object that contains the cache with the @Singleton annotation, for example:

If just-in-time bindings are not sufficient for your use case, you can add your own Guice module into the injector configuration by implementing your own com.google.inject.Module and registering it using the service loader mechanism. For example:

The MyCustomModule object will then be automatically configured as part of the injector creation.

The Action class uses the following fields:

The Action class provides the following methods:

The inner class ActionBuilder provides the following methods for constructing the Action object and setting action-related properties:

Tree state exists for the lifetime of the authentication session. Once tree execution is complete, the authentication session is terminated and a user session is created. The purpose of tree state is to hold state between the nodes.

A good example is the Username Collector node, which gets the user name from the user and stores it the shared tree state. Later, the Data Store Decision node can pull this value from shared tree state and use it to authenticate the user.

Authentication sessions when using chains and modules are stateful - the AM server that starts the authentication flow must not change. A load balancer cookie is set on the responses to the user to ensure the same AM server is used.

In contrast, authentication trees can be made stateless, so that any AM instance in a deployment can continue the authentication session.

For more information on configuring sessions, see Sessions.

AM allows a node to read and write data to and from an identity’s profile. This is useful if a node needs to store information more permanently than when using either the authentication trees' NodeState, or the identity’s session.

Nodes use callbacks to enable interaction with the authenticating user.

AM doesn’t support creating your own custom callbacks, but there are many existing implementations available to you. Learn more in Supported callbacks.

Calling the getCallbacks(Class<t> callbackType) method on a TreeContext - the sole argument to the process() method of a node - returns all callbacks of a particular type for the most recent request from the current node. For example, calling context.getCallbacks(PasswordCallback.class) returns a list of the PasswordCallback callbacks displayed in the UI most recently.

Below is an example of multiple callbacks created by a node and passed to the UI:

To process the responses to callbacks, you must know the order of the callbacks in the list. You can find the position of the callbacks created by the current node by using the constant properties for each callback position in the processing node.

If the callbacks were created in previous nodes, their positions must be stored in the shared state before subsequent nodes can use them.

The following is the code that created the UI displayed in the previous image:

Note that the order of callbacks defined in code is preserved in the UI.

Authentication flow can return to the same decision node by using two different methods.

The first method is to route the failure outcome through a Retry Limit Decision node. This node can limit how many times a user can enter incorrect authentication details. In these instances, the user is returned to re-enter their information; for example, back to an earlier Username Collector node.

The second method involves routing directly back to the currently processing node. To achieve this, use the Action.send() method, rather than Action.goTo(). The Action.goTo method passes control onto the next node in the tree. The Action.send() method takes a list of callbacks which you can construct in the current node. The return value is an ActionBuilder, which can be used to create an Action, as follows:

A typical example of returning to the same node is a password change screen where the user must enter their current password, new password, and new password confirmation. The node that processes these callbacks needs to remain on the screen and display an error message if any of the data entered by the user is incorrect. For example, if the new password and password confirmation do not match.

When a ConfirmationCallback is invoked on a screen that was produced by Action.send(), it will always route back to the node that created it. Once the details are valid, return an Action created using Action.goTo() and tree processing can continue as normal.

The most common error to display is a message in the event of an unsuccessful authentication. In an authentication tree, this occurs when the authentication process terminates at the failure node:

By default, when a catastrophic error occurs during node processing, a NodeProcessException exception should be thrown, which halts the authentication journey immediately, and displays a generic error message. This may not be desirable, as it could create a negative user experience.

Instead, errors that occur during node processing should be caught within the processing block of the node’s code, and the user should be routed to an erroneous state outcome. It may be appropriate to have a single error outcome, multiple error outcomes, or no error outcome at all, depending on the node.

It is valuable to store information about the cause of the error in the shared state, in case a node further along the tree processes it. This information should include error text to display to the user. If the shared state is used for this purpose, it is important to document not only the meaning of the various outcomes, but also the keys used to store information in the shared state.

You can display error messages to the tree administrator; for example, when a configuration property of a node is required, but not provided.

To automatically display an appropriate error message when required values are missing, annotate your config property with @RequiredValueValidator, as follows:

To control the messages displayed on error, ensure there is a .properties file under src/main/resources/org.forgerock.openam.auth.nodes with the same name as your node class. For more information, see Internationalization.

This section explains how to upgrade nodes with simple schema changes. For example, changing an attribute to a compatible type.

When configuration schema changes are simple, call the PluginTools#upgradeAuthNode(Class) method in the upgrade method of your plugin, as follows:

Examples of simple schema changes include:

This section explains how to upgrade nodes that are changing the configuration schema such that existing values would clash with the new schema. For example, changing an attribute to an incompatible type.

When configuration schema changes are complex, use the API provided in the com.sun.identity.sm package. In this example, version 1.0.0 of a node has the following configuration schema:

Version 2.0.0 of the node requires the user’s given name and family name separately, rather than simply a name string. The config for version 2.0.0 is as follows:

To upgrade this example node configuration, find all existing instances of configuration created by the version 1.0.0 node, find the current values for the name attribute, and split it on the first space character to use in the two new attributes.

The following code shows how to upgrade the schema of this example node:

For information on upgrading custom nodes, refer to Upgrade nodes and change node configuration.

You can test authentication nodes in numerous ways. For example, you can use unit tests, functional tests, and perform exploratory or manual testing.

Authentication nodes are well suited to tests that have a high percentage of code coverage. The low number of static dependencies means that unit testing of the node class itself can occur, rather than simply the business logic classes, as was the case for modules. Furthermore, as nodes should be significantly smaller than modules, testing iterations should be much shorter.

Add debug logging to your custom node to help administrators and support staff investigate any issues which may arise in production.

To add debug logging to a node, obtain a reference to the amAuth SLF4J Logger instance.

For example, you can assign the logger to a private field as follows:

You can also use the SLF4J varargs methods to defer string concatenation to SLF4J. This means string concatenation can be skipped if the configured logging level means that your message will not be written.

The following example uses the debug level:

Audit logging helps administrators to investigate user and system behavior.

AM records all incoming calls as access events. Additionally, in order to capture further details regarding authentication flows, AM records an authentication audit event for each node, and the tree outcome.

A node can provide extra data to be included in the standard audit event which is logged when an authentication node completes.

AM logs an AM-NODE-LOGIN-COMPLETED audit event each time an authentication node completes. To add extra information to this audit event, override the node interface method getAuditEntryDetail.

For example, the Retry Limit Decision node overrides this method to record how many retries remain:

When this node is processed, it results in an audit event similar to the following:

The result of the getAuditEntryDetail method is stored in the nodeExtraLogging field.

You can track authentication flows which complete with success, failure, or timeout as an outcome by using the metrics functionality built-in to AM.

For more information, see Monitor AM instances.

You can also use the following nodes in a tree to create custom metrics: