Identity Cloud

Authentication nodes configuration reference

This page covers the configuration of the authentication nodes built into AM.

Even though they appear in the UI, the following nodes are incompatible with ForgeRock Identity Cloud; therefore, their reference information is not included.

Kerberos node

Password Collector node(1)

Username Collector node(2)

Certificate Collector node

Certificate User Extractor node

Certificate Validation node

Authenticate Thing

Register Thing

(1) Use the Platform Password node instead.

(2) Use the Platform Username node instead.

Basic authentication nodes

Use the following nodes for basic authentication tasks, such as collecting usernames and passwords:

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.

Outcomes

  • True

  • False

Journey evaluation continues along the True path if the credentials are located in the configured data store; otherwise, the journey evaluation continues along the False path.

Properties

This node has no configurable properties.

Alternative nodes

  • The LDAP Decision node supports LDAP Behera Password Policies, with separate outcomes for accounts that are locked or their password has expired.

  • The Identity Store Decision node is an enhanced node with additional outcomes. Use this node if your authentication journey needs more functionality than a simple True or False outcome.

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.

Outcomes

  • True

  • False

  • Locked

  • Cancelled

  • Expired

Journey 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, journey 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, journey evaluation continues along the Cancelled outcome path.

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

Properties

Property Usage

Primary LDAP Server (required)

Specify one or more primary directory servers. Specify each directory server in the following format: host:port.

For example, directory_services.example.com:389.

Secondary LDAP Server

Specify one or more secondary directory servers. Specify each directory server in the following format: host:port.

Secondary servers are used when none of the primary servers are available.

For example, directory_services_backup.example.com:389.

DN to Start User Search (required)

Specify the DN from which to start the user search. More specific DNs, such as ou=sales,dc=example,dc=com, result in better search performance.

If multiple entries exist in the store with identical attribute values, ensure this property is specific enough to return only one entry.

Bind User DN, Bind User Password

Specifies the credentials used to bind to the LDAP user data store.

Attribute Used to Retrieve User Profile (required)

Specifies the attribute used to retrieve the profile of a user from the directory server.

The user search will have already happened, as specified by the Attributes Used to Search for a User to be Authenticated and User Search Filter properties.

Attributes Used to Search for a User to be Authenticated (required)

Specifies the attributes used to match an entry in the directory server to the credentials provided by the user.

The default value of uid forms the search filter uid=user. Specifying multiple values such as uid and cn causes the node to forms the complex search filter (|(uid=user)(cn=user)).

Multiple attribute values allow the user to authenticate with any one of the values. For example, if you have both uid and mail, then Barbara Jensen can authenticate with either bjensen or bjensen@example.com.

Note that if you have specified multiple attribute values, you must also add those attributes to the Alias Search Attribute Name property when using account lockout. Refer to User Profile for more information about this property.

User Search Filter

Specifies an additional filter to append to user searches.

For example, searching for mail and specifying a User Search Filter of (objectClass=inetOrgPerson), causes AM to use (&(mail=address)(objectClass=inetOrgPerson)) as the resulting search filter, where address is the mail address provided by the user.

Search Scope

Specifies the extent of searching for users in the directory server.

Scope OBJECT means search only the entry specified as the DN to Start User Search, whereas ONELEVEL means search only the entries that are directly children of that object. SUBTREE means search the entry specified and every entry under it.

Default: SUBTREE

LDAP Connection Mode

Specifies whether to use SSL or StartTLS to connect to the LDAP user data store. AM must be able to trust the certificates used.

Possible values: LDAP, LDAPS, and StartTLS

Default: LDAP

Return User DN to DataStore

When enabled, the node returns the DN rather than the User ID. From the DN value, AM uses the RDN to search for the user profile. For example, if a returned DN value is uid=demo,ou=people,dc=openam,dc=example,dc=org, AM uses uid=demo to search the data store.

Default: Enabled

User Creation Attributes

This list lets you map (external) attribute names from the LDAP directory server to (internal) attribute names used by AM.

Minimum Password Length

Specifies the minimum acceptable password length.

Default: 8

LDAP Behera Password Policy Support

When enabled, support interoperability with servers that implement the Internet-Draft, Password Policy for LDAP Directories.

Default: Enabled

Trust All Server Certificates

When enabled, blindly trust server certificates, including self-signed test certificates.

Default: Disabled

LDAP Connection Heartbeat Interval

Specifies how often AM should send a heartbeat request to the directory server to ensure that the connection does not remain idle.

Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. Set the units for the interval in the LDAP Connection Heartbeat Time Unit property.

Default: 10

LDAP Connection Heartbeat Time Unit

Specifies the time unit corresponding to LDAP Connection Heartbeat Interval.

Default: seconds

LDAP Operations Timeout

Defines the timeout in milliseconds that AM should wait for a response from the directory server.

Default: 0 (means no timeout)

Identity Store Decision node

The Identity Store Decision node attempts to locate the provided username and password in the identity store. If the credentials exist, the node checks whether the profile is locked out, whether the provided password has expired, or whether the user cancels a password reset.

Outcomes

  • True

  • False

  • Locked

  • Cancelled

  • Expired

Journey evaluation progresses as follows:

  • Follows the True outcome path if the credentials are found.

    • Follows the Locked outcome path if the profile associated with the provided credentials is locked.

    • Follows the Expired outcome path if the profile is found, but the password has expired.

    • Follows the Cancelled outcome path if the user needs to change their password on first login, but cancels the password change form.

  • Follows the False outcome path if the credentials are not found.

Properties

Property Usage

Name

The name of the node in the authentication journey.

Default: Identity Store Decision

Minimum Password Length

Specifies the minimum acceptable password length.

Default: 8

Username as Universal Identifier

If you enable this property, the username property is set to the value of the uuid. For example, "username": "c636b756-ba6b-481d-ab4a-ab8c064cb24b".

If this property is false, the value of the username property remains unchanged. For example, "username": "bjensen".

Default: false

  • In new Identity Cloud deployments (starting from 2022.6), this property is false ("username": "bjensen").

  • In a deployment upgrade, this property is true, (username takes the value of the uuid) for compatibility with previous Identity Cloud releases.

  • In a deployment upgrade where this node already includes the property, the value of Username as Universal Identifier remains unchanged.

The following image shows the Identity Store Decision node incorporated into an authentication journey.

The Identity Store Decision node in an authentication journey.

Alternative nodes

  • The Data Store Decision node is a simpler node with only two outcomes, True and False. Use this node if your authentication journey only needs these outcomes.

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.

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

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.

Outcomes

  • Has Credentials

  • No Credentials

Properties

Property Usage

Username Header name

Enter the name of the header that contains the username value.

Default: X-OpenAM-Username

Password Header name

Enter the name of the header that contains the password value.

Default: X-OpenAM-Password

Allow Without Referer

If enabled, the node accepts incoming requests that do not contain a Referer HTTP header. If a Referer HTTP header is present, the value is not checked.

If disabled, a Referer HTTP header must be present in the incoming request, and the value must appear in the Referer Whitelist property.

Default: Enabled

Referer Whitelist

Specify a list of URLs allowed in the Referer HTTP header of incoming requests. Incoming requests containing a Referer HTTP header value not specified in the allowlist causes journey evaluation to continue along the No Credentials outcome path.

You must disable the Allow Without Referer property for this property to take effect.

Example

Journey showing Zero Page Login node usage.
Figure 1. Example Journey With Zero Page Login node

Multi-factor authentication nodes

Use the following nodes to configure journeys with multi-factor authentication capabilities, such as web authentication and push authentication:

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.

You can use the following variables to customize the message:

  • {{appleLink}}

  • {{googleLink}}

  • {{appleLabel}}

  • {{googleLabel}}

You can also include HTML elements, for example:

Apple: <a target='_blank' href='{{appleLink}}'>{{appleLabel}}</a>

Outcomes

Single outcome path.

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

Properties

Property Usage

Get App Authenticator Message

Optional. Localized title for the node. The key is the language (such as en or fr), and the value is the message to display.

Default: Get the app from the {{appleLink}} or on {{googleLink}}.

Continue Label

Optional. Localized text to use on the Continue button. The key is the language (such as en or fr), and the value is the message to display.

Apple App Store URL

Specifies the URL to download your authenticator app from the Apple App Store. The default value points to the ForgeRock Authenticator app for iOS.

Google Play URL

Specifies the URL to download your authenticator app from the Google Play Store. The default value points to the ForgeRock Authenticator app for Android.

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

Outcomes

Single outcome path.

Properties

Property Usage

One-time password length

Specify the number of digits in the one-time password.

Default: 8

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

Example

The HmacOneTimePassword authentication journey, showing HOTP Generator node usage.
Figure 2. HmacOneTimePassword Journey With HOTP Generator Node

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 Platform Username node and also the type of MFA device; for example, by placing a Push Sender node earlier in the authentication journey.

Outcomes

  • Register

  • Get App (configurable)

  • Skip (configurable)

  • Opt-out (configurable)

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

Properties

Property Usage

Remove 'skip' option

If checked, users will no longer be able to skip the module, and must interact with it.

Display Get Authenticator App

If enabled, display the 'Get the App' button.

Message

Localized text to use as the title of the screen.

The key is the language (such as en or fr), and the value is the message to display.

Register Device

Localized text to use on the Register Device button.

The key is the language (such as en or fr), and the value is the message to display.

Get Authenticator App

Localized text to use on the Get Authenticator App button.

The key is the language (such as en or fr), and the value is the message to display.

Skip this Step

Localized text to use on the Skip this Step button.

The button, and the outcome, only appear if the Remove 'skip' option is not enabled.

The key is the language (such as en or fr), and the value is the message to display.

Opt-out

Localized text to use on the Opt-Out button. The button, and the outcome, only appear if the Remove 'skip' option is not enabled.

Note that the node itself does not affect the users' profile. Connect the Opt-out outcome to an Opt-out Multi-Factor Authentication node to actually persist the ability to skip MFA to the users' profile.

The key is the language (such as en or fr), and the value is the message to display.

Example

Refer to the Push authentication example journey for how to use the MFA Registration Options node in a journey handling push devices.

Default text of the MFA Registration Options node.
Figure 3. Default text of the MFA Registration Options node

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.

You can use the OATH nodes in conjunction with the ForgeRock Authenticator app to register your phone, receive notifications, or generate one-time passwords.

Refer to the OATH Token Verifier node example to understand how these nodes can be used in combination with other MFA nodes to create a complete OATH authentication journey.

