Handling Errors

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

@Attribute(order = 300, validators = {RequiredValueValidator.class})
Set<String> accountSearchBaseDn();

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, seeInternationalization.