Authentication Nodes Configuration Reference

Data Store Decision Node

The Data Store Decision authentication node verifies that the username and password values exist in the data store configured in the realm.

For example, the username and password could be obtained by a combination of the Username Collector and Password Collector nodes, or the Zero Page Login Collector node.

Tree evaluation continues along the True path if the credentials are located in the configured data store. Otherwise, the tree evaluation continues along the False path.

Properties:

This node has no configurable properties.

Kerberos Node

The Kerberos authentication node enables desktop single sign-on such that a user who has already authenticated with a Kerberos Key Distribution Center can authenticate to AM without having to provide the login information again.

To achieve this, the user presents a Kerberos token to AM through the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) protocol.

End users may need to set up Integrated Windows Authentication in Internet Explorer or Microsoft Edge to benefit from single sign-on when logged on to a Windows desktop.

Tree evaluation continues along the True path if Windows Desktop SSO is successful. Otherwise, the tree evaluation continues along the False path.

Properties:

C:\> ktpass -out fileName.keytab -princ HTTP/openam.example.com@AD_DOMAIN.COM -pass +rdnPass -maxPass 256 -mapuser amKerberos@frdpcloud.com -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -kvno 0

Example:

This flow will attempt to authenticate the user, by using Windows Desktop SSO. If unsuccessful, AM will request the username and password for login. Meter nodes are used to track metrics for the various paths through the tree.

Kerberos Example Tree

LDAP Decision Node

The LDAP Decision authentication node verifies that the provided username and password values exist in a specified LDAP user data store, and whether they are expired or locked out.

For example, the username and password could be obtained by a combination of the Username Collector and Password Collector nodes, or by using the Zero Page Login Collector node.

Tree evaluation continues along the True outcome path if the credentials are located in the specified LDAP user data store. If the profile associated with the username and password is locked, or the password has expired, tree evaluation continues along the respective Locked or Expired outcome paths. If the user needs to change their password on first login, but cancels the password change form, tree evaluation continues along the Cancelled outcome path.

If the credentials are not found, the tree evaluation continues along the False outcome path.

Properties:

Password Collector Node

The Password Collector authentication node prompts the user to enter their password. The captured password is transient, persisting only until the authentication flow reaches the next node requiring user interaction.

Tree evaluation continues along the single outcome path after capturing the password.

Properties:

This node has no configurable properties.

Username Collector Node

The Username Collector authentication node prompts the user to enter their username.

Tree evaluation continues along the single outcome path after capturing the username.

Properties:

This node has no configurable properties.

Zero Page Login Collector Node

The Zero Page Login Collector authentication node checks whether selected headers are provided in the incoming authentication request, and if so, uses their value as the provided username and password.

Tree evaluation continues along the Has Credentials outcome path if the specified headers are available in the request, or the No Credentials path if the specified headers are not present.

A common use for the Zero Page Login Collector authentication node is to connect the Has Credentials outcome connector to the input of a Data Store Decision node, and the No Credentials outcome connector to the input of a Username Collector node followed by a Password Collector node, and then into the same Data Store Decision node as earlier. For an example of this layout, see the default Example authentication tree provided in AM. See "Example Tree With Zero Page Login Node".

The password collected by the Zero Page Login Collector node is transient, persisting only until the authentication flow reaches the next node requiring user interaction.

Properties:

Example:

Example Tree With Zero Page Login Node

Get Authenticator App Node

The Get Authenticator App node presents the user with links to obtain your authenticator app from the Apple App Store or the Google Play store.

Tree evaluation continues along the single outcome path when the user clicks the Continue button.

Properties:

HOTP Generator Node

The HOTP Generator authentication node creates a string of random digits, of the length specified. The default length is 8 digits.

Passwords are stored in the oneTimePassword transient state property of the authentication tree.

Properties:

Use alongside the following authentication nodes to add one-time password verification to the authentication tree:

Example:

HmacOneTimePassword Tree With HOTP Generator Node {AM)

HmacOneTimePassword Tree With HOTP Generator Node (ForgeRock Identity Platform)

MFA Registration Options Node

The MFA Registration Options node lets the user register a multi-factor authentication device or skip the registration process.

The node requires the username of the identity to update; for example, by using a "Username Collector Node" , and also the type of MFA device; for example, by placing a "Push Sender Node" node earlier in the authentication journey.

Properties:

Tree evaluation continues along whichever outcome the user selects when presented with the options.

Example:

OATH Registration Node

The OATH Registration node lets the user register a device for OATH-based multi-factor authentication (MFA). Based on the node properties, the user device displays a QR code that includes all the details required for registration. If registration is successful, the node stores the device data, recovery codes (if enabled), and sets the skippable attribute to prevent repeat registration at next login.

The node requires the credentials of the user; for example, by using a sequence of the following nodes earlier in the authentication journey:

Connect the OATH Registration node's Success outcome path to the "OATH Token Verifier Node" to continue to OTP verification.

View the OATH Token Verifier Node example to see how these nodes can be used in combination with other MFA nodes to create a complete OATH authentication journey.

Properties:

If registration is successful and the device details are stored, tree evaluation continues along the Success outcome path. If AM encounters an issue during the registration process, or the user fails to complete registration, evaluation proceeds along the Failure path.

OATH Token Verifier Node

The OATH Token Verifier node requests and verifies a one-time password (OTP) generated by a device such as a mobile phone. The default configuration is time-based OTP (TOTP), but the node also supports HMAC (HOTP).

The node requires that the user credentials are authenticated, and that the user has previously registered a device using the "OATH Registration Node". These two nodes work together to provide all the capabilities of a secure OATH authentication journey.

They can also be used in combination with other MFA nodes to extend these capabilities, for example:

For a visual overview of how the OATH nodes can be used within an authentication tree layout, see the "OATH Registration Node" example.

Properties:

Tree evaluation continues along one of the following outcome paths:

Example

Opt-out Multi-Factor Authentication Node

The Opt-out Multi-Factor Authentication node sets the Skippable attribute in the user's profile, which lets them skip MFA.

The node requires the username of the identity to update; for example, by using a "Username Collector Node" , and also the type of MFA device to set as "skippable." For example, by placing a "Push Sender Node" node earlier in the authentication journey.

Tree evaluation continues along the single outcome path after setting the MFA device as "skippable" in the users' profile.

Properties:

This node has no configurable properties.

OTP Collector Decision Node

The OTP Collector Decision authentication node requests and verifies one-time passwords.

Tree evaluation continues along the True outcome path if the entered one-time password is valid for the authentication in progress. Otherwise, the tree evaluation continues along the False outcome path.

Properties:

OTP Email Sender Node

The OTP Email Sender authentication node sends an email containing a generated one-time password to the user.

Send mail requests will timeout after 10 seconds.

Properties:

OTP SMS Sender Node

The OTP SMS Sender authentication node uses an email-to-SMS gateway provider to send an SMS message containing a generated one-time password to the user.

The node sends an email to an address formed by joining the following values together:

For example, if configured to use the TextMagic email-to-SMS service, the node might send an email through the specified SMTP server to the address: 18005550187@textmagic.com.

Properties:

Push Registration Node

The Push Registration authentication node provides a way to register a device, such as a mobile phone, for multi-factor authentication using push notifications. For more information, see MFA: Push Authentication.

If the user successfully registers their authenticator, then tree evaluation continues along the Success outcome path.

If the node does not receive a response from the users' device within the time specified in the node configuration, evaluation continues along the Time Out outcome path.

If AM encounters an issue when attempting to register using a device, tree evaluation continues along the Failure outcome path.

