PingAM 8.0.0

Action class

The Node class returns an Action instance from its process() method.

The Action class encapsulates changes to authentication tree state and flow control.

For example, the following implementation demonstrates an authentication level decision:

@Override
public Action process(TreeContext context) throws NodeProcessException {
  NodeState state = context.getStateFor(this);
  if (!state.isDefined(AUTH_LEVEL)) {
    throw new NodeProcessException("Auth level is required");
  }
  JsonValue authLevel = state.get(AUTH_LEVEL);
  boolean authLevelSufficient =
    !authLevel.isNull()
    && authLevel.asInteger() >= config.authLevelRequirement();
  return goTo(authLevelSufficient).build();
}

Learn more in the Action class.

Action fields and methods

The Action class uses the following fields:

Fields Description

callbacks

A list of the callbacks requested by the node. This list may be null.

errorMessage

A custom error message string included in the response JSON if the authentication tree reaches the Failure node authentication node.

Each node in a tree can replace or update the error message string as the user traverses through the authentication tree.

If required, your custom node or custom UI must localize the error string.

lockoutMessage

A custom lockout message string included in the response JSON when the user is locked out.

If required, your custom node or custom UI must localize the error string.

outcome

The result of the node.

returnProperties

A map of properties returned to the client.

Use the withHeader, withStage, and withDescription methods to add a property to the map.

sessionHooks

The list of classes implementing the TreeHook interface that run after a successful login.

sessionProperties

A map of properties added to the final session if the authentication tree completes successfully.

Use putSessionProperty(String key, String value) and removeSessionProperty(String key) to add or remove entries from the map.

sharedState and transientState

Deprecated.

Use the NodeState object instead. Learn more in Store values in a tree’s node states.

webhooks

The list of webhooks that run after logout.

Use the addWebhook and addWebhooks methods to populate this list.

The Action class provides the following static methods to create an ActionBuilder:

Methods Description

goTo

Specify the exit path to take, and move on to the next node in the tree.

For example:

return goTo(false).build();

send

Send the specified callbacks to the user for them to interact with.

For example, the Username Collector node uses the following code to send the NameCallback callback to the user to request the USERNAME value:

return send(new NameCallback(bundle.getString("callback.username"))).build();

sendingCallbacks

Returns true if the action is a request for input from the user.

suspend

Suspends the authentication tree and lets the user resume it from the point it was suspended. You can also control how long it is suspended for.

For example, the following call is taken from the Email Suspend node:

return suspend(resumeURI -> createSuspendOutcome(context, resumeURI, recipient, templateObject)).build();

Use the SuspensionHandler interface for handling the suspension request.

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

Methods Description

addNodeType

Add a node type to the session properties and shared state. Replace any existing shared state with the specified TreeContext’s shared state.

addSessionHook and addSessionHooks

Add one or more session hook classes for AM to run after a successful login.

addWebhook and addWebhooks

Add one or more webhook names to the list of webhooks.

build

Creates and returns an Action instance providing the mandatory fields are set.

putSessionProperty

Add a new session property.

removeSessionProperty

Remove the specified session property.

replaceSharedState and replaceTransientState

Deprecated.

Use the NodeState object instead. Learn more in Store values in a tree’s node states.

withDescription

Set a description for this action.

withErrorMessage

Set a custom message for when the authentication tree reaches the failure node.

withHeader

Set a header for this action.

withIdentifiedIdentity

Add an identity, authenticated or not, that is confirmed to exist in an identity store. Specify the username and identity type or an AMIdentity object.

Use this method to record the type of identified user. If the advanced server property, org.forgerock.am.auth.trees.authenticate.identified.identity is set to true, AM uses the stored identified identities to decide which user to log in.

This lets the authentication tree engine correctly resolve identities that have the same username.

Learn more in advanced server properties.

withLockoutMessage

Set a custom message for when the user is locked out.

withMaxIdleTime

Set the maximum idle time for the authenticated session in minutes.

This overrides the maximum idle time set in the journey or the Session service.

If a user has session timeouts set, the user-specific settings are always used.

withMaxSessionTime

Set the maximum authenticated session time in minutes.

This overrides the maximum authenticated session time set in the journey or the Session service.

If a user has session timeouts set, the user-specific settings are always used.

withStage

Set a stage name to return to the client to aid the rendering of the UI. The property is only sent if the node also sends callbacks.

withUniversalId

Deprecated.

Use withIdentifiedIdentity instead.