Nodes and trees

Authentication trees 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 customer-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.

Figure 1. Example authentication tree

AM provides the following default trees: ldapService, Agent and amsterService. Learn more in Default trees.

You can use trees to further control the authentication process. The following table describes some examples of how you can do this.

Task	Resource
Assign authentication levels to branches on a tree, with higher levels typically used to allow access to more restricted resources.	Authentication levels for trees
Use individual nodes to handle session property management.	Set Session Properties node
Call out to third-party systems by using scripted nodes.	Scripted Decision node
Use webhooks to register events to make HTTP POST calls to a server.	Configure webhooks

Task

Resource

Assign authentication levels to branches on a tree, with higher levels typically used to allow access to more restricted resources.

Authentication levels for trees

Use individual nodes to handle session property management.

Set Session Properties node

Call out to third-party systems by using scripted nodes.

Scripted Decision node

Use webhooks to register events to make HTTP POST calls to a server.

Configure webhooks

Authentication levels for trees

When a user successfully authenticates, AM creates a session, which allows AM to manage the user’s access to resources. The session is assigned an authentication level. The authentication level is often used as a measure of the strength of the authentication performed. For example, username and password could be assigned a low authentication level, and multi-factor with Push and webAuthn could be assigned a high one.

Authorization policies could require a particular authentication level to access protected resources. When an authenticated user tries to access a protected resource without satisfying the authentication level requirement, AM denies access to the resource and returns an advice indicating that the user needs to reauthenticate at the required authentication level to access the resource.

The web or Java agent or policy enforcement point can then send the user back to AM for session upgrade. Learn more in Session upgrade

AM provides the following nodes to manage authentication levels:

The Authentication Level Decision node, which checks if the current authentication level is equal or greater than the one specified in the node.
The Modify Authentication Level node, which can raise or lower the authentication level.

Position these nodes to alter the authentication level depending on the route taken through the authentication tree.

Account lockout for trees

Use account lockout to limit the number of times an end user can attempt to authenticate with invalid credentials before rendering their account inactive. Limiting the number of attempts helps to prevent password-guessing and brute-force attacks.

By default, authentication trees support account lockout and provide nodes for checking and changing a user’s status:

Account Active Decision node

Use this node to determine whether an account is locked or unlocked.

An account is considered locked under these conditions:
- The status is inactive.
- The status is active and a duration lockout is set on the account.
An account is considered unlocked under this condition:
- The status is active and no duration lockout is set on the account.

Account Lockout node

Use this node to change the account’s status to inactive or active.

When setting an account to inactive, the node doesn’t consider the realm’s account lockout settings, so effectively sets a persistent lockout on the account.

When setting an account to active, the node also resets the failed attempts and lockout duration counters.

In addition to the lockout-specific nodes above, the Success and Failure nodes include account lockout functionality, when lockout is enabled in a realm, as follows:

Success node

Checks the User Status property of the user profile, when reached, and fails the authentication with an error message, if the account is marked as Inactive:

The error message is returned in the JSON response if authenticating to the tree by using REST:
```
{
    "code":401,
    "reason":"Unauthorized",
    "message":"User Locked Out."
}
```
Resets the failure count in the user profile, when reached, if the User Status property is set to Active.

Failure node

Checks the invalid attempts property of the user profile, and returns a warning message if the number of failed attempts is equal to or greater than the configured Warn User After N Failures value in the realm:

The error message is returned in the JSON response if authenticating to the tree by using REST:
```
{
    "code":401,
    "reason":"Unauthorized",
    "message":"Warning: You will be locked out after 1 more failure(s)."
}
```
Increments the failure count in the user profile, when reached.
Returns an error message if the account is marked as Inactive:

The error message is returned in the JSON response if authenticating to the tree by using REST:
```
{
    "code":401,
    "reason":"Unauthorized",
    "message":"User Locked Out."
}
```

You can find information on configuring account lockout in a realm in Account lockout.

PingAM 8.0.0

Nodes and trees

Authentication levels for trees

Account lockout for trees