The node requires the username of the identity to update; for example, by using a "Username Collector Node".

You must also configure the Push Notification Service.

For information on provisioning the credentials required by the Push Notification Service, see How To Configure Service Credentials (Push Auth, Docker) in Backstage in the ForgeRock Knowledge Base.

For detailed information about the available properties, see "Push Notification Service".

Properties:

Property	Usage
Issuer	Specify an identifier so that the user knows which service their account relates to. The value is displayed by the authenticator app: For example, Example Inc., or the name of your application.
Account Name	Specifies the profile attribute to display as the username in the authenticator app. If not specified, or if the specified profile attribute is empty, their username is used.
Registration Response Timeout	Specify the number of seconds to wait for a response from the authenticator. If the specified time is reached, tree evaluation continues along the Time Out outcome path.
Background Color	Specifies the background color, in hex notation, to display behind the issuer's logo within the ForgeRock Authenticator app.
Logo Image URL	Specifies the location of an image to download and display as the issuer's logo within the ForgeRock Authenticator app.
Generate Recovery Codes	Specify whether push-specific recovery codes should be generated. If enabled, recovery codes are generated and stored in transient state if registration was successful. Use the Recovery Code Display Node to display the codes to the user for safe keeping. Important Generating recovery codes will overwrite all existing push-specific recovery codes. Only the most recent set of recovery codes can be used for authentication if a device has been lost or stolen.
QR code message	The message with instructions to scan the QR code to register the device. Click Add. Enter the message locale in the Key field; for example en-gb. Enter the message to display to the user in the Value field.

Example:

Example Push Tree (Standalone AM)

Example Push Tree (ForgeRock Identity Platform)

The example tree above shows a possible implementation of a tree for handling push devices.

After verifying the users credentials against the configured data store, tree evaluation continues to the Push Sender Node.

If the user does not yet have a registered device, the MFA Registration Options Node displays the following options:

Once the registration is complete the path returns to the Push Sender Node, which starts the actual push notification stage of the journey.

A polling loop using the Polling Wait Node in combination with the Push Result Verifier Node continuously checks whether the user has successfully responded to the push notification.

An option displayed on the Polling Wait Node lets the user exit that loop, and instead provide one of their push-specific recovery codes, letting them log in if they have lost their device, for example.

Note that in order for a user to manage their registered push devices, they must log in using either the device, or a recovery code. For more information, see Managing Devices for MFA.

Push Result Verifier Node

The Push Result Verifier node works together with the Push Sender Node to validate the user's response to a previously sent push notification message.

Tree evaluation continues along the Success outcome path if the push notification was positively responded to by the user. For example, using the ForgeRock Authenticator app, the user slid the switch with a checkmark on horizontally to the right.

Tree evaluation continues along the Failure outcome path if the push notification was negatively responded to by the user. For example, using the ForgeRock Authenticator app, the user tapped the cancel icon in the top-right of the screen.

If the push notification was not responded to within the Message Timeout value specified in the Push Sender Node then tree evaluation continues along the Expired outcome path.

If a response to the push message has not yet been received, then tree evaluation continues along the Waiting outcome path.

Properties:

This node has no configurable properties.

Push Sender Node

The Push Sender authentication node sends push notification messages to a device such as a mobile phone, enabling multi-factor authentication.

The Push Sender authentication node requires that the Push Notification Service has also been configured. For information on the properties used by the service, see "Push Notification Service" . For information on provisioning the credentials used by the service, see How To Configure Service Credentials (Push Auth, Docker) in Backstage in the ForgeRock Knowledge Base.

Tree evaluation continues along the Sent outcome path if the push notification was successfully sent to the handling service.

If the user does not have a registered device, tree evaluation continues along the Not Registered outcome path. To determine whether the user has a registered device, the tree must have already acquired a username, for example by using a "Username Collector Node" .

If the user chooses to skip push authentication, tree evaluation continues along the Skipped outcome path. You can configure whether the user is able to skip the node by setting the Two Factor Authentication Mandatory property. See "Letting Users Opt Out of One-Time Password Authentication (OATH)".

Properties:

Example:

Example Push Tree (Standalone AM)

Example Push Tree (ForgeRock Identity Platform)

The example tree above shows one possible implementation of multi-factor push authentication.

If the user has a registered device:

If the user does not have a registered device:

If the configuration allows it and the user chooses to skip multi-factor authentication:

Recovery Code Collector Decision Node

The Recovery Code Collector Decision authentication node allows users to authenticate using a recovery code provided when registering a device for multi-factor authentication.

Use this node when a tree is configured to use push notifications or one-time passwords but the user has lost the registered device, and must therefore use an alternative method for authentication. For more information on viewing the recovery codes when registering a device, see "Registering the ForgeRock Authenticator for Multi-Factor Authentication".

Tree evaluation continues along the True outcome path if the provided recovery code matches one belonging to the user. To determine whether the provided code belongs to the user, the tree must have already acquired the username, for example by using a "Username Collector Node" .

If the recovery code does not match, or a username has not been acquired, tree evaluation continues along the False outcome path.

Properties:

Recovery Code Display Node

The Recovery Code Display node is used in conjunction with the WebAuthn Registration Node or Push Registration Node . It retrieves generated recovery codes from the transient state and presents them to the user, for safe-keeping. The codes can be used to authenticate if a registered device is lost or stolen.

Generated recovery codes are inserted into transient state when tree evaluation continues along the Success outcome path of the MFA nodes, if they are configured to generate recovery codes. Connect the Recovery Code Display node to the Success outcome path to display the codes.

If no recovery codes are available in transient state, tree evaluation continues along the only outcome path, and nothing is displayed to the user.

Properties:

This node has no configurable properties.

Example:

The following is an example of the output of the Recovery Code Display node:

Example output of the Recovery Code Display node

WebAuthn Authentication Node

The WebAuthn Authentication node allows users of supported clients to use a registered FIDO device during authentication.

To determine whether the user has a registered device, the tree must have already acquired a username, for example by using a "Username Collector Node" .

If the user's client does not support web authentication, tree evaluation will continue along the Unsupported outcome path. For example, clients connected over the HTTP protocol rather than HTTPS do not support WebAuthn. ^[4]

If the user does not have a registered device, tree evaluation continues along the No Device Registered outcome path.

If AM encounters an issue when attempting to authenticate using the device, tree evaluation continues along the Failure outcome path. For example, AM could not verify that the response from the authenticator was appropriate for the specific instance of the authentication ceremony.

If the user's client encounters an issue when attempting to authenticate using the device, for example, if the timeout was reached, then tree evaluation continues along the Client Error outcome path. This outcome is used whenever the client throws a DOMException, as required by the Web Authentication: An API for accessing Public Key Credentials Level 1 specification.

If the Allow recovery code property is enabled, AM provides the user the option to enter a recovery code rather than authenticate using a device. Tree evaluation continues along the Recovery Code outcome path if the users chooses to enter a recovery code. To accept and verify the recovery code, ensure the outcome path leads to a Recovery Code Collector Decision Node.

If the user successfully authenticates with a device of the type determined by the User verification requirement property, tree evaluation continues along the Success outcome path.

Properties:

Example:

Example WebAuthn Authentication Tree (Standalone AM)

Example WebAuthn Authentication Tree (ForgeRock Identity Platform)

The example tree above shows one possible implementation of a tree for authenticating with WebAuthn devices.

After verifying the users credentials against the configured data store, tree evaluation continues to the WebAuthn Authentication Node.