Outcomes

  • Success

  • Failure

If registration is successful and the device details are stored, journey 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.

Properties

Property Usage

Issuer

Specify an identifier to appear on the user’s device, such as a company name, a website, or an AM realm. The value is displayed by the authenticator app.

Account Name

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

Background Color

The background color, in hex notation, to display behind the issuer’s logo within the authenticator app.

Logo Image URL

The location of an image to download and display as the issuer’s logo within the authenticator app.

Generate Recovery Codes

If enabled, recovery codes are generated and stored in the success outcome’s transient state.

Use the Recovery Code Display node to display the codes to the user for safekeeping.

One Time Password Length

The length of the generated OTP in digits. This value must be at least 6, and compatible with the hardware/software OTP generators you expect your end-users to use. For example, Google and ForgeRock authenticators support values of 6 and 8 respectively.

Minimum Secret Key Length

Number of hexadecimal characters allowed for the Secret Key.

OATH Algorithm

Specify the algorithm your device uses to generate the OTP:

HOTP

HOTP uses a counter value that is incremented every time a new OTP is generated.

TOTP

TOTP generates a new OTP every few seconds as specified by the TOTP Time Step Interval value.

The default value is TOTP. If this is changed to HOTP, you need to set the same value in the OATH Token Verifier node.

TOTP Time Step Interval

The length of time that an OTP is valid, in seconds. For example, if the time step interval is 30 seconds, a new OTP will be generated every 30 seconds, and it will be valid for 30 seconds only.

The default value is 30.

TOTP Hash Algorithm

The HMAC hash algorithm to be used to generate the OTP codes. AM supports SHA1, SHA256, and SHA512.

HOTP Checksum Digit

This adds a digit to the end of the OTP generated to be used as a checksum to verify the OTP was generated correctly. This is in addition to the actual password length. You should only set this if your device supports it.

HOTP Truncation Offset

This is an option used by the HOTP algorithm that not all devices support. This should be left as the default value of -1, unless you know your device uses an offset.

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.

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:

You can use the OATH nodes in conjunction with the ForgeRock Authenticator app to register your phone, receive notifications, or generate one-time passwords.

For a visual overview of how the OATH nodes can be used within an authentication journey layout, refer to the Example.

Outcomes

Journey evaluation continues along one of the following outcome paths:

  • Success: If there is a registered device and the token code is verified.

  • Failure: If the user is not authenticated, or the collected token code cannot be verified.

  • Not registered: If there is no registered device for the user.

Properties

Property Usage

OATH Algorithm

Specify the algorithm your device uses to generate the OTP:

HOTP

HOTP uses a counter value that is incremented every time a new OTP is generated.

TOTP

TOTP generates a new OTP every few seconds as specified by the TOTP Time Step Interval value.

The default value is TOTP. If this is changed to HOTP, you need to set the same value in the OATH Registration node.

HOTP Window Size

This property sets the window that the OTP device and the server counter can be out of sync. For example, if the window size is 100 and the server’s last successful login was at counter value 2, the server will accept an OTP that is generated between counter 3 and 102.

The default value is 100.

TOTP Time Step Interval

The length of time that an OTP is valid, in seconds. For example, if the time step interval is 30 seconds, a new OTP will be generated every 30 seconds, and it will be valid for 30 seconds only.

The default value is 30.

TOTP Time Steps

This is the number of time step intervals that the OTP is permitted to be out of sync. This applies to codes that are generated before or after the current code. For example, with a time step of 1, the server will permit either the previous, the current, or the next code.

The default value is 2.

TOTP Hash Algorithm

The HMAC hash algorithm to be used to generate the OTP codes. ForgeRock Authenticator (OATH) supports SHA1, SHA256, and SHA512.

TOTP Maximum Allowed Clock Drift

Number of time steps a client is allowed to be out of sync with the server before a manual resynchronization is required.

For example, with 3 allowed drifts and a time step interval of 30 seconds, the server will allow codes from up to 90 seconds from the current time to be treated as the current time step. The drift for a user’s device is calculated each time they enter a new code. If the drift exceeds this value, the user’s authentication code will be rejected.

The default value is 5.

Allow recovery codes

Specify whether to allow users to use one of the recovery codes to proceed with the login.

Example

Example ForgeRock Authenticator (OATH) authentication journey.

OTP Collector Decision node

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

Outcomes

  • True

  • False

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

Properties

Property Usage

One Time Password Validity Length

Specify the length of time, in minutes, that a one-time password remains valid.

Default: 5

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.

Outcomes

Single outcome path.

Properties

Property Usage

Mail Server Host Name (required)

Specifies the hostname of the SMTP email server.

Mail Server Host Port

Specifies the outgoing mail server port. Common ports are 25, 465 (when connecting over SSL), or 587 (for StartTLS).

Mail Server Authentication Username

Specifies the username AM uses to connect to the mail server.

Mail Server Authentication Password

Specifies the password AM uses to connect to the mail server.

Email From Address (required)

Specifies the email address from which the one-time password will appear to have been sent.

Email Attribute Name

Specifies the user’s profile attribute containing the email address to which to email the OTP.

Default: mail

The subject of the email

Click Add to add a new email subject. Enter the locale (for example, en-uk) in the KEY field and the subject in the VALUE field. Repeat these steps for each locale that you support.

The content of the email

Click Add to add the content of the email. Enter the locale (for example, en-uk) in the KEY field and the email content in the VALUE field. Repeat these steps for each locale that you support.

Mail Server Secure Connection

Specifies how to connect to the mail server. If a secure method is specified, AM must trust the server certificate of the mail server.

The possible values for this property are:

  • NON SSL/TLS

  • SSL/TLS

  • Start TLS

Default: SSL/TLS

Gateway Implementation Class

Specifies the class the node uses to send SMS and email messages. A custom class must implement the com.sun.identity.authentication.modules.hotp.SMSGateway interface.

Default: com.sun.identity.authentication.modules.hotp.DefaultSMSGatewayImpl

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:

  • The user’s telephone number, obtained by querying a specified profile attribute, for example telephoneNumber.

  • The @ character.

  • The email-to-SMS gateway domain, obtained by querying the profile attribute specified by the Mobile Carrier Attribute Name property.

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.

Outcomes

Single outcome path.

Properties

Property Usage

Mail Server Host Name (required)

Specifies the hostname of the SMTP email server.

Mail Server Host Port

Specifies the outgoing mail server port. Common ports are 25, 465 (when connecting over SSL), or 587 (for StartTLS).

Mail Server Authentication Username

Specifies the username AM uses to connect to the mail server.

Mail Server Authentication Password

Specifies the password AM uses to connect to the mail server.

Email From Address (required)

Specifies the email address from which the one-time password will appear to have been sent.

Mobile Phone Number Attribute Name

Specifies the user’s profile attribute containing the mobile phone number to which to send the SMS containing the OTP.

Default: telephoneNumber

Mobile Carrier Attribute Name

Specifies the user’s profile attribute containing the mobile carrier domain used as the email to SMS gateway.

The subject of the message

Click Add to add a new message subject. Enter the locale (for example, en-uk) in the KEY field and the subject in the VALUE field. Repeat these steps for each locale that you support.

The content of the message

Click Add to add the content of the message. Enter the locale (for example, en-uk) in the KEY field and the email content in the VALUE field. Repeat these steps for each locale that you support.

Mail Server Secure Connection

Specifies how to connect to the mail server. If a secure method is specified, AM must trust the server certificate of the mail server.

The possible values for this property are:

  • NON SSL/TLS

  • SSL/TLS

  • Start TLS

Default: SSL/TLS

Gateway Implementation Class

Specifies the class the node uses to send SMS and email messages. A custom class must implement the com.sun.identity.authentication.modules.hotp.SMSGateway interface.

Default: com.sun.identity.authentication.modules.hotp.DefaultSMSGatewayImpl

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 Platform Username 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.

Outcomes

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

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, refer to MFA: Push authentication.

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

You must also configure the Push Notification Service.

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

For detailed information about the available properties, refer to Push Notification service.

Outcomes

  • Success

  • Failure

  • Time Out

If the user successfully registers their authenticator, then journey 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, journey evaluation continues along the Failure outcome path.

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:

The icons next to a registered account represent the authentication factors supported. The bell icon represents push notification support.

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

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

Refer to the Push authentication example journey for how to use the Push Registration node in a journey handling push devices.

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.

If the push message contained any additional information, for example if it was a registration request, the values are stored in the nodeState object of the journey for the pushContent key.

Outcomes

  • Success

  • Failure

  • Expired

  • Waiting

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

Journey 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 journey evaluation continues along the Expired outcome path.

If a response to the push message has not yet been received, then journey 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, refer to Push Notification Service.

For information on provisioning the credentials used by the service, refer to How To Configure Service Credentials (Push Auth, Docker) in Backstage in the ForgeRock Knowledge Base.

To determine whether the user has a registered device, the journey must have already acquired a username, for example by using a Platform Username node.

Authentication journeys are not capable of registering a device to a profile.

Outcomes

  • Sent

  • Not Registered

  • Skipped

Journey 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, journey evaluation continues along the Not Registered outcome path.

If the user chooses to skip push authentication, journey evaluation continues along the Skipped outcome path.

Properties

Property Usage

Message Timeout

Specifies the number of milliseconds the push notification message will remain valid. The Push Result Verifier node rejects responses to push messages that have timed out.

User Message

Specifies the optional message to send to the user.

You can provide the message in multiple languages by specifying the locale in the KEY field, for example en-US. For information on valid locale strings, see JDK 11 Supported Locales. The locale selected for display is based on the user’s locale settings in their browser.

Messages provided in the node override the defaults provided by AM.

The following variables can be used in the VALUE field:

{{user}}

Replaced with the username value of the account registered in the ForgeRock Authenticator app, for example Demo.

{{issuer}}

Replaced with the issuer value of the account registered in the ForgeRock Authenticator app, for example ForgeRock.

Example: Login attempt from {{user}} at {{issuer}}.

Remove 'skip' option

Enable this option in the node to make the push authentication mandatory. When set to Disabled the user can skip the push authentication requested by the node, and journey evaluation continues along the Skipped outcome path.

Default: Disabled

Nodes in authentication journeys are not affected by the Two Factor Authentication Mandatory property, available at Realms > Realm Name > Authentication > Settings > General.

Share Context info

If enabled, context data such as remoteIp, userAgent, and location will be included in the notification payload.

For example:

