ForgeRock Identity Platform 7.2

Platform authentication nodes reference

This page includes the configuration reference for authentication nodes that can only be used in a platform environment.

For information about all the nodes that AM supports, see the Authentication node configuration reference in the [ref]ForgeRock Access Management documentation.

Accept Terms and Conditions node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

You set up Terms and Conditions in the Platform UI. For more information, see Terms & Conditions in the platform documentation.

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

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

Example Accept Terms and Conditions node Output.

Properties

This node has no configurable properties.

Example

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

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

An Example authentication tree, showing Accept Terms and Conditions node usage.
Figure 1. Example Tree 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 tree, such as collecting user information to populate a new account in a registration tree.

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

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

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

Properties

Property Usage

Attributes to Collect

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

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.

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.

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

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

Properties

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.

Identity Attribute

The attribute used to identify the object in IDM.

Attribute Value Decision node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

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

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

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

Properties

Property Usage

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.

Comparison Attribute

The object attribute to compare.

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.

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

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

Properties

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 auth tree flow, such as user registration.

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

Properties

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

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.

Properties

Property Usage

User Name

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

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.

Email Suspend node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

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

Properties

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.

Email Attribute

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

Email Suspend Message

The localized message to be returned once the tree 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 true, IDM is queried for an existing object. Otherwise, the object in the authentication tree’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.

Example

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

Authentication tree showing email suspend node usage during a forgotten password flow.
Figure 2. Email Suspend Tree

Email Template node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

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

Properties

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.

Email Attribute

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

Identity Attribute

The attribute used to identify the object in IDM.

Identify Existing User node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

Properties

Property Usage

Identifier

The attribute to collect from an IDM object.

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.

Example

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

Authentication tree showing identify existing user node usage during a forgotten password flow.
Figure 3. Identify Existing User Tree

Increment Login Count node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

Properties

Property Usage

Identity Attribute

The attribute used to identify the object in IDM.

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.

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

Properties

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 functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

This is used when creating or updating a user with Knowledge-Based Authentication enabled. For more information, see Security Questions.

Properties

Property Usage

Purpose Message

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

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 functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

Properties

Property Usage

KBA Attribute

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

Identity Attribute

The attribute used to identify the object in IDM.

Login Count Decision node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

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

Properties

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.

Amount

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

Identity Attribute

The attribute used to identify the object in IDM.

Page node

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

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

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

The Page node.

Properties

Property Usage

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.

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. This is used in UI development, to help identify what node or series of nodes are being returned so they can be rendered in the UI appropriately.

The Page node’s optional properties are passed in the response, but the 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, a password collector, and a choice collector:

Example tree showing Page node usage.

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

User’s view of an example tree containing a page node.

Pass-Through Authentication node

The Pass-Through 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.

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

Before you use the node:

  • Configure the connector to the third-party service.

    For details, see Connectors in the IDM documentation.

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

    For details, see Synchronization in the IDM documentation.

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.

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:

Pass-through authentication that updates user credentials.
Figure 4. Pass-Through Authentication

Patch Object node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

Properties

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 tree’s shared state that should be ignored as part of patch. If this is empty, all shared-state fields in the tree’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 tree.

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.

Identity Attribute

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

Platform Password node

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

Use this node instead of the Password Collector node when you have configured AM as part of a ForgeRock Identity Platform deployment.

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

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.

Platform Username node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

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.

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.

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

Properties

Property Usage

Profile Completeness Threshold

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.

Query Filter Decision node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

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

Properties

Property Usage

Query Filter

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.

Required Attributes Present node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

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.

It can also be configured to only show identity providers the user has already associated with their account, such as in account claiming flows, where a user wishes to associate a new social identity provider with an account that is being authenticated with social authentication.

The node has two possible outputs: social authentication, and local authentication. Local authentication can be turned off by disabling Include local authentication. In cases such as during account claiming, where the user has already authenticated once and is associating a new identity provider, the node will only display a local sign in option if it detects that the user’s account has a password attribute present.

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

Properties

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.

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 ForgeRock Identity Platform can use.

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.

Terms and Conditions Decision node

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

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

You set up Terms and Conditions in the Platform UI. For more information, see Terms & Conditions in the platform documentation.

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

Properties

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.

This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment.

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

This node is mainly used for Progressive Profile completion.

Properties

Property Usage

Elapsed Time

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.
Copyright © 2010-2024 ForgeRock, all rights reserved.