If the user's client does not support WebAuthn, the tree fails and the user does not get a session. A more user-friendly approach would be to set a success URL to redirect the user to a page explaining the benefits of multi-factor authentication, and then proceeding to the Success node.

If there are no registered WebAuthn devices present in the user's profile, the failure URL is set, pointing to a tree that allows the user to register a device. This stage could also be an Inner Tree Evaluator, with a registration tree inside.

If the user's client does support WebAuthn, and the connection is secured with TLS, the user will be asked to complete an authorization gesture, for example scanning a fingerprint, or entering a PIN number:

The WebAuthn Authentication node waiting for an authenticator (Standalone AM)

The WebAuthn Authentication node waiting for an authenticator (ForgeRock Identity Platform)

The user's browser may present a consent pop-up to allow access to the authenticators available on the client. When consent has been granted, the browser activates the relevant authenticators, ready for authentication.

The authenticators the client activates for authentication depends in the value of the properties in the node. For example, if the User verification requirement property is set to REQUIRED, the client SHOULD only activate authenticators which verify the identity of the user. For extra protection, AM WILL verify that the response from an authenticator matches the criteria configured for the node, and will reject - by using the Failure outcome - an authentication attempt by an inappropriate authenticator type.

When the user completes an authorization gesture, for example scanning a fingerprint, or entering a PIN number, tree evaluation continues along the Success outcome path. In this example, their authentication level is increased by ten to signify the stronger authentication that has occurred, and the user is taken to their profile page.

If the user clicks the Use Recovery Code button, tree evaluation continues to the Recovery Code Collector Decision Node, ready to accept the recovery code. If verified, the user is taken to their profile page.

Any problems encountered during the authentication (thorugh the Failure outcome), including a timeout (through the Client Error outcome), results in the overall failure of the authentication tree.

WebAuthn Device Storage Node

The WebAuthn Device Storage node writes information about FIDO2 devices to a user's profile, so that they can subsequently authenticate using the device.

Use this node to store the device data that the "WebAuthn Registration Node" places into the tree's transient state when its Store device data in transient state property is enabled.

If AM encounters an issue when attempting to save the device data to the user's profile; for example, the user has not been identified earlier in the tree, then tree evaluation continues along the Failure outcome path.

If the node successfully stores the device data to the user's profile, tree evaluation continues along the Success outcome path.

Properties:

WebAuthn Registration Node

The WebAuthn Registration authentication node allows users of supported clients to register FIDO2 devices for use during authentication.

AM interacts with FIDO2/WebAuthn capable browsers, for example Chrome, Firefox and Microsoft Edge. These browsers interact with CTAP2 authenticators, including U2F and FIDO2 Security Keys, and platforms such as Windows Hello or MacOS TouchId

If the user's client does not support WebAuthn, tree evaluation will continue along the Unsupported outcome path. For example, clients connected over the HTTP protocol rather than HTTPS do not support WebAuthn.^[4]

If AM encounters an issue when attempting to register using a device, tree evaluation continues along the Failure outcome path. For example, AM could not verify that the response from the authenticator was appropriate for the specific instance of the authentication ceremony.

If the user's client encounters an issue when attempting to register using a device, for example, if the timeout was reached, then tree evaluation continues along the Client Error outcome path. This outcome is used whenever the client throws a DOMException, as required by the Web Authentication: An API for accessing Public Key Credentials Level 1 specification.

If the user successfully registers an authenticator of the correct type as determined by the node's properties, tree evaluation continues along the Success outcome path.

Properties:

Example:

Example WebAuthn Registration Tree (Standalone AM)

Example WebAuthn Registration Tree (ForgeRock Identity Platform)

The example tree above shows a possible implementation of a tree for registering WebAuthn devices.

After verifying the users credentials against the configured data store, tree evaluation continues to the WebAuthn Registration Node.

If the user's client does not support WebAuthn, the failure URL is altered, for example to redirect the user to a page explaining which clients and operating systems support WebAuthn.

If the user's client does support WebAuthn, and the connection is secured with TLS, the user will be asked to register an authenticator:

The WebAuthn Registration node waiting for an authenticator (Standalone AM)

The WebAuthn Registration node waiting for an authenticator (ForgeRock Identity Platform)

The user's browser may present a consent pop-up to allow access to the authenticators available on the client. When consent has been granted the browser activates the relevant authenticators, ready for registration.

The authenticators the client activates for registration depends in the value of the properties in the node. For example, if the User verification requirement property is set to REQUIRED, the client would not activate a USB hardware security key for registration.

When the user completes an authorization gesture, for example scanning a fingerprint, or entering a PIN number, tree evaluation continues along the Success outcome path, and in this example will be taken to their profile page.

The registered authenticator appears on the user's dashboard page, with the label New Security Key. To rename the authenticator, click its vertical ellipsis context icon (  ), and then click Rename.

Any problems encountered during the registration, including a timeout, results in tree evaluation continuing to the Failure outcome.

Account Active Decision Node

Checks if the account the user has entered is activated. This node relies on the tree's shared state to determine which account to check. Use this node to validate whether an account is currently activated, such as in login flows where an account may already be created, but not enabled until a later date.

For more information, see "About Account Lockout for Trees".

Properties:

This node has no configurable properties.

Account lockout Node

The Account lockout node can lock or unlock the authenticating user's account profile.

For more information, see "About Account Lockout for Trees".

Properties:

Example:

The following example uses the Account lockout Decision authentication node with the Retry Limit Decision Node to lock an account after a number of invalid attempts:

RetryLimit Tree With Account lockout Decision Node (Standalone AM)

RetryLimit Tree With Account lockout Decision Node (ForgeRock Identity Platform)

Auth Level Decision Node

The Auth Level Decision authentication node compares the current authentication level value against a configured value.

Properties:

Modify Auth Level Node

The Modify Auth Level authentication node lets you increase or decrease the current authentication level value.

Tree evaluation continues along the single outcome path after modifying the authentication level.

Properties:

CAPTCHA Node

The CAPTCHA node implements Google's reCAPTCHA v2 widget and hCaptcha's hCaptcha v1 widget, to add CAPTCHA support to authentication trees. This node verifies the response token received from Google or hCaptcha and creates a CAPTCHA callback for the UI.

The node is configured by default for Google's reCAPTCHA.

Properties:

Example:

Example Tree With CAPTCHA Node (Standalone AM)

Example Tree With CAPTCHA Node (ForgeRock Identity Platform)

Increment Login Count Node

Increments the successful login count property of a managed object in IDM.

Use this node in conjunction with the "Login Count Decision Node". If you plan to track the number of logins, include this node in your login authentication flow, but you can safely omit it if you are not planning to use that functionality.

Properties:

Login Count Decision Node

Triggers an action when a user's successful login count property reaches a specified number.

The action can either be triggered once, by setting the interval property to happen AT the set amount of successful login attempts; or set to occur EVERY time the specified number of additional successful login attempts occur.

Use this node in conjunction with the "Increment Login Count Node". The Increment Login Count Node needs to be present in your login authentication flow for the Login Count Decision Node to have the data necessary to trigger a decision.

Properties:

Certificate Collector Node

This node collects an X.509 digital certificate from the request coming from the authenticating user so that AM can use it as the user's credentials.

The tree continues through the Collected path if AM collects the digital certificate, and through the Not Collected path, otherwise.

To validate the certificate, add a "Certificate Validation Node" to the tree.

Properties:

Certificate Validation Node

This node validates a digital X.509 certificate collected by the "Certificate Collector Node".

