Product names changed when ForgeRock became part of Ping Identity.

The following name changes have been in effect since early 2024:

Learn more about the name changes in New names for ForgeRock products in the Knowledge Base.

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.

To determine the functionality of a node, reduce the node’s responsibility to its core purpose. For example, the Password Collector node just captures the user’s password.

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 that, on their own, don’t 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.

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

Ping Identity 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:

When developing nodes that include sensitive data such as passwords and encryption keys, make sure the data is secured:

Make sure you use well-known and trusted cryptographic libraries where appropriate.

Different algorithms and methods are discovered and tested over time, and communities of experts decide which are the most secure for different uses. Use up-to-date cryptographic methods and algorithms to generate keys.

When developing nodes that accept user input data, sanitize the input data and remove any sensitive information, such as passwords, before using and storing the data. Don’t use unsanitized user input data for any purpose.

Where a node reads data from the shared state, always treat that data as user input data and sanitize accordingly.

The outcomeProvider class defines the possible node outcomes.

The abstract implementations of the node interface, org.forgerock.openam.auth.node.api.SingleOutcomeNode and org.forgerock.openam.auth.node.api.AbstractDecisionNode, define outcome providers you can use for simple use cases. Provide your own implementation for more complex use cases.

To ensure the node is available to the Configuration Provider node, your outcome provider class must implement the StaticOutcomeProvider or the BoundedOutcomeProvider interfaces.

Learn more about these implementations and interfaces in the org.forgerock.openam.auth .node.api package.

For example, the following is the custom outcome provider from the LDAP Decision node, which has True, False, Locked, Cancelled, and Expired exit paths:

The configClass contains the configuration of any attributes requested by the node when using it as part of a tree.

Learn more in the Config interface.

The optional configValidator class validates the provided configuration at the class level. This can be useful when you have two attributes that depend on each other for validation. For example, an attribute is only required if another attribute is set to true.

The configValidator class must implement the ServiceConfigValidator interface.

For example, the following is the @Node.Metadata annotation for the Message node:

Where the MessageNode.MessageNodeValidator.class validates the locales entered:

The optional extensions class provides additional metadata information about the node. The Java class is serialized into JSON.

For example, the following is the @Node.Metadata annotation for the Username Collector node with an extensions class added:

Where the UsernameCollectorNode.ExtraMetadata.class adds extra metadata:

The getType() response for this node includes this metadata:

The optional tags attribute contains a list of tags to categorize the node within the tree designer view.

Tags are made up of one or more text strings that let users find the node more easily when designing trees. For example, you could include common pseudonyms for the functionality the node provides, such as mfa for a node that provides multi-factor authentication functionality.

The tree designer view organizes nodes into a number of categories, based on the presence of certain tag values, as described in the table below:

For example, the @Node.Metadata annotation for Timer Start node places it in the Utilities section:

Learn more in the Annotation Interface Node.Metadata.

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. Learn more in Internationalize nodes.

You can find more information in the Config annotation type in the AM Public API Javadoc.

The @Attribute annotation is required. It defines the properties that appear as configurable options when you add or update a node.

Consider the following when using the @Attribute annotation:

For example:

1 The domain attribute defines a String-type 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.

4 Use the TextArea annotation to indicate a String-type node property that needs a larger text input than a single line.

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

6 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.

Learn more in the Attribute annotation type in the AM Public API Javadoc.

7 An identifier used to create a secret label for the node that maps to a secret in a secret store. The default custom authentication node secret label is am.authentication.nodes.customauth.%s.secret where %s is the value of the identifier. The identifier can only contain alphanumeric characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

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:

You can use Guice injection to send an HTTP request by injecting the CloseableHttpClientHandler into the node instance. This means the node uses the standard AM HTTP client handler, and all the httpClient settings and tuning apply.

The following example demonstrates sending an HTTP POST request to the https://www.example.com/api endpoint:

If just-in-time bindings aren’t 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 static methods to create an ActionBuilder:

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

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, add requiredValue=true to your config property, 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. Learn more in Internationalize nodes.

Always store the authentication state in the NodeState object that AM lets you access from the TreeContext object passed to the node’s process() method. AM ensures the node state is made available to downstream nodes:

Internally, AM distinguishes the following node state data:

Learn more in NodeState.

Use the IdUtils static class:

If AM is configured to search for the identity’s profile using a different search attribute than the default, provide the attributes as a third argument to the method.

To obtain the attributes, you could request them in the configuration of the node or obtain them from the realm’s authentication service configuration.

The following example demonstrates how to obtain the user alias:

By combining these approaches, you can search for an identity by using the ID and whichever configured attribute field(s) as necessary.

After obtaining the profile, use the AMIdentity.getAttribute(String name) method.

Create a Map<String, Set<String>> structure of the attributes you want to write, as follows:

A node can provide JavaScript for execution on the client-side browser.

For example, the following is a simple JavaScript script named hello-world.js:

Execute the script on the client by using the following code:

Variables can be injected using your favorite Java String utilities, such as String.format(script, myValue).

To retrieve the data back from the script, add HiddenValueCallback to the list of callbacks sent to the user, as follows:

The JavaScript needs to add the required data to the HiddenValueCallback and submit the form, for example:

In the process method of the node, retrieve the hidden callback as follows:

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 multiple ways, including unit tests, functional tests, and performing 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 lets you unit test the node class as well as the business logic classes.

You might need to debug your nodes during development as well as prepare your nodes to allow debug logging after they are deployed.

Audit logging helps administrators to investigate user and system behavior.

AM records all incoming calls as access events. Additionally, to capture further details about the 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 that complete with success, failure, or timeout as an outcome by using the metrics functionality built-in to AM.

Learn more in Monitor AM instances.

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