{
  "location": {
    "latitude": 49.2208569,
    "longitude": -123.1174431
  },
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36",
  "remoteIp": "9.9.9.9"
}

For the location attribute to be set, the journey must contain a Device Profile Collector node with the Collect Device Location option enabled.

Custom Payload Attributes

Specify shared state objects to be included in the message payload sent to the client. The size of the payload must not exceed 3Kb, or a NodeProcessException is thrown.

To add a custom attribute, enter the shared state object name in the text field and click Add. Repeat for each object you want to include in the payload.

Push Type

Select the type of the push notification that must be processed before the notification is sent. Possible values are:

  • Tap to Accept: Requires the user to tap to accept. This is the default notification type.

  • Display Challenge Code: Requires the user to select one of three numbers displayed on their device. This selected number must match the code displayed in the browser for the request to be verified.

  • Use Biometrics to Accept: Requires the user’s biometric authentication to process the notification.

Example

Example push authentication journey
Figure 4. Example Push Authentication Journey
Node connections
Table 1. List of node connections
Source node Outcome path Target node

Page Node containing:

  • Platform Username

  • Platform Password

Data Store Decision

Data Store Decision

True

Push Sender

False

Failure

Push Sender

Sent

Push Wait

Not Registered

MFA Registration Options

Push Wait

Done

Push Result Verifier

Exit

Recovery Code Collector Decision

Push Result Verifier

Success

Success

Failure

Failure

Expired

Push Sender

Waiting

Push Wait

MFA Registration Options

Register

Push Registration

Get App

Get Authenticator App

Skip

Success

Opt-out

Opt-out Multi-Factor Authentication

Recovery Code Collector Decision

True

Success

False

Retry Limit Decision

Push Registration

Success

Recovery Code Display Node

Failure

Failure

Time Out

MFA Registration Options

Get Authenticator App

MFA Registration Options

Opt-out Multi-Factor Authentication

Success

Retry Limit Decision

Retry

Recovery Code Collector Decision

Reject

Failure

Recovery Code Display Node

Push Sender

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

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

If the user has a registered device:

  1. A push notification is sent to their registered device.

  2. The Push Wait node pauses the authentication journey for 5 seconds, during which time the user can respond to the push notification on their device; for example, by using the ForgeRock Authenticator application.

    • If the user responds successfully, they are authenticated and logged in.

    • If the user fails to respond successfully, they are not authenticated and do not receive a session.

    • If the push notification expires, the journey will send a new push notification.

      The Retry Limit Decision node could be used here to constrain the number of times a new code is sent.
    • If the user has not yet responded, the journey loops back a step and the Push Wait node pauses the authentication journey for another 5 seconds.

    If the user exits the Push Wait node, they can enter a recovery code in order to authenticate.

    In this situation, configure the Exit Message property in the Push Wait node with a message such as: Lost phone? Use a Recovery Code, which appears as follows:

    Example exit message.

A Retry Limit Decision node allows three attempts at entering a recovery code before failing the authentication.

If the user does not have a registered device:

  1. The MFA Registration Options node presents the user with the following options:

    • Register Device The journey continues to the Push Registration node, which displays the QR code that should be scanned with a suitable authenticator app.

    • Get the App The journey continues to the Get Authenticator App node, which displays the links needed to obtain a suitable app; for example, the ForgeRock Authenticator.

    • Skip this step Displayed only if the node configuration lets the user skip. In this example journey, skipping is linked to the Success outcome. Alternatively, an Inner Tree Evaluator node could have been used for authentication.

    • Opt-out Displayed only if the node configuration allows the user to skip or opt out. The journey continues to the Opt-out Multi-Factor Authentication node, which updates the users' profile to skip MFA with push in the future. In this example, after updating the profile the journey continues to the Success node.

  2. The user registers the device with the Push Registration node. After registration, the recovery codes are displayed to the user for safekeeping, and the journey returns to the Push Sender node to start push notification.

A user must log in using either the device, or a recovery code to manage their registered push devices.

For more information, refer to Manage devices for MFA.

Push Wait node

The Push Wait node pauses the progress of the authentication journey for a specified number of seconds during the processing of a push authentication request.

When the push authentication journey involves a number selection challenge (where the push type of the Push Sender node is set to Display Challenge Code), the node displays the code challenge for the user to complete. Connect the Push Wait node to a Push Result Verifier node to check the result of the code challenge.

Both the wait time and the message to display are configurable.

The message displayed on the exit button can be configured using the Exit Message property.

To provide localized versions of the waiting, push challenge, and exit messages in multiple languages, configure the message properties to specify the locale in the KEY field (for example, en-US) and the message in the VALUE field. The locale selected for display is based on the user’s locale settings in their browser.

Messages provided in the node override the defaults provided by AM.

Outcomes

The Push Wait node has two outcomes: Done and Exit.

Tree evaluation continues along the Done outcome path after the wait time has passed.

Tree evaluation continues along the Exit outcome path if the user clicks the exit button.

Properties

Property Usage

Seconds To Wait

Specify the number of seconds to pause the authentication journey.

Default: 5

Waiting Message

Customize the message to display to the user. To include the remaining seconds in the message, use the {{time}} variable.

Click Add to enter a KEY and VALUE for a localized message and + to save. Repeat for each supported language.

Default: Waiting for response…​

Push Challenge Message

Customize the message containing the challenge code. To include the number challenge, use the {{challenge}} variable.

Click Add to enter a KEY and VALUE for a localized message and + to save. Repeat for each supported language.

Default: Tap the number [{{challenge}}] on the Push Notification to continue.

Exit Message

Customize the message to display to the user when they choose to exit the node before the wait period has elapsed. The message is displayed as a link.

Click Add to enter a KEY and VALUE for a localized message and + to save. Repeat for each supported language.

Default: Cancel

Example

Refer to the Push Sender node example journey for an example of how the Push Wait node is connected in a push authentication journey.

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 journey 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, refer to Register the ForgeRock Authenticator for multi-factor authentication.

Outcomes

  • True

  • False

Journey 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 journey must have already acquired the username, for example by using a Platform Username node.

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

Properties

Property Usage

Recovery Code Type

Specify the type of recovery code the user will submit for verification.

Default: OATH

Recovery Code Display node

The Recovery Code Display node is used in conjunction with the WebAuthn Registration node, OATH 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 journey evaluation continues along the Success outcome path of the MFA nodes, when 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, journey evaluation continues along the only outcome path, and nothing is displayed to the user.

Generated recovery codes cannot be retrieved from the user’s profile - they are one-way encrypted. The Recovery Code Display node is the one and only opportunity to view the recovery codes, and keep them safe.

Outcomes

Single outcome path.

Properties

This node has no configurable properties.

Example

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

trees-node-recovery-code-display-output
Figure 5. 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 journey must have already acquired a username, for example by using a Platform Username node.