The node has different outcomes, some of which are used depending on the configuration of the node:

When the outcome is True, append a "Certificate User Extractor Node" to extract the values of the certificate and return them to AM.

Properties:

Example:

The following is an example of how to use the certificate nodes. Note that all the failure outcomes of the "Certificate Validation Node" are linked so that the user provides a username and password, but you could choose different authentication methods for each outcome.

Certificate Validation Example (Standalone AM)

Certificate Validation Example (ForgeRock Identity Platform)

Certificate User Extractor Node

This node extracts a value from the certificate collected by the "Certificate Collector Node", and searches for it in the identity store. The goal is to match the certificate with a user in the identity store.

The tree continues through the Extracted path if AM was able to match the certificate to a user in the identity store, and through the Not Extracted path otherwise.

The extracted value is stored in the username key in the shared state of the authentication tree.

Properties:

Cookie Presence Decision Node

The Cookie Presence Decision authentication node checks if a named cookie is present in the incoming authentication request.

Note that the node does not check the value of the named cookie, only that it exists.

Properties:

Device Profile Collector

The Device Profile Collector authentication node gathers metadata about the device the user is authenticating with.

The node sends a DeviceProfileCallback callback. For more information, see "Interactive Callbacks".

When used with the ForgeRock SDKs, the node can collect the following:

Alongside the collected metadata, an identifier string in the JSON uniquely identifies the device.

Use this node alongside the "Device Profile Save" authentication node when you want to create a trusted profile from the collected data. The trusted device profile can be used in subsequent authentication attempts; for example, with the "Device Match" and "Device Profile Location Match" authentication nodes.

Properties:

Device Match

The Device Match authentication node compares any collected device metadata with that stored in the user's profile.

Use this node alongside the "Device Profile Collector" authentication node to determine if the authenticating user is on a previously saved, trusted device.

You can choose between two methods of comparison:

You must establish the identity of the user in the tree before attempting to match device profiles.

Tree evaluation continues along the True path if the collected device profile matches a saved profile, within the configured variance; otherwise, tree evaluation continues along the False path.

If the user has no trusted device profiles, or the identity of the user has not been established, tree evaluation continues along the Unknown Device path.

Properties:

Device Profile Save

The Device Profile Save authentication node persists collected device data to a user's profile in the identity store.

Use this node alongside the "Device Profile Collector" authentication node when you want to reuse the collected data in future authentications; for example, with the "Device Match" and "Device Profile Location Match" authentication nodes.

You must establish the identity of the user in the tree before attempting to save to their profile.

A user profile can contain multiple device profiles. Use the Maximum Saved Profiles property to configure the maximum number of device profiles to persist per user. Saving a device profile with the same identifier as an existing entry overwrites the original record, and does not increment the device profile count.

The user UI component of the platform UI displays saved device profiles to end users. Note that the Access Management UI does not display saved device profiles to end users.

You can manage device profiles with REST, by using the /json/users/user/devices/profile endpoint.

Use the AM API Explorer for detailed information about the parameters supported by the /devices/profile endpoint, and to test it against your deployed AM instance.

In the AM console, select the Help icon, and then go to API Explorer > /users > /{user} > /devices > /profile.

Properties:

Device Profile Location Match

The Device Profile Location Match authentication node compares any collected device location metadata with that stored in the user's profile.

Use this node alongside the "Device Profile Collector" authentication node to determine if the authenticating user's device is located within range of somewhere they have authenticated from, and saved, previously.

You must establish the identity of the user in the tree before attempting to match locations.

Tree evaluation continues along the True path if the collected location is within the specified range of saved location data; otherwise, tree evaluation continues along the False path.

If the user has no saved device profiles, or the identity of the user has not been established, tree evaluation continues along the Unknown Device path.

Properties:

Device Geofencing

The Device Geofencing authentication node compares any collected device location metadata with the trusted locations configured in the authentication node.

Use this node alongside the "Device Profile Collector" authentication node to determine if the authenticating user's device is located within range of configured, trusted locations.

Tree evaluation continues along the Inside path if the collected location is within the specified range of a configured trusted location; otherwise, tree evaluation continues along the Outside path.

Properties:

Device Tampering Verification

The Device Tampering Verification authentication node specifies a threshold for deciding if the device has been tampered with; for example, if it has been rooted or jailbroken.

A score between zero and one is returned by the device, based on the likelihood that is has been tampered with or may pose a security risk. For example, an emulator scores the maximum of 1.

Use this node alongside the "Device Profile Collector" authentication node to retrieve the tampering score from the device.

Tree evaluation continues along the Not Tampered path if the device scores less than or equal to the configured threshold, otherwise tree evaluation continues along the Tampered path.

Properties:

Persistent Cookie Decision Node

The Persistent Cookie Decision authentication node checks for the existence of the persistent cookie specified in the Persistent cookie name property, the default being session-jwt.

If the cookie is present, the node verifies the signature of the JWT stored in the cookie by using the signing key specified in the HMAC signing key property.

If the signature is valid, the node will decrypt the payload of the JWT by using the key pair specified in the Persistent Cookie Encryption Certificate Alias property. This property can be found at the global level by navigating to Configure > Authentication > Core Attributes > Security, or at the realm level by navigating to Realms > Realm Name > Authentication > Settings > Security.

Within the decrypted JSON payload is information such as the UID of the identity, and the client IP address. Enable the Enforce client IP property to verify that the current IP address and the client IP address in the cookie are identical.

Tree evaluation continues along the True outcome path if the persistent cookie is present and all the verification checks above are satisfied. Otherwise, tree evaluation continues along the False outcome path.

Properties:

$ openssl rand -base64 32

$ cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1|base64

Example:

PersistentCookie Tree (Standalone AM)

PersistentCookie Tree (ForgeRock Identity Platform)

Set Persistent Cookie Node

The Set Persistent Cookie authentication node creates a persistent cookie named after the value specified in the Persistent cookie name property, the default being session-jwt.

The cookie contains a JWT, inside which there is a JSON payload with information such as the UID of the identity, and the client IP address.

The node encrypts the JWT using the key pair specified in the Persistent Cookie Encryption Certificate Alias property. This property can be found by navigating to Configure > Authentication > Core Attributes > Security.

The node signs the cookie with the signing key specified in the HMAC signing key property. Any node that will read the persistent cookie must be configured with the same HMAC signing key.

Properties:

$ openssl rand -base64 32

$ cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1|base64

OAuth 2.0 Node

The OAuth 2.0 authentication node lets AM authenticate users of OAuth 2.0-compliant resource servers. References in this section are to RFC 6749, The OAuth 2.0 Authorization Framework.

Tree evaluation continues along the Account Exists path if an account matching the attributes retrieved from the social identity provider is found in the user data store. Otherwise, the tree evaluation continues along the No account exists path.

Properties:

{
  "sub" : "12345",
  "name" : {
    "first_name" : "Demo",
    "last_name" : "User"
  }
}

{
  "sub" : "12345",
  "name" : {
    "first_name" : "Demo",
    "last_name" : "User"
  }
}

OpenID Connect Node

The OpenID Connect authentication node lets AM authenticate users of OpenID Connect-compliant resource servers. As OpenID Connect is an additional layer on top of OAuth 2.0, many references in this section are to RFC 6749, The OAuth 2.0 Authorization Framework. OpenID Connect-specific references are to the OpenID Connect Core 1.0 incorporating errata set 1 specification.

Tree evaluation continues along the Account Exists path if an account matching the attributes retrieved from the OpenID Connect identity provider is found in the identity store. Otherwise, the tree evaluation continues along the No account exists path.

The OpenID Connect node implements the "Authorization Code Grant" flow.

Properties:

Provision Dynamic Account Node

The Provision Dynamic Account node provisions an account following successful authentication by a SAML2 authentication node, or the "Social Provider Handler Node".

Accounts are provisioned using properties defined in the attribute mapper configuration of a social authentication or SAML2 authentication node earlier in the tree evaluation.

If a password has been acquired from the user, for example, by using the "Platform Password Node", it is used when provisioning the account; otherwise, a 20 character random string is used.

In addition to retrieving the password from the node state, the Provision Dynamic Account node gets the realm value, and attributes and userNames from userInfo in the shared state. It sets the username attribute in the node's shared state.

Properties:

Example:

The following example uses the Provision Dynamic Account authentication node to allow users who have performed social authentication using Google to provide a password and provision an account, if they do not have a matching existing profile. They must enter a one-time password to verify they are the owner of the Google account.

Google-DynamicAccountCreation Tree With Provision Dynamic Account Node

Provision IDM Account Node

The Provision IDM Account node redirects users to an IDM instance to provision an account.

Ensure you have configured the details of the IDM instance in AM, by navigating to Configure > Global Services > IDM Provisioning.

Properties:

Example:

The following example uses the Provision IDM Account authentication node to allow users who have performed social authentication using Facebook to provision an account using IDM, if they do not have a matching existing profile.

Facebook-ProvisionIDMAccount Tree With Provision IDM Account Node

SAML2 Authentication Node

This node lets you integrate SAML v2.0 SSO into an AM authentication tree. Use it when deploying SAML v2.0 single sign-on in integrated mode (SP-initiated SSO only).

If a user account is found that matches the federated account, tree evaluation continues along the "Account Exists" outcome. Otherwise, a matching account could not be found, and tree evaluation continues along the "No Account Exists" outcome.

If the node continues along the "Account Exists" or along the "No Account Exists" outcomes (in other words, if the node reaches the end of its processing without a failure), it sets the successURL parameter in the tree's shared state to the value of the RelayState parameter in the request, if any.

If the request does not provide a value, the node uses the default RelayState value configured in the SP.

You can dynamically provision an account on the SP if it does not exist, or you can link the remote account to a local account using the "Write Federation Information Node".

Before attempting to configure a SAML2 authentication node, ensure that:

Properties:

Property	Usage
IdP Entity ID	Specifies the name of the remote IdP.
SP MetaAlias	Specifies the local alias for the SP, in the format /Realm Name/SP Name.
Allow IdP to Create NameID	Specifies whether the IdP should create a new identifier for the authenticating user if none exists. For detailed information, see the section on the AllowCreate property in SAML Version 2.0 Errata 05. Default: Enabled
Comparison Type	Specifies a comparison method to evaluate authentication context classes or statements. The value specified in this property overrides the value set in the SP configuration under Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context > Comparison Type. Valid comparison methods are exact, minimum, maximum, or better. For more information about the comparison methods, see the section on the <RequestedAuthnContext> element in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0. Default: minimum
Authentication Context Class Reference	(Optional) Specifies one or more URIs for authentication context classes to be included in the SAML request. What Are Authentication Context Classes? They are unique identifiers for an authentication mechanism. The SAML v2.0 protocol supports a standard set of authentication context classes, defined in Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0. In addition to the standard authentication context classes, you can specify customized authentication context classes. Any authentication context class that you specify in this field must be supported for the service provider. Where Can I Find This Information? In the AM console, go to Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context. When specifying multiple authentication context classes, use the | character to separate the classes. For example: urn:oasis:names:tc:SAML:2.0:ac:classes:Password|urn:oasis:names:tc:SAML:2.0:ac:classes:TimesyncToken
Authentication Context Declaration Reference	(Optional) Specifies one or more URIs that identify authentication context declarations. When specifying multiple URIs, use the | character to separate the URIs. For more information, see the section on the <RequestedAuthnContext> element in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.
Request Binding	Specifies the format the SP will use to send the authentication request to the IdP. Valid values are HTTP-Redirect and HTTP-POST. Default: HTTP-Redirect
Response Binding	Specifies the format the IdP will use to send the response to the SP. Valid values are HTTP-POST and HTTP-Artifact. Default: HTTP-Artifact
Force IdP Authentication	Specifies whether the IdP forces authentication or if it can reuse existing security contexts. Default: Disabled
Passive Authentication	Specifies whether the IdP uses passive authentication or not. Passive authentication requires the IDP to only use authentication methods that do not require user interaction. For example, authenticating using an X.509 certificate. Default: Disabled
NameID Format	Specifies the SAML name ID format that will be requested in the SAML authentication request. For example: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent urn:oasis:names:tc:SAML:2.0:nameid-format:transient urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified Default: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

For examples, see "SSO and SLO in Integrated Mode".

Social Facebook Node

The Social Facebook authentication node is a duplicate of the OAuth 2.0 Node node, preconfigured to work with Facebook. Only the Client ID and Client Secret are required to be populated.

Tree evaluation continues along the Account Exists path if an account matching the attributes retrieved from Facebook are found in the user data store. Otherwise, the tree evaluation continues along the No account exists path.

Properties:

{
  "sub" : "12345",
  "name" : {
    "first_name" : "Demo",
    "last_name" : "User"
  }
}

{
  "sub" : "12345",
  "name" : {
    "first_name" : "Demo",
    "last_name" : "User"
  }
}

Example:

The following example uses the Provision IDM Account authentication node to allow users who have performed social authentication using Facebook to provision an account using IDM, if they do not have a matching existing profile.

Facebook-ProvisionIDMAccount Tree With Provision IDM Account Node

Social Google Node

The Social Google authentication node is a duplicate of the OAuth 2.0 Node node, preconfigured to work with Google. Only the Client ID and Client Secret are required to be populated.

Tree evaluation continues along the Account Exists path if an account matching the attributes retrieved from Google are found in the user data store. Otherwise, the tree evaluation continues along the No account exists path.

Properties:

{
  "sub" : "12345",
  "name" : {
    "first_name" : "Demo",
    "last_name" : "User"
  }
}

{
  "sub" : "12345",
  "name" : {
    "first_name" : "Demo",
    "last_name" : "User"
  }
}

Example:

The following example uses the Anonymous User Mapping authentication node to allow users who have performed social authentication using Google to access AM as an anonymous user if they do not have a matching existing profile.

Google-AnonymousUser Tree With Anonymous User Mapping Node

Social Ignore Profile Node

The Social Ignore Profile authentication node specifies if a local user profile should be ignored. If tree evaluation passes through this node, after successful social authentication, AM issues an SSO token regardless of whether a user profile exists in the data store. The presence of a user profile is not checked.

Properties:

This node has no configurable properties.

Social Provider Handler Node

This node is used alongside the "Select Identity Provider Node" to enable use of the Social Identity Provider Service.

It takes the provider selection from the "Select Identity Provider Node" and attempts to authenticate the user with that provider. It then collects relevant profile information from the provider and returns the user to the flow, and transforms that profile information into attributes AM can use.

Properties:

Write Federation Information Node

This node creates a persistent link between a remote IdP account and a local account in the SP, if none exists yet. If a transient link exists, it is persisted. Existing account links with different IdPs are not lost.

Use this node alongside the "SAML2 Authentication Node", and ensure that the NameID Format is persistent.

Properties:

This node has no configurable properties.

For examples, see "Linking Identities by Using Authentication Trees or Chains".