If the user’s client does not support web authentication, journey evaluation will continue along the Unsupported outcome path. For example, clients connected over the HTTP protocol rather than HTTPS do not support WebAuthn. (HTTPS may not be required when testing locally, on http://localhost, for example. For more information, refer to Is origin potentially trustworthy?)

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

If AM encounters an issue when attempting to authenticate using the device, journey 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 journey 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 a client error occurs, the error type and description are added to a property named WebAuthenticationDOMException in the shared state. This property can be read by other nodes later in the journey, if required.

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. Journey 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, journey evaluation continues along the Success outcome path.

Outcomes

  • Unsupported

  • No Device Registered

  • Success

  • Failure

  • Client Error

  • Recovery Code (configurable)

Properties

Property Usage

Relying party identifier

Specifies the domain used as the relying party identifier during web authentication. If not specified, AM uses the domain name of the instance, for example openam.example.com.

Specify an alternative domain if your AM instances are behind a load balancer, for example.

Origin domains

Specifies a list of fully qualified URLs to accept as the origin of incoming requests.

If left empty, AM accepts any incoming domain.

User verification requirement

Specifies the required level of user verification.

The available options are:

REQUIRED

The authenticator used must verify the identity of the user, for example, by using biometrics. Authenticators that do not verify the identity of the user should not be activated for authentication.

PREFERRED

Use of an authenticator that verifies the identity of the user is preferred, but if none are available any authenticator is accepted.

DISCOURAGED

Use of an authenticator that verifies the identity of the user is not required. Authenticators that do not verify the identity of the user should be preferred.

Allow recovery codes

Specify whether to allow the user to enter one of their recovery codes instead of performing an authentication gesture.

Enabling this options adds a Recovery Code outcome path to the node. This outcome path should lead to a Recovery Code Collector Decision node in order to collect and verify the recovery code.

Timeout

Specify the number of seconds to wait for a response from an authenticator.

If the specified time is reached, journey evaluation continues along the Client error outcome path, and a relevant message is stored in the WebAuthenticationDOMException property of the shared state.

Username from device

Specifies whether AM requests that the device provides the username.

When enabled, if the device is unable to store or provide usernames, the node will fail and results in the Failure outcome.

For information on using this property for usernameless authentication with ForgeRock Go, refer to Configuring Usernameless Authentication with ForgeRock Go.

Return challenge as JavaScript

Specifies that the node returns its challenge as a fully encapsulated client-side JavaScript that interacts directly with the WebAuthn API, and auto-submits the response back.

If disabled, the node returns the challenge and associated data in a metadata callback. A custom UI, for example an application using the ForgeRock SDKs, uses the information from the callback to interact with the WebAuthn API on AM’s behalf.

Example

trees-node-webauthn-auth-example
Figure 6. Example WebAuthn Authentication journey

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

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

If the user’s client does not support WebAuthn, the journey 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 journey that allows the user to register a device. This stage could also be an Inner Tree Evaluator, with a registration journey 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:

trees-node-webauthn-waiting
Figure 7. The WebAuthn Authentication node waiting for an authenticator

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 relying party details configured in the node are often included in the consent message to help the user verify the entity that is requesting access.

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

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 journey’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 journey, then journey evaluation continues along the Failure outcome path.

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

Outcomes

  • Success

  • Failure

Properties

Property Usage

Generate recovery codes

Specify whether WebAuthn device recovery codes should be generated. If enabled, recovery codes are generated and stored in the journey’s transient state, and stored alongside the device profile.

Use the Recovery Code Display node to display the codes to the user for safe keeping.

Generating recovery codes will overwrite all existing WebAuthn device recovery codes.

Only the most recent set of recovery codes can be used for authentication if a device has been lost or stolen.

Maximum saved devicees

Specify the maximum number of WebAuthn device to save in a user’s profile. 0 for unlimited.

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, journey evaluation will continue along the Unsupported outcome path. For example, clients connected over the HTTP protocol rather than HTTPS do not support WebAuthn.

If AM encounters an issue when attempting to register using a device, journey 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 journey 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 a client error occurs, the error type and description are added to a property named WebAuthenticationDOMException in the shared state. This property can be read by other nodes later in the journey, if required.

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

Outcomes

  • Unsupported

  • Success

  • Failure

  • Client Error

Properties

Property Usage

Relying party

Specify the name of the relying party entity that is registering and authenticating users by using WebAuthn.

For example, Example Inc..

Relying party identifier

Specifies the domain used as the relying party identifier during WebAuthn. If not specified, AM uses the domain name of the instance, for example openam.example.com.

Specify an alternative domain if your AM instances are behind a load balancer, for example.

Origin domains

Specifies a list of fully qualified URLs to accept as the origin of incoming requests.

If left empty, AM accepts any incoming domain.

User verification requirement

Specifies the required level of user verification.

The available options are:

REQUIRED

The authenticator used must verify the identity of the user, for example by using biometrics. Authenticators that do not verify the identity of the user should not be activated for registration.

PREFERRED

Use of an authenticator that verifies the identity of the user is preferred, but if none are available any authenticator is accepted.

DISCOURAGED

Use of an authenticator that verifies the identity of the user is not required. Authenticators that do not verify the identity of the user should be preferred.

Preferred mode of attestation

Specifies whether AM requires that the authenticator provides attestation statements.

The available options are:

NONE

AM does not require the authenticator to provide attestation statements. If the authenticator does send attestation statements, AM will not verify them, and will not fail the process.

INDIRECT

AM does not require the authenticator to provide attestation statements. If the authenticator does send attestation statements, AM will verify them, and will fail the process if they fail verification.

DIRECT

AM requires that the authenticator provides attestation statements, and will verify them. The process will fail if the attestation statements cannot be verified.

AM supports the following attestation formats:

You must set the Preferred mode of attestation property to NONE to use an authenticator that provides attestation statements in a format other than the supported formats above.

Specifically, AM does not currently support:

Accepted signing algorithms

Specify the algorithms that authenticators can use to sign their assertions.

Authentication attachment

Specifies whether AM requires that the authenticator is a particular attachment type.

There are two types of authenticator attachment:

  • An authenticator that is built-in to the client device is labelled a platform attachment.

    A fingerprint scanner built-in to a phone or laptop is an example of a platform attachment authenticator.

  • An authenticator that can roam, or move, between different client devices is labelled a cross-platform attachment.

    A USB hardware security key is an example of a cross-platform attachment authenticator.

The available options are:

UNSPECIFIED

AM accepts any attachment type.

PLATFORM

The authenticator must be a platform attachment type. The client should not activate other authenticator types for registration.

CROSS_PLATFORM

The authenticator must be a cross-platform attachment type. The client should not activate other authenticator types for registration.

Trust Store alias

The alias of the realm trust store holding the secrets necessary to validate a supplied attestation certificate. The alias name must only contain the characters a-z and the . symbol.

Enforce revocation check

Specifies whether to enforce certificate revocation checks. When enabled, then any attestation certificate’s trust chain MUST have a CRL or OCSP entry that can be verified by AM during processing.

When disabled, certificates are not checked for revocation. You must ensure expired or revoked certificates are manually removed.

Timeout

Specify the number of seconds to wait for a response from an authenticator.

If the specified time is reached, journey evaluation continues along the Client error outcome path, and a relevant message is stored in the WebAuthenticationDOMException property of the shared state.

Limit registrations

Specify whether the same authenticator can be registered multiple times.

If enabled, the client should not activate an authenticator that is already registered for registration.

Generate recovery codes

Specify whether WebAuthn-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.

If you have enabled the Store device data in transient state and there are not saving the device data to the user’s profile immediately, do not enable this property. Enable the Generate recovery codes property in the WebAuthn Device Storage node instead.

Generating recovery codes will overwrite all existing WebAuthn-specific recovery codes.

Only the most recent set of recovery codes can be used for authentication if a device has been lost or stolen.

Store data in transient state

Specify whether the information provided by the device to the node will be stored in the journey’s transient state for later analysis by subsequent nodes, using the key webauthnData.

In addition to the information provided by the device, the type of attestation achieved; for example, BASIC, CA, SELF and so on, will be stored in the journey’s transient data, using the key webauthnAttestationType.

The amount of data involved can be large. Only enable this option if you intend to analyze it.

Store device data in transient state

Specify whether the information about the device required for WebAuthn is stored in the journey’s transient state rather than saved immediately to the user’s profile.

Enable this option if you intend to make decisions in scripts, and have enabled the Store data in transient state property, and therefore do not want to register the device to the user until the outcome of the analysis is complete.

Do not alter the data whilst it is in the journey’s transient state, nor when saved to a user’s profile.

Modifying the device data will likely cause the device to be unable to authenticate.

Use the WebAuthn Device Storage node to write the device data to the user’s profile when this option is enabled.

When disabled, device data is written automatically to the user’s profile when registration is successful.

Username to device

Specifies whether AM requests that the device stores the user’s username.

When enabled, if the device is unable to store or provide usernames, the node will fail and results in the Failure outcome.

For information on using this property for usernameless authentication with ForgeRock Go, refer to Configure usernameless authentication with ForgeRock Go.

Shared state attribute for display name

Specifies a variable in journey’s shared state that contains a display name for the user; for example, their full name, or email address.

The value is written to devices alongside the username when the Username to device property is enabled, and helps the user select between the accounts they may have on their devices.

If not specified, or the variable is not found in shared state, the user name is used.

For information on using this property for usernameless authentication with ForgeRock Go, refer to Configure usernameless authentication with ForgeRock Go.

Return challenge as JavaScript

Specifies that the node returns its challenge as a fully encapsulated client-side JavaScript that interacts directly with the WebAuthn API, and auto-submits the response back.

If disabled, the node returns the challenge and associated data in a metadata callback. A custom UI; for example, an application using the ForgeRock SDKs, uses the information from the callback to interact with the WebAuthn API on AM’s behalf.

Maximum saved devicees

Specify the maximum number of WebAuthn device to save in a user’s profile. 0 for unlimited.

Example

trees-node-webauthn-reg-example
Figure 8. Example journey with WebAuthn Registration node

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

After verifying the users credentials against the configured data store, journey 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:

trees-node-webauthn-waiting
Figure 9. The WebAuthn Registration node waiting for an authenticator

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 relying party details configured in the node are often included in the consent message to help the user verify the entity that is requesting access.

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, journey 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 journey evaluation continuing to the Failure outcome.

Risk management authentication nodes

Use the following nodes to examine the perceived risk associated to the authentication and act on it:

Account Active Decision node

Checks if the account the user has entered is activated. This node relies on the journey’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, refer to Account lockout for journeys.

Outcomes

  • True

  • False

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, refer to Account lockout for journeys.

Outcomes

Single outcome path.

Properties

Property Usage

Lock Action

Choose whether to LOCK or UNLOCK the authenticating user’s account profile.

The Data Store Decision authentication node checks if the account profile is in the LOCK state. For more information, refer to Data Store Decision node.

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:

The RetryLimit example authentication journey, showing Account Lockout Decision node usage.
Figure 10. RetryLimit journey with Account Lockout Decision node

Auth Level Decision node

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

Outcomes

  • True

  • False

Properties

Property Usage

Sufficient Authentication Level

Journey evaluation continues along the True path if the current authentication level is equal to or greater than the entered integer. Otherwise, the journey evaluation continues along the False path.

CAPTCHA node

The CAPTCHA node implements Google’s reCAPTCHA v2 and reCAPTCHA v3 widgets and hCaptcha’s v1 widget, to add CAPTCHA support to authentication journeys.

This node verifies the response token received from Google or hCaptcha and creates a CAPTCHA callback for the UI to interact with.

By default, the node is configured for Google’s reCAPTCHA v2.

Outcomes

  • True (success)

  • False (failure)

Properties

Property Usage

CAPTCHA Site Key (required)

The CAPTCHA site key, provided by Google or hCaptcha when you sign up for access to the API.

CAPTCHA Secret Key (required)

The CAPTCHA secret key, provided by Google or hCaptcha when you sign up for access to the API.

CAPTCHA Verification URL (required)

The URL used to verify the CAPTCHA submission. Possible values are:

  • Google: https://www.google.com/recaptcha/api/siteverify

  • hCaptcha: https://hcaptcha.com/siteverify

CAPTCHA API URL (required)

The URL of the JavaScript that loads the CAPTCHA widget. Possible values are:

  • Google: https://www.google.com/recaptcha/api.js

  • hCaptcha: https://hcaptcha.com/1/api.js

Class of CAPTCHA HTML Element

The class of the HTML element required by the CAPTCHA widget. Possible values are:

  • Google: g-recaptcha

  • hCaptcha: h-captcha

ReCaptcha V3 node

If you’re using Google reCaptcha, specifies whether it’s v2 or v3. Turn on for v3.

Score Threshold

If you’re using Google reCAPTCHA v3, or hCaptcha, enter a Score Threshold. reCAPTCHA v3 and hCaptcha return a score for each user request, based on observed interaction with your site. Both facilities "learn" by observing real site traffic, so scores in a staging environment or in a production deployment that has just been implemented might not be very accurate. A score of 1.0 is likely a good user interaction, while 0.0 is likely to be a bot. The threshold you set here determines whether to allow or deny access, based on the score returned by Google or hCaptcha. You can generally start with a threshold of 0.5. For more information about score thresholds, refer to the Google documentation.

Example

An example journey using the CAPTCHA node.
Figure 11. Example journey with CAPTCHA node

Test the CAPTCHA node

ForgeRock provides a Postman collection to configure AM to test the CAPTCHA node. The Postman collection contains the queries to demonstrate the CAPTCHA node with reCAPTCHA V2, V3 and with hCaptcha. Before you start, set up a reCAPTCHA V2 and V3 site, and an hCaptcha site, and copy their site and secret keys.

  1. Download and install Postman.

  2. Download the ForgeRock CAPTCHA Collection.

  3. Import the collection into Postman:

    • Select File > Import …​ > Upload Files.

    • Select the CAPTCHA collection, and click Open, then click Import.

  4. Change the collection variables to suit your environment:

    • On the Collections tab, select the ForgeRock CAPTCHA Collection.

    • Click on the Variables tab, and set the value of at least the following variables:

      • URL_base

      • admin_password

      • demo_username

      • demo_password

    • Click Update to save your changes.

      You are ready to run the collection.

  5. When the authentication journeys have been created, visit the following URLs in your browser to demonstrate the login flow for each CAPTCHA type:

    • URL_base/XUI/?realm=sub_realm&service=recaptchav3

    • URL_base/XUI/?realm=sub_realm&service=recaptchav2

    • URL_base/XUI/?realm=sub_realm&service=hcaptcha

Use the demo_username and demo_password to log in.

Legacy CAPTCHA node

The Legacy CAPTCHA node verifies the response token received from the CAPTCHA verifier in addition to creating a CAPTCHA callback for the UI to interact with. Default values are for Google ReCAPTCHA.

This node has been superseded by the CAPTCHA node. Use that node instead.

This node verifies the response token received from Google or hCaptcha and creates a CAPTCHA callback for the UI to interact with.

Outcomes

  • True (success)

  • False (failure)

Properties

Property Usage

CAPTCHA Site Key (required)

The CAPTCHA site key, provided by Google or hCaptcha when you sign up for access to the API.

CAPTCHA Secret Key (required)

The CAPTCHA secret key, provided by Google or hCaptcha when you sign up for access to the API.

CAPTCHA Verification URL (required)

The URL used to verify the CAPTCHA submission. Possible values are:

  • Google: https://www.google.com/recaptcha/api/siteverify

  • hCaptcha: https://hcaptcha.com/siteverify

CAPTCHA API URL (required)

The URL of the JavaScript that loads the CAPTCHA widget. Possible values are:

  • Google: https://www.google.com/recaptcha/api.js

  • hCaptcha: https://hcaptcha.com/1/api.js

Class of CAPTCHA HTML Element

The class of the HTML element required by the CAPTCHA widget. Possible values are:

  • Google: g-recaptcha

  • hCaptcha: h-captcha

Modify Auth Level node

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

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

Outcomes

Single outcome path.

Properties

Property Usage

Value To Add

Enter a positive integer to increase the current authentication level, or a negative integer to decrease the current authentication level by the specified value.

Behavioral authentication nodes

Use the following nodes to adjust the behavior of authentication journeys:

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.

Outcomes

Single outcome path.

Properties

Property Usage

Identity Attribute

The attribute used to identify the object in IDM.

Default: userName

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.

Outcomes

  • True

  • False

Properties

Property Usage

Interval

The type of interval the decision should trigger on. Valid types are EVERY and AT. EVERY refers to a recurring action that happens every specified number of successful logins, such as prompting a user to update their contact information every 30 days. AT refers to an action that occurs once, after the specified number of successful logins. For example, prompting the user to set their communication preferences once they have logged in 10 times.

Default: AT

Amount

The amount (count) of logins the interval should trigger on.

Default: 25

Identity Attribute

The attribute used to identify the object in IDM.

Default: userName

Contextual authentication nodes

Use the following nodes to change the journey or set a cookie based on the authentication context:

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.

Outcomes

  • True

  • False

Properties

Property Usage

Name of Cookie (required)

Journey evaluation continues along the True path if the named cookie is present in the incoming authentication request. Otherwise, the journey evaluation continues along the False path.

Device Geofencing node

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 node to determine if the authenticating user’s device is located within range of configured, trusted locations.

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

Outcomes

  • Inside

  • Outside

Properties

Property Usage

Trusted Locations (required)

Specify the latitude and longitude of at least one trusted location. Separate the values with a comma; for example, 37.7910855,-122.3951663.

Geofence Radius (km)

Specifies the maximum distance, in kilometers, that a device can be from a configured trusted location.

The distance is calculated point-to-point.

Device Location Match node

The Device 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 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 journey before attempting to match locations.

Outcomes

  • True

  • False

  • Unknown Device

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

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

Properties

Property Usage

Maximum Radius (km)

Specifies the maximum distance, in kilometers, that a device can be from a previously saved location.

The distance is calculated point-to-point.

Device Match node

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 node to determine if the authenticating user is on a previously saved, trusted device.

You can choose between two methods of comparison:

  • Built-in matching

    The node handles the comparison and matching, and you can configure the acceptable variance, and specify a time frame that profiles are considered current.

  • Custom matching

    Create scripts of type Journey Decision Node that compare captured device data against trusted device profiles.

    ForgeRock also provides a more complete sample script, as well as instructions for its use, and a development toolkit. Find these resources on GitHub, at: https://github.com/ForgeRock/forgerock-device-match-script.

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

Outcomes

  • True

  • False

  • Unknown Device

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

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

Properties

Property Usage

Acceptable Variance

Specify the maximum amount of device attribute differences that is still acceptable for a match.

Expiration

Specify the maximum age, in the number of days since being saved, that existing profiles can be considered for comparison. Device profiles that were saved to the user’s profile before this time will not be compared to the collected metadata.

Default: 30

Use Custom Matching Script

Specifies whether to use a custom script to compare the collected metadata with saved device profiles. The script type must be Journey Decision Node.

Default: Authentication Tree Decision Node Script

When a custom matching script is used, the Acceptable Variance and Expiration properties are ignored.

Custom Matching Script

Specifies the custom script to use if the Use Custom Matching Script property is enabled.

Only scripts of type Journey Decision Node appear in the list.

Device Profile Collector node

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, refer to Interactive callbacks.

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

Device Metadata

Information such as the platform, versions, device name, hardware information, and the brand of the device being used.

The captured data is in JSON format, and stored in the authentication journey’s shared state, in a variable named forgeRock.device.metadata.

Device Location

Provides the last known latitude and longitude of the device’s location.

The captured data is in JSON format, and stored in the authentication journey’s shared state, in a variable named forgeRock.device.location.

The collection of geographical information requires end-user approval. This process is driven by a browser function. A pop-up displays, asking if sharing geographical location can be permitted. Note that this function is not honored by the browser if the connection is not secure.

It is up to you what information you collect from users and devices.

You should always use data responsibly and provide your users appropriate control over data they share with you.

You are responsible for complying with any regulations or data protection laws.

In addition to the collected metadata, an identifier string in the JSON uniquely identifies the device.

Use this node with the Device Profile Save 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 Location Match node.

Outcomes

Single outcome path.

Properties

Property Usage

Maximum Profile Size (KB)

Specifies the maximum accepted size, in kilobytes, of a device profile.

If the collected profile data exceeds this size, authentication fails.

Default: 3

Collect Device Metadata

Specifies whether device metadata is requested.

Collect Device Location

Specifies whether device location is requested.

Message

Specifies an optional message to display to the user while the node collects the requested data.

You can provide the message in multiple languages by specifying the locale in the KEY field, for example en-US.

The locale selected for display is based on the user’s locale settings in their browser.

Messages provided in the node override the defaults provided by AM.

Device Profile Save node

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 node when you want to reuse the collected data in future authentications; for example, with the Device Match and Device Location Match node.

You must establish the identity of the user in the journey 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 for the realm.

Outcomes

Single outcome path.

Properties

Property Usage

Device Name Variable

Specifies the name of a variable in the authentication journey’s shared state that contains an alias label for the device profile.

Maximum Saved Profiles

Specify the maximum number of device profiles to save in a user’s profile.

When the maximum is reached, saving a new device profile replaces the oldest record.

Save Device Metadata

Specifies whether device metadata is saved to the user’s profile.

Save Device Location

Specifies whether device location metadata is saved to the user’s profile.

Device Tampering Verification node

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 node to retrieve the tampering score from the device.

Outcomes

  • Not Tampered

  • Tampered

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

Properties

Property Usage

Score Threshold

Specifies the score threshold for determining if a device has been tampered with. Enter a decimal fraction, between 0 and 1; for example, 0.75.

The higher the score returned from the device, the more likely the device is jailbroken, rooted, or is a potential security risk.

Emulators score the maximum; 1.

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 in the AM admin UI under 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.

The Persistent Cookie Decision authentication node recreates the received persistent cookie, updating the value for the idle time property. Therefore, cookie creation properties as used by the Set Persistent Cookie node are also available in the Persistent Cookie Decision authentication node.

Outcomes

  • True

  • False

Journey evaluation continues along the True outcome path if the persistent cookie is present and all the verification checks above are satisfied.

Otherwise, journey evaluation continues along the False outcome path.

Properties

Property Usage

Idle Timeout

Specifies the maximum amount of idle time allowed before the persistent cookie is invalidated, in hours. If no requests are received and the time is exceeded, the cookie is no longer valid.

Enforce Client IP

When enabled, ensures that the persistent cookie is only used from the same client IP to which the cookie was issued.

Use Secure Cookie

When enabled, adds the Secure flag to the persistent cookie.

If the Secure flag is included, the cookie can only be transferred over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.

Use HTTP Only Cookie

When enabled, adds the HttpOnly flag to the persistent cookie.

When the HttpOnly flag is included, that cookie will not be accessible through JavaScript. According to RFC 6265, the HttpOnly flag, "instructs the user agent to omit the cookie when providing access to cookies via 'non-HTTP' APIs (for example, a web browser API that exposes cookies to scripts)."

HMAC Signing Key (required)

Specifies a key to use for HMAC signing of the persistent cookie. Values must be base64-encoded and at least 256 bits (32 bytes) long.

To consume the persistent cookies generated by instances of the Set Persistent Cookie node in the journey, ensure they are using the same HMAC signing key.

To generate an HMAC signing key, run one of the following commands:

$ openssl rand -base64 32

or

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

Persistent cookie name

Specifies the name of the persistent cookie to check.

Example

The PersistentCookie authentication journey, showing persistent cookie decision and set persistent cookie node usage.
Figure 12. PersistentCookie journey

The Set Custom Cookie node lets you store an additional custom cookie in the client. The node uses the specified properties to create a cookie with a custom name and value, and optionally, sets attributes such as the cookie path, domain, expiry, and security flags.

Journey evaluation continues along the single outcome path. The custom cookie is created when AM next returns to the client.

The Set Custom Cookie node can be used in conjunction with the Configuration Provider node to extend custom capabilities. For instance, create a Config Provider script to set custom static values or access values from the shared or transient state.

Include all the Set Custom Cookie node attributes in the configuration provider script’s config map. This example shows how to set the attributes of the custom cookie to static values:

config = {
    "name": "testname",
    "value": "testvalue",
    "maxAge": "60",
    "domain": "tenant.forgeblocks.com",
    "path": "/",
    "useSecureCookie": false,
    "useHttpOnlyCookie": false,
    "sameSite": "LAX"
};

Reference the script when you create a Configuration Provider node, and set the Node Type to Set Custom Cookie. For example:

Configuration Provider node referencing the Set Custom Cookie node

Example

This example uses a Set Custom Cookie node in a login journey. The custom cookie is set in the client after the user has successfully authenticated.

Set Custom Cookie node in a login journey.
Figure 13. Login Tree With Set Custom Cookie Node (ForgeRock Identity Platform)

Outcomes

Single outcome path.

Properties

Property Usage

Custom Cookie Name (required)

Sets the name of the custom cookie.

The cookie name can contain any US-ASCII characters except for: space, tab, control, or a separator character (()<>@,;:"/[]?=\{}).

Custom Cookie Value (required)

Sets the value of the custom cookie.

Max Age

(Optional). Specifies the length of time the custom cookie remains valid, in seconds. If that time is exceeded, the cookie is no longer valid.

Both the Max-Age and Expires attributes are set in the cookie to increase compatibility with different browsers.

If omitted, the cookie will expire at the end of the current session. The precise implementation of this is determined by the specific browser. Refer to RFC 6265 for details.

Custom Cookie Domain

(Optional). Sets the domain that the custom cookie will be sent to.

Custom Cookie Path

(Optional). Sets the path of the custom cookie.

Use Secure Cookie

When enabled, adds the Secure flag to the custom cookie.

If the Secure flag is included, the cookie can only be transferred over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.

Use HTTP Only Cookie

When enabled, adds the HttpOnly flag to the custom cookie.

When the HttpOnly flag is included, the cookie is not accessible to scripts.

Custom Cookie SameSite attribute

Sets the SameSite attribute of the custom cookie.

The default value is LAX, to align with most modern browsers.

For more information about cookies in AM, refer to SameSite cookie support in AM and IG.

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

Outcomes

Single outcome path.

Properties

Property Usage

Idle Timeout

Specifies the maximum amount of idle time allowed before the persistent cookie is invalidated, in hours. If no requests are received and the time is exceeded, the cookie is no longer valid.

Max life

Specifies the length of time the persistent cookie remains valid, in hours. If that time is exceeded, the cookie is no longer valid.

Use Secure Cookie

When enabled, adds the Secure flag to the persistent cookie.

If the Secure flag is included, the cookie can only be transferred over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.

Use HTTP Only Cookie

When enabled, adds the HttpOnly flag to the persistent cookie.

When the HttpOnly flag is included, that cookie will not be accessible through JavaScript. According to RFC 6265, the HttpOnly flag, "instructs the user agent to omit the cookie when providing access to cookies via 'non-HTTP' APIs (for example, a web browser API that exposes cookies to scripts)."

HMAC Signing Key (required)

Specifies a key to use for HMAC signing of the persistent cookie. Values must be base64-encoded and at least 256 bits (32 bytes) long.

To consume the persistent cookies generated by instances of the Set Persistent Cookie node in the journey, ensure they are using the same HMAC signing key.

To generate an HMAC signing key, run one of the following commands:

$ openssl rand -base64 32

or

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

Persistent Cookie Name

Specifies the name used for the persistent cookie.

Federation authentication nodes

Use the following nodes to configure journeys with federation capabilities, such as OAuth 2.0, social authentication, and account provisioning:

SAML2 Authentication node

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

Regardless of which outcome the journey continues along (Account exists or No account exists), providing the node reaches the end of its processing without a failure, it sets the successURL parameter in the journey’s shared state to the value of the RelayState parameter in the request.

If the request does not provide a value for this parameter, 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:

  • You have configured a remote IdP and a hosted SP in a CoT in the same realm where the authentication node will be configured.

  • The SP is configured for integrated mode. Refer to SSO and SLO in Integrated Mode.

Outcomes

  • Account exists

  • No account exists

If a user account is found that matches the federated account, journey evaluation continues along the Account exists outcome.

Otherwise, a matching account could not be found, and journey evaluation continues along the No account exists outcome.

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, refer to 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, refer to 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.

Authentication Context Classes 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. In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context.

Authentication Context Supported by the SP

When specifying multiple authentication context classes, use the kbd:[|] 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 kbd:[|] character to separate the URIs.

For more information, refer to 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, refer to SSO and SLO in integrated mode.

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.

Outcomes

  • Account exists

  • No account exists

Properties

Property Usage

Transformation Script

A script that transforms a normalized social profile to an identity or managed object.

Select Normalized Profile to Managed User, or any other script you have created for this purpose.

Username Attribute

The attribute in IDM that contains the username for this object.

Client Type

Specify the client type you are using to authenticate to the provider.

Use the default, BROWSER, when making use of the ForgeRock-provided user interfaces, or the ForgeRock SDK for JavaScript. This causes the node to return the RedirectCallback.

Select NATIVE if you are using the ForgeRock SDKs for Android or iOS. This causes the node to return the IdPCallback.

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.

Outcomes

Single outcome path.

Properties

This node has no configurable properties.

For examples, refer to SSO and SLO in integrated mode.

Identity management authentication nodes

Use the following nodes to perform identity management during an authentication journey flow, such as mapping anonymous users to a session.

Accept Terms and Conditions node

This node prompts the user to accept the currently active terms and conditions.

For information on setting up terms and conditions, refer to Terms & Conditions in the platform documentation.

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

Note that there is no failure path for this node. The user must accept the terms and conditions in order to proceed:

Example Accept Terms and Conditions node output.

Outcomes

Single outcome path.

Properties

This node has no configurable properties.

Example

In a progressive profile journey, 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.

An Example authentication journey, showing Accept Terms and Conditions node usage.
Figure 14. Example journey with Accept Terms and Conditions node

Attribute Collector node

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

To request a value, the attribute must be present in the IDM schema of the Identity Object configured in the journey. 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 journey, or within a page node.

Outcomes

Single outcome path.

Properties

Property Usage

Attributes to Collect (required)

A list of the attributes you wish to collect, based on the attributes found in the IDM schema for the identity object configured in the journey.

All Attributes Required

When enabled, all attributes collected in this node are required in order to continue.

Validate Input

When enabled, the content input in this node should be validated against IDM policy settings specified in the IDM schema.

Identity Attribute

The attribute used to identify the object in IDM.

Default: userName

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.

Outcomes

  • True

  • False

Properties

Property Usage

Present Attribute

The object attribute to verify is present in the IDM object. This can be an otherwise private attribute, such as password.

Default: password

Identity Attribute

The attribute used to identify the object in IDM.

Default: userName

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

Outcomes

  • True

  • False

Properties

Property Usage

Comparison Attribute (required)

The object attribute to compare.

Comparison Operation

The operation to perform on the object attribute; PRESENT checks for existence of an attribute, EQUALS checks if the object’s attribute value equals the configured comparison value.

Default: EQUALS

Comparison Value

This property is only relevant when using the EQUALS comparison operation, and is the value to compare the object’s attribute value to.

Identity Attribute

The attribute used to identify the object in IDM.

Default: userName

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.

Outcomes

Single outcome path.

Properties

Property Usage

All Mappings Required

If enabled, all mappings listed by this node require consent in order to move forward.

Privacy & Consent Message

Localized message providing the privacy and consent notice. The key is the language (such as en or fr), and the value is the message to display.

Create Object node

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

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

Outcomes

  • Created

  • Failed

Properties

Property Usage

Identity Resource

The type of IDM managed identity resource object that this node will create. It must match the identity resource type for the current journey.

To check for the available managed identity resource types, go to the IDM admin UI, and open the Manage drop-down list, at the upper right corner of the screen.

Identity managed object types are preceded by the icon.

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.

Outcomes

Single outcome path.

Properties

Property Usage

User Name

The attribute used to identify the username in an IDM object.

Default: userName

Identity Attribute

The attribute used to identify the object in IDM. Since this node is generally used for recovering a username, the identity attribute in this case should be some other attribute that is unique to a user object, such as the user’s email address. You will receive an exception if there is more than one result for this attribute, so make sure the value of whatever attribute you select is unique for each user.

Default: mail

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 journey’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.

Outcomes

  • True

  • False

Properties

Property Usage

Identifier

The attribute to collect from an IDM object.

Default: userName

Identity Attribute

The attribute used to identify the object in IDM. Since this node is generally used for recovering a username, the identity attribute in this case should be some other attribute that is unique to a user object, such as the user’s email address.

Default: mail

Example

The following is an example of a forgotten password journey. The user enters information that the Identify Existing User 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 journey. Once authentication is resumed, the user is sent to a different journey to reset their password:

Authentication journey showing identify existing user node usage during a forgotten password flow.
Figure 15. Identify Existing 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.

Outcomes

  • True

  • False

Properties

Property Usage

Identity Attribute

The attribute used to identify the object in IDM.

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, refer to Security Questions.

Outcomes

Single outcome path.

Properties

Property Usage

Purpose Message

A localised message describing the purpose of the data requested from the user.

Allow User-Defined Questions

When enabled, users can create their own KBA questions. Disable this setting to restrict users to select from predefined questions only.

Default: Enabled

Questions

Create or modify custom localized questions that the user can choose from when defining security questions.

To add a localized security question:

  1. Click + to open the Add a Security Question form.

  2. Select from the list of existing locales or add a new locale, type a question into the textfield, and click Done.

  3. Repeat to add further questions, and click Save when complete.

To edit an existing security question, click the edit icon (), make your changes, and click Save.

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.

Outcomes

  • True

  • False

Properties

Property Usage

KBA Attribute

The IDM object attribute in which KBA questions and answers are stored.

Default: kbaInfo

Identity Attribute

The attribute used to identify the object in IDM.

Default: userName

Passthrough Authentication node

The Passthrough Authentication node authenticates an identity through a connector to a third-party service. This lets you migrate user profiles without forcing users to reset their passwords, or retain a third-party service indefinitely as the canonical store for authentication credentials.

Before you use the node:

  • Configure the connector to the third-party service.

    For details, refer to Connector configuration.

  • If you plan to collect credentials in the identity repository for users, synchronize accounts from the third-party service.

    For details, refer to Sync identities.

Use this node after collecting the authentication credentials. For example, use the Platform Username node and Platform Password node to collect the username and password.

Pass the credentials to this node to authenticate the identity against the service.

Outcomes

  • Authenticated

  • Missing Input

  • Failed

Properties

Property Usage

System Endpoint (required)

Name of the connector to the third-party service that performs authentication.

Object Type

The OpenICF object type for the object being authenticated.

Default: account

Identity Attribute

The username attribute for authentication.

Default: userName

Password Attribute

The password attribute for authentication.

Default: password

Example

Before trying this example, synchronize accounts from the third-party service. The example shows a login journey that tries pass-through authentication when local authentication fails, and stores the user password when authentication with the third-party service succeeds.

In this example, the user enters their credentials with the Platform Username node and Platform Password node. The Data Store Decision node authenticates against the platform directory service. On failure, authentication passes through to the third-party service. On success, the Identify Existing User node and Required Attributes Present node check for a valid user profile. The Patch Object node updates the user’s profile with the successful password:

Passthrough authentication that updates user credentials.
Figure 16. Passthrough Authentication
Node connections
Table 2. List of node connections
Source node Outcome path Target node

Page Node containing:

  • Platform Username

  • Platform Password

Data Store Decision

Data Store Decision

True

Passthrough Authentication

False

Increment Login Count

Passthrough Authentication

Authenticated

Identify Existing User

Missing Input

Page Node

Failed

Failure

Identify Existing User

True

Required Attributes Present

False

Increment Login Count

Required Attributes Present

True

Patch Object

False

Increment Login Count

Patch Object

Patched

Increment Login Count

Failed

Increment Login Count

Increment Login Count

Inner Tree Evaluator

Inner Tree Evaluator

True

Success

False

Failure

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.

Outcomes

  • Patched

  • Failed

Properties

Property Usage

Patch as Object

Allows patching as the object being updated. Enable this property to patch a user object as part of the user’s current session, such as when updating their password.

Ignored Fields

Fields from the journey’s shared state that should be ignored as part of patch. If this is empty, all shared-state fields in the journey’s nodeState object are attempted as part of the patch. Use this to keep your patch focused only on the fields you want to update.

Identity Resource

The type of IDM managed identity resource object that this node will create. It must match the identity resource type for the current journey.

To check for the available managed identity resource types, go to the IDM admin UI, and open the Manage drop-down list, at the upper right corner of the screen.

Identity managed object types are preceded by the icon.

Default: managed/user

Identity Attribute

The attribute used to identify the object to update in IDM.

Default: userName

Platform Password node

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

This node uses the _id of the object for policy evaluation. For existing users, the user’s _id must therefore be in the shared state for user-specific policies (such as password history, cannot-contain-others, and so on) to be evaluated. (No _id is available for new users.)

Outcomes

Single outcome path.

Properties

Property Usage

Validate Password

When enabled, this node checks the user’s input against IDM’s password policies, and returns any policy failures as errors. For example, if you submitted an invalid password on registration, the response from this node would include a list of failed policies:

{
    "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\" }"
    ]
},

Password Attribute

The attribute used to store a password in the IDM object.

Default: password

Confirm Password

Enable this option to require the user to enter the password identically in a second field.

Note that this property only appears when the node is placed within a Page node.

Platform Username node

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

Outcomes

Single outcome path.

Properties

Property Usage

Validate Username

When enabled, this node checks the user’s input against IDM’s username policies, and returns any policy failures as errors.

Username Attribute

The attribute used to store a username in the IDM object.

Default: userName

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.

Outcomes

  • True

  • False

Properties

Property Usage

Profile Completeness Threshold (required)

Percentage of user-viewable and user-editable fields in a profile that need to be filled out for the node to pass. Expressed as a number between 0 and 100.

Identity Attribute

The attribute used to identify the object in IDM.

Default: userName

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.

Outcomes

  • True

  • False

Properties

Property Usage

Query Filter (required)

A query filter used to check the contents of an object.

Identity Attribute

The attribute used to identify the object that will be queried in IDM.

Default: userName

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

Outcomes

  • True

  • False

Properties

Property Usage

Identity Resource

The type of IDM managed identity resource object that this node will create. It must match the identity resource type for the current journey.

To check for the available managed identity resource types, go to the IDM admin UI, and open the Manage drop-down list, at the upper right corner of the screen.

Identity managed object types are preceded by the icon.

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.

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

Outcomes

  • Social Authentication

  • Local Authentication

Local authentication can be turned off by disabling Include local authentication.

Properties

Property Usage

Include local authentication

Determines whether local authentication will be included as an available method for authenticating.

Offer only existing providers

Enable this when the social identity provider choices offered should be limited to those already associated with a user object. Use this when a user is authenticating using a new social identity provider, and an account associated with that user already exists (also known as "account claiming").

Password attribute

The attribute in the user object that stores a user’s password for use during local authentication.

Identity Attribute

The attribute used to identify an existing user. Required to support the offer of only existing providers.

Filter Enabled Providers

By default, the node displays all identity providers that are marked as Enabled in the Social Identity Provider Service as a selectable option. Specify the name of one of more providers to filter the list.

View the names of your configured social identity providers by navigating to Services > Social Identity Provider Service > Secondary Configurations.

If this field is not empty, providers must be in the list, and also be enabled in the Social Identity Provider service, in order to be displayed. If left blank, all enabled providers are displayed.

Terms and Conditions Decision node

The Terms and Conditions Decision node verifies that the user has accepted the active set of Terms and Conditions. Use this node to verify that the user has accepted your Terms and Conditions before proceeding (such as logging in, or in a progressive profile journey). The node is often used with the Accept Terms and Conditions node.

For information on setting up Terms and conditions, refer to Terms & Conditions in the platform documentation.

Outcomes

  • True

  • False

Properties

Property Usage

Identity Attribute

The attribute used to identify the object to check in IDM.

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.

Outcomes

  • True

  • False

Properties

Property Usage

Elapsed Time (required)

The amount of time since the user was created, in minutes, that needs to elapse before this node is triggered.

This property also supports specifying basic time units. For example, when setting the property to 10080 minutes, writing 7 days or 1 week also works.

Identity Attribute

The attribute used to identify the object to update in IDM.

Default: userName

Utility authentication nodes

Use the following nodes to perform various tasks during the authentication flow:

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.

Non-agent identities, such as users stored in configured identity repositories, cannot be verified by using the Agent Data Store Decision node. Instead, you should use the Data Store Decision node.

Outcomes

  • True

  • False

The Agent Store journey evaluation continues along the True path if the credentials match those of a configured agent profile. Otherwise, the journey evaluation continues along the False path.

Properties

This node has no configurable properties.

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

Outcomes

Single outcome path.

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 authentication journey, showing Anonymous User Mapping node usage.
Figure 17. Example journey with Anonymous Session Upgrade node

Anonymous User Mapping node

The Anonymous User Mapping node lets users log in to your application or website 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.

The anonymous user status is Inactive by default. If you use the default anonymous user in this node, you must change the user status to Active.

Outcomes

Single outcome path.

Properties

Property Usage

Anonymous User Name

Specifies the username of an account that represents anonymous users. This user must already exist in the realm.

Example

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

A journey showing Social Identity Provider login With Anonymous User Mapping node

Choice Collector node

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

Outcomes

  • Choice 1

    …​

  • Choice n

Properties

Property Usage

Choices

Enter two or more choice strings to display to the user.

To remove a choice, select its delete icon ('x').

Default Choice (required)

Enter the value of the choice to be selected by default.

If you do not specify a default choice, the first choice in the list becomes the default.

Prompt (required)

Enter the prompt string to display to the user when presenting the choices.

Field Display Type

Specifies the format of the options presented to the user. Possible values are:

  • select, lets the user select one or more options from a selection (default)

  • radio, lets the user select a single option from a group of radio buttons

Note that this property only appears when the node is placed within a Page node.

Example:

An example of the choice collector node presenting choices to the authenticating user.

Configuration Provider node

The Configuration Provider node creates a dynamic node configuration, based on the current node state. The node references a script that lets you build up a configuration map object with custom values, and provides this configuration map to the specified node type.

The node has all the outcomes of the specified node and an additional outcome, Configuration failure. Use the Configuration failure outcome to specify what should happen in the journey if the node is unable to build the configuration map, the configuration map is missing required values, or the configuration map is invalid.

Before you use the Configuration Provider node, create a script, of type Configuration Provider Node, that provides the functionality for the node. The map that you build in the script must be named config, and must be populated with the required configuration.

This example creates a configuration map that pulls in the user’s username from the node state to display a custom message, requesting the user to confirm that they are over 18:

config = {
    "message": {"en-GB": "Hi " + nodeState.get("username") + ". Please confirm that you are over 18."},
    "messageYes": {"en-GB": "Confirm"},
    "messageNo": {"en-GB": "Deny"},
};

Refer to the sample script for a reference to the bindings available to this script.

Example

An example of a configuration provider node in a login journey.
Figure 18. Example journey with Configuration Provider node (ForgeRock Identity Platform)

Referencing the script shown in the previous example, the configuration of this node would look something like this:

The configuration of a configuration provider node.

Outcomes

Configurable.

Properties

Property Usage

Script

Select the Config Provider type script that you created for this node. Click + to go to the script editor and create a new Config Provider script. Click Edit Script to modify an existing Config Provider script in the script editor.

Node Type (required)

Select the type of node for which you are generating a configuration.

The Configuration Provider node cannot provide configuration for all node types. The node type must have a fixed set of outcomes that cannot be changed by the node’s configuration.

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 journey will pause until the user clicks a link in the email to resume the journey 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 authentication journey to pause and wait for a response from email, use the Email Template node instead.

Outcomes

Single outcome path.

Properties

Property Usage

Email Template Name

The name of the IDM email template to be sent. Check IDM for the names of available email templates, or to create a new template.

Default: registration

Email Attribute

The IDM attribute storing the address to send the email to.

Default: mail

Email Suspend Message

The localized message to be returned once the journey is suspended. The default message is, "An email has been sent to your inbox."

Object Lookup

Determines whether the object should be looked up in IDM. If enabled, IDM is queried for an existing object. Otherwise, the object in the authentication journey’s shared state is used. For example, if suspending a user registration flow before the user object is created in IDM, this should be set to false. If the registration flow has already created the new user object when the flow is suspended, then this should be set to true.

Identity Attribute

The attribute used to identify the object in IDM.

Default: userName

Example

The following is an example of a forgotten password journey. 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 journey. Once authentication is resumed, the user is sent to a different journey to reset their password:

Authentication journey showing email suspend node usage during a forgotten password flow.
Figure 19. Email Suspend node authentication journey

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 authentication journey to pause and wait for a response from email, use the Email Suspend node instead.

Outcomes

  • Email Sent

  • Email Not Sent

According to OWASP authentication recommendations, the message to the user should be the same in both cases.

Properties

Property Usage

Email Template Name

The name of the IDM email template to be sent. Check IDM for the names of available email templates, or to create a new template.

Default: welcome

Email Attribute

The IDM attribute storing the address to send the email to.

Default: mail

Identity Attribute

The attribute used to identify the object in IDM.

Default: userName

Failure URL node

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

Specifying a failure URL in a journey overrides any gotoOnFail query string parameters.

For more information on how AM determines the redirection URL, and to configure the Validation Service to trust redirection URLs, refer to Configure success and failure redirection URLs.

The URL is also saved into the nodeState object for the failureUrl key, which can be useful for custom node developers.

Outcomes

Single outcome path.

Properties

Property Usage

Failure URL (required)

Specify the full URL to be redirected to when authentication fails.

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 with the specified key in the journey’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, refer to 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.

Example check for existing session script
if (typeof existingSession !== 'undefined') {
  outcome = "hasSession";
} else {
  outcome = "noSession";
}

Outcomes

Single outcome path.

Properties

Property Usage

Session Data Key (required)

Specify the name of a key in the user’s session data to use to retrieve the value.

Shared State Key (required)

Specify the name of a key in the nodeState object to use to store the retrieved value.

Example

Example journey with scripted node to check for session, and get session data node to obtain username.
Figure 20. Get Session Data Journey Example

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

Table 3. Get Session Data Example Keys and Values
Key Sample value

AMCtxId

e370cca2-02d6-41f9-a244-2b107206bd2a-122934

amlbcookie

01

authInstant

2018-04-04T09:19:05Z

AuthLevel

0

CharSet

UTF-8

clientType

genericHTML

FullLoginURL

/openam/UI/Login?realm=%2F

Host

198.51.100.1

HostName

openam.example.com

Locale

en_US

Organization

dc=openam,dc=forgerock,dc=org

Principal

uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org

Principals

amAdmin

Service

ldapService

successURL

/openam/console

sun.am.UniversalIdentifier

uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org

UserId

amAdmin

UserProfile

Required

UserToken

amAdmin

webhooks

myWebHook

Inner Tree Evaluator node

The Inner Tree Evaluator authentication node allows the nesting and evaluation of authentication journeys (previously referred to as trees) as children within a parent journey. There is no limit to the depth of nested journeys.

Any information collected or set by the parent journey, for example, a username or the authentication level, is available to the child journey. Information collected by the child journey is available to the parent once evaluation of the child is complete.

Outcomes

  • True

  • False

Journey evaluation continues along the True path if the child journey reaches the Success exit point. Otherwise, the journey evaluation continues along the False path.

Properties

Property Usage

Tree name (required)

Enter the name of the journey to evaluate.

Message node

The Message authentication node lets you 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.

Outcomes

  • True

  • False

Properties

Property Usage

Message

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.

Locales that you specify here must be real locales, otherwise AM returns an Invalid config error.

If the locale of the user’s browser does not match any locale configured in the node, the node uses the Default Authentication Locale (set, per realm, in Authentication > Settings > General). If there is no default authentication locale, the node uses the Default Locale (set in Deployment > Servers > Server Name >General > System).

If the message property is left blank, the text Default message is displayed to the user.

To remove a message, select its Delete icon ().

Positive answer

Specify a positive answer that will cause journey evaluation to continue along the True outcome path.

Click Add, and enter the locale of the positive answer in the Key field, and the message to display to the user in the Value field.

If the locale of the user’s browser cannot be determined during authentication, the first message in the list is used.

If the message property is left blank, the text Yes is displayed to the user.

To remove a message, select its Delete icon ().

Negative answer

Specify a negative answer that will cause journey evaluation to continue along the False outcome path.

Click the Add button, and then enter the locale of the negative answer in the Key field, and the message to display to the user in the Value field.

If the locale of the user’s browser cannot be determined during authentication, the first message in the list is used.

If the message property is left blank, the text No will display to the end user.

To remove a message, select its Delete icon ().

Shared State Property Name

The name of the shared state variable.

Only Positive Answer

When enabled, the node displays only a single confirmation button containing the positive answer.

Note that this property only appears when the node is placed within a Page node.

Example

An example of the Message node presenting a yes/no question to the authenticating user.

Meter node

The Meter authentication node increments a specified metric key each time journey evaluation passes through the node.

Outcomes

Single outcome path.

Properties

Property Usage

Metric Key (required)

Specify the name of a metric to increment when journey evaluation passes through the node.

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 onto the Page node to combine them.

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.

Outcomes

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.

Properties

Property Usage

Page Header

Optional. Localized title for the page node and the nodes contained within it. Use this when components of an authentication flow need a title, such as breaking a registration into labelled sections.

Page Description

Optional. A localized description for the page node and the nodes contained within it. Use this when additional descriptive text is needed in an authentication flow.

Stage

Optional. An optional stage name to pass to the client to aid in rendering.

Submit Button Text

Optional. Use the Key and Value fields to set the text of the Submit button.

Theme

Optional. If using hosted pages, specify a theme to override this journey’s UI theme.

The Page node’s optional properties are passed in the response, but a self-hosted or custom UI needs to support these properties before they will be visible to the end user.

Example

The following example uses a Page node containing a Username Collector node, a Password Collector node, and a Choice Collector node:

Example journey showing Page node usage.
Figure 21. Example journey with Page node

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

User’s view of an example journey containing a page node.
Figure 22. User view of example journey with Page node

Polling Wait node

The Polling Wait authentication node pauses progress of the authentication journey 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 journey 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 "<session-cookie-name>=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://<tenant-env-fqdn>/am/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, refer to Authenticate using REST.

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

Outcomes

  • Done

  • Exited (configurable)

  • Spam (configurable)

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

Property Usage

Seconds To Wait

Specify the number of seconds to pause the authentication journey.

Default: 8

Enable Spam Detection

Specify whether to track the number of responses received during the wait time, and continue journey evaluation along the Spam outcome path if the number specified in the Spam Tolerance property is exceeded.

Default: Disabled

Spam Tolerance

Specify the number of responses to allow during the wait time before continuing journey evaluation along the Spam outcome path. This property only applies if spam detection is enabled.

Default: 3

Waiting Message

Specifies the optional message to display to the user.

You can provide the message in multiple languages by specifying the locale in the KEY field, for example en-US.

The locale selected for display is based on the user’s locale settings in their browser.

Messages provided in the node override the defaults provided by AM.

Exitable

Specify whether the user can exit the node during the wait period. Enabling this option adds a button with a configurable message to the page. Clicking the button causes journey evaluation to continue along the Exited outcome path.

Default: Disabled

Exit Message

Specifies the optional message to display to the user on the button used to exit the node before the wait period has elapsed. For example, Cancel or Lost phone? Use Recovery Code. This property only applies if the Exitable property is enabled.

You can provide the message in multiple languages by specifying the locale in the KEY field, for example en-US.

The locale selected for display is based on the user’s locale settings in their browser.

Messages provided in the node override the defaults provided by AM.

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 journey 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, refer to Configure authentication webhooks.

Outcomes

Single outcome path.

Properties

Property Usage

Webhook name

Specify the name of the webhook to register.

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

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 journey evaluation continues along the single outcome path.

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

Outcomes

Single outcome path.

Properties

Property Usage

Property Names (required)

Enter one or more key names of properties to remove from the session.

Retry Limit Decision node

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

Outcomes

  • Retry

  • Reject

Properties

Property Usage

Retry limit

Specify the number of times to allow a retry.

Default: 3

Save Retry Limit to User

Specify whether the number of failed login attempts persists between successful authentications. Possible values are:

  • Enabled. The node saves the number of failed login attempts to the user’s profile. New authentication journeys using the Retry Limit Decision node will use the stored value as the starting point for the retry limit.

    AM resets the count after the user authenticates successfully with a journey that contains this node.

    If AM cannot find the user’s profile, the authentication journey will end with an error.

  • Disabled. The node saves the number of failed login attempt in the journey’s nodeRetryLimitKey shared state property, which is discarded when the authentication session ends.

    For security reasons, ForgeRock recommends that you enable this setting.

Default: Enabled.

Example

The RetryLimit authentication journey with a Retry Limit Decision node
Figure 23. RetryLimit journey example

Scripted Decision node

The Scripted Decision authentication node allows execution of scripts during authentication. Journey 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.

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

All 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, refer to Scripted decision node API.

Outcomes

Configurable.

Properties

Property Usage

Script

Select the script to execute from the drop-down field. Click + to go to the script editor and create a new Journey Decision Node script. Click Edit Script to modify an existing Journey Decision Node script in the script editor.

Outcomes

Enter the possible strings that can be assigned to the outcome variable by the script. These strings provide the possible outcome paths the journey can continue along.

Script Inputs

A list of state inputs required by the script. Defaults to *.

Script Outputs

A list of state outputs produced by the script. Defaults to *.

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.

You can access session properties using a variable in a webhook. For more information, refer to Configuring Authentication Webhooks.

Outcomes

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

Properties

Property Usage

Properties

To add a session property, select the Add button, enter a key name and a value, and then select the plus icon. Repeat the steps to add multiple 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.

An example of OTP authentication with a State Metadata node.
Figure 24. Example journey with the State Metadata node

Outcomes

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

Properties

Property Usage

Attributes

Specify one or more shared state attribute names for return.

Success URL node

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

Specifying a success URL in a journey overrides any goto query string parameters.

For more information on how AM determines the redirection URL, and to configure the Validation Service to trust redirection URLs, refer to Configure success and failure redirection URLs.

The URL is also saved into the nodeState object for the successUrl key, which can be useful for custom node developers.

Properties

Property Usage

Success URL (required)

Specify the full URL to be redirected to when the authentication succeeds.

Timer Start node

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

Outcomes

Single outcome path.

Properties

Property Usage

Start Time Property

Specify a property name into which to store the current time. Specify the same value in any instances of the Timer Stop node that measure the time elapsed since journey evaluation passed through this node.

Timer Stop node

The Timer Stop authentication node records the time elapsed since journey evaluation passed through the specified Timer Start node in the specified metric name.

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 journey can also calculate the time elapsed since journey evaluation passed through the same Timer Start node.

Outcomes

Single outcome path.

Properties

Property Usage

Start Time Property

Specify the property name containing the time from which to calculate the elapsed time.

Metric Key (required)

Specify the name of a metric in which to store the calculated elapsed time.

Copyright © 2010-2022 ForgeRock, all rights reserved.