Accept Terms and Conditions Node

This node prompts the user to accept the currently active Terms and Conditions.

You set up Terms and Conditions in the Platform UI. For more information, see see Configure Terms and Conditions in the Platform Self-Service Guide.

This node is used in a registration tree, or combined with the "Terms and Conditions Decision Node" in a progressive profile or login tree.

Note that there is no failure path for this node: the user must accept the Terms and Conditions in order to proceed:

Properties:

This node has no configurable properties.

Example:

In a progressive profile tree, the Accept Terms and Conditions node is used after the "Terms and Conditions Decision Node". If the user has not accepted the latest version of the Terms and Conditions, they are taken to a page notifying them that proceeding indicates accepting the current Terms and Conditions.

If the user clicks next, the acceptance response is stored in IDM.

Example Tree With Accept Terms and Conditions Node

Anonymous User Mapping Node

The Anonymous User Mapping node allows users to log in to your application or web site without providing credentials, by assuming the identity of a specified, existing user account. The default user for this purpose is named anonymous.

Typically, you would provide such users with very limited access, for example, anonymous users may have access to public downloads on your site.

Properties:

Example:

The following example uses the Anonymous User Mapping authentication node to allow users who have performed social authentication to access AM as an anonymous user if they do not have a matching existing profile.

Social Identity Provider With Anonymous User Mapping Node

Social Identity Provider With Anonymous User Mapping Node (ForgeRock Identity Platform)

Anonymous Session Upgrade Node

The Anonymous Session Upgrade node allows an anonymous session to be upgraded to a non-anonymous session by adding the Anonymous Session Upgrade node as the first node in any tree.

Properties:

This node has no configurable properties.

Example:

After using the "Anonymous User Mapping Node" to access AM as an anonymous user, the Anonymous Session Upgrade authentication node lets users upgrade their session to a non-anonymous one.

Example Tree With Anonymous Session Upgrade Node (Standalone AM)

Example Tree With Anonymous Session Upgrade Node (ForgeRock Identity Platform)

Attribute Collector Node

The Attribute Collector node is used to collect the values of attributes for use elsewhere in a tree, such as collecting user information to populate a new account in a registration tree.

To request a value, the attribute must be present in the IDM schema of the Identity Object configured in the tree. This node supports three types of attributes: string, boolean, and number.

The node configuration allows the admin to specify if the attributes are required to continue, and if they should be subject to validation through IDM's policy filter.

You can place the node anywhere in your authentication tree, or within a page node.

Properties:

Attribute Present Decision Node

Checks if an attribute is present on an object, regardless of whether the field is private. Use this to verify an attribute is present, without needing to know the value of the attribute itself.

A good use case is during an update password flow, where you want to check if the account has a password (rather than no password and logging in through a social identity) before continuing.

This node is similar to the "Attribute Value Decision Node" when that node is set to use the PRESENT operator, except it cannot return the value of the attribute, but can work with private attributes.

Properties:

Attribute Value Decision Node

Verifies that the user's specified attribute satisfies a specific condition.

Use this node to check whether an attribute's expected value is equal to a collected attribute value, or to validate that a specified attribute has been collected (regardless of the value of that attribute).

For example, to validate that a user filled out the country attribute when registering, set the comparison operation to PRESENT, and the comparison attribute to country.

If you instead need to ensure the country attribute is set to the United States, set the comparison operation to EQUALS, the comparison attribute to country, and the comparison value to United States.

Use "Attribute Present Decision Node" instead when you need to check for the presence of a private attribute (such as, password).

Properties:

Create Object Node

The Create Object node is used to create a new object in IDM based on information collected during an auth tree flow, such as user registration.

Any managed object attributes that are marked as required in IDM will need to be collected during the auth tree flow in order for the new object to be created.

Properties:

Create Password Node

The Create Password node allows users to create a password when provisioning an account.

The social identity provider will not provide a user's password. Use this node to provide a password to complete the user's credentials before provisioning an account.

The tree must provision an account after asking the user for a password, for example by using the Provision Dynamic Account authentication node. If an account is not provisioned the entered password will not be saved.

Properties:

Example:

The following example uses the Create Password authentication node to allow users who have performed social authentication using Google to provide a password and provision an account, if they do not have a matching existing profile. They must enter a one-time password to verify they are the owner of the Google account.

Google-DynamicAccountCreation Tree With Create Password Node

Consent Collector Node

The Consent Collector node prompts the user to consent to share their profile data.

A consent notice is listed for each IDM mapping that has consent enabled. If an IDM mapping is not created, or the mappings do not have privacy and consent enabled, no consent message will be shown to the user.

This node is primarily used in progressive profile or registration flows.

Properties:

Display Username Node

This node is used to fetch a username based on a different identifying attribute (such as an email address), then display it on screen. To email the username to the user instead, use the "Identify Existing User Node" combined with a "Email Suspend Node" or "Email Template Node" . The Display Username node requires IDM integration to function.

Properties:

Identify Existing User Node

This node verifies a user exists based on an identifying attribute, such as an email address, then makes the value of a specified attribute available in a tree's shared state.

For example, use this node in a "Forgot Username" flow to fetch a username to email to the user. If you want to display the username on screen, use the "Display Username Node" instead.

Properties:

Example:

The following is an example of a forgotten password tree. The user enters information that the "Identify Existing User Node" will use to try to identify them. Next, AM sends the user an email, possibly with a link to resume authentication. Once authentication is resumed, the user is sent to a different tree to reset their password:

Identify User Tree

KBA Decision Node

The KBA Decision node is used to check if the minimum number of KBA questions required by the system are defined for the user.

The number of KBA questions is determined by the minimumAnswersToDefine property in selfservice.kba.json in IDM. This node is mainly used for Progressive Profile completion.

Properties:

KBA Definition Node

The KBA Definition node collects KBA questions and answers from the user and saves them to the user object.

This is used when creating or updating a user with Knowledge-Based Authentication enabled. For more information, see Configure Security Questions in the Platform Self-Service Guide.

Properties:

KBA Verification Node

The KBA Verification node presents KBA questions to the user, collects answers to those questions, and verifies the input against the user's stored answers.

This is used during self-service actions such as Forgot Password or Forgot Username, where additional authentication is needed. The number of KBA questions is determined by the minimumAnswersToVerify property in selfservice.kba.json in IDM.

Properties:

Patch Object Node

The Patch Object node is used to update attributes in an existing managed object in IDM.

This is used in cases such as progressive profile completion, where you may wish to collect additional profile data from a user after they have logged in several times.

Properties:

Platform Password Node

This node prompts the user to enter their password and stores the input in a configurable state attribute.

Use this node instead of the Password Collector node when working with AM and IDM as an integrated platform.

Properties:

{
    "name": "failedPolicies",
    "value": [
        "{ \"params\": { \"minLength\": 8 },
           \"policyRequirement\": \"MIN_LENGTH\" }",
        "{ \"params\": { \"numCaps\": 1 },
           \"policyRequirement\": \"AT_LEAST_X_CAPITAL_LETTERS\" }",
        "{ \"params\": { \"numNums\": 1 },
           \"policyRequirement\": \"AT_LEAST_X_NUMBERS\" }"
    ]
},

Platform Username Node

This node prompts the user to enter their username, and stores it in a configurable state attribute.

Use this node instead of the Username Collector node when working with AM and IDM as an integrated platform.

Properties:

Profile Completeness Decision Node

The Profile Completeness Decision node is used in progressive profile flows. It checks how much of a user's profile has been filled out, where the completeness of a profile is expressed as a percentage of user-viewable, user-editable fields that are not null.

Properties:

Query Filter Decision Node

Checks if the contents of a user's profile matches a specified query filter.

Use this node to verify whether a particular field has been filled out, or that the contents of a field match a specific pattern. For instance, use this in progressive profile flows to check if marketing preferences are set on a user's profile.

For more information on constructing effective query filters, see Construct Queries in the IDM Object Modeling Guide.

Properties:

Required Attributes Present Node

The Required Attributes Present node checks the specified identity resource in IDM (by default, managed/user), and determines if all attributes required to create the specified object exist within shared state of the tree.

Properties:

Select Identity Provider Node

This node is used in combination with the "Social Provider Handler Node" to enable use of the Social Identity Provider Service. It presents the user with a list of configured, enabled, social identity providers to use for authentication.

The node has two possible outputs: social authentication, and local authentication. Local authentication can be turned off by disabling Include local authentication.

This node returns the SelectIdPCallback when more than one social identity provider is enabled, or a single provider is enabled as well as the Local Authentication option, and therefore a choice from the user is required. If no choice from the user is required, authentication proceeds to the next node in the tree.

Properties:

Terms and Conditions Decision Node

The Terms and Conditions Decision node verifies the user has accepted the active set of Terms and Conditions.

You set up Terms and Conditions in the Platform UI. For more information, see see Configure Terms and Conditions in the Platform Self-Service Guide.

Use this node when you want to verify the user has accepted your Terms and Conditions before proceeding (such as logging in, or in a progressive profile tree). This is often used with the "Accept Terms and Conditions Node".

Properties:

Time Since Decision Node

Checks if a specified amount of time has passed since the user was registered.

For example, if you wanted to prompt users to review your terms and conditions after the account is a week old, you could set the Elapsed Time property to 10080 minutes. After that time has elapsed, the next time the user logs in, they will be prompted to review your terms and conditions.

This node is mainly used for Progressive Profile completion.

Properties:

Agent Data Store Decision Node

The Agent Data Store Decision authentication node verifies that a provided agent ID and password match a web agent or Java agent profile configured in AM.

The web or Java agent ID, and the password should be obtained by using the Zero Page Login Collector Node.

Tree evaluation continues along the True path if the credentials match those of a configured agent profile. Otherwise, the tree evaluation continues along the False path.

Properties:

This node has no configurable properties.

Choice Collector Node

The Choice Collector authentication node lets you define two or more options to present to the user when authenticating.

Email Suspend Node

The Email Suspend node is used to generate and send an email to a user, such as an address verification email, based on an email template in IDM. The authentication tree will pause until the user clicks a link in the email to resume the tree flow.

The link is generated by the Email Suspend node, and is passed along to IDM as part of the email object, in a property called resumeURI.

This node uses the email service configured in IDM to send email. If you do not need the auth tree to pause and wait for a response from email, use the "Email Template Node" instead.

Properties:

Example:

The following is an example of a forgotten password tree. The user enters information that the Identify Existing User Node will use to try to identify them. Next, AM uses the "Email Suspend Node" to send an email to the user and suspend the authentication tree. Once authentication is resumed, the user is sent to a different tree to reset their password:

Email Suspend Tree

Email Template Node

The Email Template node is used to generate and send an email to a user, such as a welcome email, based on an email template in IDM.

This node uses the email service configured in IDM to send email. If you need the auth tree to pause and wait for a response from email, use the "Email Suspend Node" instead.

This node has two possible outcomes: "Email Sent" and "Email Not Sent", which can be used if you need different behavior depending on the outcome. According to OWASP authentication recommendations, the message to the user should be the same in both cases.

Properties:

Failure URL Node

The Failure URL authentication node sets the URL to be redirected to when authentication fails.

For more information on how AM determines the redirection URL, and to configure the Validation Service to trust redirection URLs, see "Configuring Success and Failure Redirection URLs".

Properties:

Get Session Data Node

The Get Session Data authentication node retrieves the value of a specified key from a user's session data, and stores it in the specified key in the tree's nodeState object.

The Get Session Data authentication node is only used during session upgrade—when the user has already successfully authenticated previously—and is now upgrading their session for additional access. For more information on upgrading a session, see Session Upgrade.

The node will fail with an error if you attempt to get a property when the user does not have an existing session. Use a "Scripted Decision Node" to determine if an existing session is present.

if (typeof existingSession !== 'undefined')
{
  outcome = "hasSession";
}
else
{
  outcome = "noSession";
}

Properties:

Example:

Get Session Data Tree Example (Standalone AM)

Get Session Data Tree Example (ForgeRock Identity Platform)

The following table includes example keys that may be available in an existing session, and corresponding sample values:

Inner Tree Evaluator Node

The Inner Tree Evaluator authentication node allows the nesting and evaluation of authentication trees as children within a parent tree. There is no limit to the depth of nested trees.

Any information collected or set by the parent tree, such as a username or the authentication level, is available to child trees.

Shared node state data collected by child trees is available to the parent when evaluation of the child is complete, but data stored in transient and secure state is not. For instance, if a child tree collects and stores the user's password in transient state, it cannot be retrieved by a node in the parent tree when evaluation continues.

For information about shared state data, refer to "Accessing Shared State Data".

Tree evaluation continues along the True path if the child tree reached the Success exit point. Otherwise, the tree evaluation continues along the False path.

Properties:

Message Node

The Message authentication node allows you to present a custom, localized message to the user.

In addition to the message, you can provide a localized positive, and negative response that the user must select to proceed.

Properties:

Example:

Meter Node

The Meter authentication node increments a specified metric key each time tree evaluation passes through the node. For information on the Meter metric type, see "Monitoring Metric Types". The metric is exposed in all available interfaces, as described in Monitoring Instances.

Properties:

Page Node

The Page authentication node combines multiple nodes that request input into a single page for display to the user. Drag and drop nodes on to the page node to combine them.

The outcome paths are determined by the last node in the page node. Only the last node in the page can have more than one outcome path.

Only nodes that use callbacks to request input can be added to a Page Node. Other nodes, such as the Data Store Decision Node and Push Sender Node must not be added to a page node.

Properties:

Example:

The following example uses a page node containing a username collector, a password collector, and a choice collector:

Example Tree With Page Node (Standalone AM

Example Tree With Page Node (ForgeRock Identity Platform)

The user is presented with all of the requests for input on a single page:

User View of Example Tree with Page Node (Standalone AM)

User View of Example Tree with Page Node (ForgeRock Identity Platform)

Polling Wait Node

The Polling Wait authentication node pauses progress of the authentication tree for a specified number of seconds, for example in order to wait for a response to a one-time password email or push notification.

Requests to the tree made during the wait period are sent a PollingWaitCallback callback and an authentication ID. For example, the following callback indicates a wait time of 10 seconds:

{
    "authId": "eyJ0eXAiOiJK...u4WvZmiI",
    "callbacks": [
        {
            "type": "PollingWaitCallback",
            "output": [
                {
                    "name": "waitTime",
                    "value": "10000"
                },
                {
                    "name": "message",
                    "value": "Waiting for response..."
                }
            ]
        }
    ]
}

The client must wait 10 seconds before returning the callback data, including the authId. For example:

$ curl \
--cookie "iPlanetDirectoryPro=AQIC5w...NTcy*" \" \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--data '{
    "authId":"eyJ0eXAiOi...WLxJ-1d6ovYKHQ",
    "template":"",
    "stage":"AuthenticatorPush3",
    "header":"Authenticator Push",
    "callbacks":[
        {
            "type":"PollingWaitCallback",
            "output":[
                {
                    "name":"waitTime",
                    "value":"10000"
                }
            ]
        },
        {
            "type":"ConfirmationCallback",
            "output":[
                {
                    "name":"prompt",
                    "value":""
                },
                {
                    "name":"messageType",
                    "value":0
                },
                {
                    "name":"options",
                    "value":[
                        "Use Emergency Code"
                    ]
                },
                {
                    "name":"optionType",
                    "value":-1
                },
                {
                    "name":"defaultOption",
                    "value":0
                }
            ],
            "input":[
                {
                    "name":"IDToken2",
                    "value":100
                }
            ]
        }
    ]
}' \
"https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate\
?authIndexType=composite_advice\
&authIndexValue=%3CAdvices%3E%0A\
%3CAttributeValuePair%3E%0A%3CAttribute%20name%3D\
%22TransactionConditionAdvice%22%2F%3E%0A\
%3CValue%3E9dae2c80-fe7a-4a36-b57b-4fb1271b0687\
%3C%2FValue%3E%0A%3C%2FAttributeValuePair\
%3E%0A%3C%2FAdvices%3E"

For more information on authenticating using the REST API, see Authenticating (REST).

When using the UI for authentication, it automatically waits for the required amount of time and resubmits the page in order to continue tree evaluation. The message displayed whilst waiting is configurable by using the Waiting Message property.

Tree evaluation continues along the Done outcome path when the next request is received after the wait time has passed.

Enabling Spam detection adds a Spam outcome path to the node. Tree evaluation continues along the Spam outcome path if more than the specified number of requests are received during the wait time.

Enabling the user to exit without waiting adds an Exited outcome path to the node. Tree evaluation continues along the Exited outcome path if the user clicks the button that appears when the option is enabled. The message displayed on the exit button is configurable by using the Exit Message property.

Properties:

Register Logout Webhook Node

The Register Logout Webhook authentication node registers the specified webhook to trigger when a user's session ends. The webhook triggers when a user explicitly logs out, or the maximum idle time or expiry time of the session is reached.

The webhook is only registered if tree evaluation passes through the Register Logout Webhook node. You can register multiple webhooks during the authentication process, but they must be unique.

For more information on webhooks, see "Configuring Authentication Webhooks".

Properties:

Remove Session Properties Node

The Remove Session Properties authentication node enables the removal of properties from the session. The session properties may have been set by a Set Session Properties node elsewhere in the tree.

If a specified key is not found in the list of session properties that will be added to the session upon successful authentication, no error is thrown and tree evaluation continues along the single outcome path.

If a specified key is found, the tree evaluation continues along the single outcome path after setting the value of the property to null.

Properties:

Retry Limit Decision Node

The Retry Limit Decision authentication node allows the specified number of passes through to the Retry outcome path, before continuing tree evaluation along the Reject outcome path.

Properties:

Example:

RetryLimit Tree (Standalone AM)

RetryLimit Tree (ForgeRock Identity Platform)

Scripted Decision Node

The Scripted Decision authentication node allows execution of scripts during authentication. Tree evaluation continues along the path matching the result.

The script defines the possible outcome paths by setting one or more values of a string variable named outcome. For more information on creating scripts, see Managing Scripts (UI).

Tree evaluation continues along the outcome path that matches the value of the outcome variable when script execution completes.

All of the inputs required by the script and the outputs produced by it must be declared in the node's configuration or the script may fail. Even if the definition is null, it still needs to be declared. Use the wildcard * to include any available inputs or outputs.

For information about the API available for use in the Scripted Decision Node, see "Scripted Decision Node API Functionality".

Properties:

Set Session Properties Node

The Set Session Properties authentication node allows the addition of key:value properties to the user's session if authentication is successful.

Tree evaluation continues along the single outcome path after setting the specified properties in the session.

Properties:

State Metadata Node

The State Metadata authentication node returns selected attributes from the shared state as metadata.

The node sends a MetaDataCallback to retrieve shared state values which are added to the JSON response from the /authenticate endpoint. This example shows how a shared state attribute, mail, is returned in the JSON output:

  
"callbacks": [
    {
        "type": "MetadataCallback",
        "output": [
            {
                 "name": "data",
                 "value":
                     {
                         "mail": "bjensen@example.com"
                     }
            }
        ]
    }
]
  
  

You can use the State Metadata node when you want to display custom information that includes user attributes, without having to alter the existing authentication journey.

For example, for OTP authentication with a choice of email or SMS, create a State Metadata node to return the user's email address or phone number. These attributes can be used in conjunction with an OTP Collector Decision Node and, optionally, a Scripted Decision Node, to customize the data for display later in the journey.

Tree evaluation continues along the single outcome path after the callback.

Properties:

Example:

State Metadata Tree (Standalone AM)

State Metadata Tree (ForgeRock Identity Platform)

Success URL Node

The Success URL authentication node sets the URL to be redirected to when authentication succeeds.

For more information on how AM determines the redirection URL, and to configure the Validation Service to trust redirection URLs, see "Configuring Success and Failure Redirection URLs".

Properties:

Timer Start Node

The Timer Start authentication node starts a named timer metric, which can be stopped elsewhere in the tree by using the Timer Stop Node.

Properties:

Timer Stop Node

The Timer Stop authentication node records the time elapsed since tree evaluation passed through the specified Timer Start Node in the specified metric name. For information on the Timer metric type, see "Monitoring Metric Types".

Note that the time stored in the specified Start Time Property property is not reset by the Timer Stop Node, so other Timer Stop Nodes in the tree can also calculate the time elapsed since tree evaluation passed through the same Timer Start Node.

The metric is exposed in all available interfaces, as described in Monitoring Instances.

Properties:

Authenticate Thing Node

This node authenticates a thing. A thing represents an IoT device, service, or the Thing Gateway. Before using this node, ensure that the IoT Service is configured for the realm.

It collects a proof-of-possession JWT from the request and checks the following:

If all checks are successful and AM can verify the JWT's signature with the confirmation key, the tree continues through the Success path, and adds the username and the verified claims to the authentication tree's shared state.

When using the resulting session, the thing's request must be signed, and AM must be able to validate the signature using the confirmation key in the thing's identity profile.

If the identity does not exist, or AM cannot match the identity with the confirmation key, the tree continues through the Requires Registration outcome. If any other check fails, the tree continues through the Failure outcome.

Properties:

This node has no configurable properties.

Examples:

The following example shows how to authenticate a thing when the identity already exists in the identity store and when its profile contains a confirmation key:

Authenticating a Thing Without Registration

The following example shows how to authenticate a thing when the identity does not exist, or when it needs to refresh its confirmation key:

Authenticating a Thing With Registration

Register Thing Node

This node registers a thing. A thing represents an IoT device, service, or the Thing Gateway. Before using this node, ensure that the IoT Service is configured for the realm.

The node collects a proof-of-possession JWT from the request, and verifies the contained X.509 certificate against the key mapped to the am.services.iot.cert.verification secret ID.

If the certificate is valid, the node verifies the JWT's signature with the public key provided in the certificate and uses the claims in the JWT to create an identity for the thing and register (or rotate) a confirmation key for it. Then, the tree continues through the Success outcome.

If the node cannot verify the certificate with the key mapped to the secret ID, or if it cannot verify the JWT's signature, the tree continues through the Failure outcome.

For an example on how to use this node, see the "Authenticate Thing Node".

Properties: