Authentication node reference
Basic nodes
Data Store Decision node
Verifies that the username and password values match those in the data store configured for the realm.
Alternative nodes
-
The LDAP Decision node supports LDAP Behera Password Policies, with separate outcomes for accounts that are locked or password that have expired.
Kerberos node
Enables desktop single sign-on such that a user who has already authenticated with a Kerberos Key Distribution Center can authenticate to AM without having to provide the login information again.
To achieve this, the user presents a Kerberos token to AM through the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) protocol.
End users may need to set up Integrated Windows Authentication in Internet Explorer or Microsoft Edge to benefit from single sign-on when logged on to a Windows desktop.
Outcomes
-
True
-
False
Evaluation continues along the True
path if Windows Desktop SSO is successful;
otherwise, evaluation continues along the False
path.
Properties
Property | Usage | ||
---|---|---|---|
Service Principal |
Specifies the Kerberos principal for authentication in the format In multi-instance AM deployments, configure AM-DOMAIN as the FQDN or IP address of the load balancer in front of the AM instances. For example, For more information, refer to the KB article How do I set up the WDSSO authentication module in AM in a load-balanced environment?. |
||
Key Tab File Path |
Specifies the full, absolute path of the keytab file for the specified Service Principal.
|
||
Kerberos Realm |
Specifies the name of the Kerberos (Active Directory) realm used for authentication. Must be specified in ALL CAPS. |
||
Kerberos Server Name |
Specifies the fully qualified domain name, or IP address of the Kerberos (Active Directory) server. |
||
Trusted Kerberos realms |
Specifies a list of trusted Kerberos realms for user Kerberos tickets. If realms are configured, then Kerberos tickets are only accepted if the realm part of the user principal name of the user’s Kerberos ticket matches a realm from the list. Each trusted Kerberos realm must be specified in all caps. |
||
Return Principal with Domain Name |
When enabled, AM returns the fully qualified name of the authenticated user rather than just the username. |
||
Lookup User In Realm |
Validates the user against the configured data stores.
If the user from the Kerberos token is not found, evaluation continues along the This search uses the |
||
Is Initiator |
When enabled ( When disabled ( |
LDAP Decision node
Verifies that the provided username and password values exist in a specified LDAP user data store, and checks whether they are expired or locked out.
For example, the username and password could be obtained by a combination of the Username Collector node and Password Collector node, or by using the Zero Page Login Collector node.
Outcomes
True
-
The credentials match those found in the LDAP user data store.
False
-
The credentials do not match those found in the LDAP user data store.
Locked
-
The profile associated with the provided credentials is locked.
Cancelled
-
The user must change their password. When the journey prompts the user to change their password, the user cancels the password change.
Expired
-
The profile is found, but the password has expired.
The LDAP Decision node requires specific user attributes in the LDAP user data store. These required attributes are present by default in ForgeRock Directory Services. If you are using an alternative identity store, you might need to modify your LDAP schema to use this node. |
Properties
Property | Usage |
---|---|
Primary LDAP Server (required) |
Specify one or more primary directory servers.
Specify each directory server in the following format: For example, |
Secondary LDAP Server |
Specify one or more secondary directory servers.
Specify each directory server in the following format: Secondary servers are used when none of the primary servers are available. For example, |
DN to Start User Search (required) |
Specify the DN from which to start the user search.
More specific DNs, such as 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 Multiple attribute values allow the user to authenticate with any one of the values.
For example, if you have both Note that if you have specified multiple attribute values,
you must also add those attributes to the |
User Search Filter |
Specifies an additional filter to append to user searches. For example, searching for |
Search Scope |
Specifies the extent of searching for users in the directory server. Scope Default: |
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: Default: |
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 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: |
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 Note that setting this property to Default: |
LDAP Connection Heartbeat Time Unit |
Specifies the time unit for Default: |
LDAP Operations Timeout |
Defines the timeout, in seconds, that AM should wait for a response from the directory server. Default: |
Use mixed case for password change messages |
Defines whether password change messages are returned in mixed (sentence) case or transformed to uppercase. By default password reset and password change messages are transformed to upper case. Enable this setting to return messages in sentence case. Default: Disabled |
Password Collector node
Prompts the user to enter their password.
The captured password is transient, persisting only until the authentication flow reaches the next node requiring user interaction.
Zero Page Login Collector node
Checks whether selected headers are provided in the incoming authentication request, and if so, uses their values as the provided username and password.
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.
For an example of this layout, refer to the default Example
authentication tree provided in AM.
The password collected by this node is transient, persisting only until the next node requiring user interaction.
Outcomes
-
Has Credentials
-
No Credentials
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.
Properties
Property | Usage | ||
---|---|---|---|
Username Header name |
Enter the name of the header that contains the username value. Default: |
||
Password Header name |
Enter the name of the header that contains the password value. Default: |
||
Allow without referer |
If enabled, the node accepts incoming requests that do not contain a If disabled, a Default: |
||
Referer Whitelist |
Specify a list of URLs allowed in the
|
Multi-factor nodes
Get Authenticator App node
Displays information to obtain an authenticator application from the Apple App Store or the Google Play Store.
Use the following variables to customize the message:
-
{{appleLink}}
-
{{appleLabel}}
-
{{googleLink}}
-
{{googleLabel}}
You can also include HTML elements, for example:
Apple: <a target='_blank' href='{{appleLink}}'>{{appleLabel}}</a>
Properties
Property | Usage |
---|---|
Get App Authenticator Message |
Localized title for the node.
The key is the language, such as Default: |
Continue Label |
Localized text to use on the Continue button.
The key is the language, such as |
Apple App Store URL |
Specifies the URL to download your authenticator application from the Apple App Store. The default value points to the ForgeRock Authenticator application for iOS. |
Google Play URL |
Specifies the URL to download your authenticator application from the Google Play Store. The default value points to the ForgeRock Authenticator application for Android. |
HOTP Generator node
Creates a string of random digits of the specified length for use as a one-time password.
Passwords are stored in the oneTimePassword
transient node state property.
Use this node with these nodes to add one-time password verification as an additional factor:
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 and the type of MFA device. For example, you can use a Username Collector node and a Push Sender node earlier in the flow to obtain these.
Outcomes
-
Register
-
Get App
(configurable) -
Skip
(configurable) -
Opt-out
(configurable)
Evaluation continues along the outcome the user selects.
Properties
Property | Usage |
---|---|
Remove 'skip' option |
If checked, users can no longer skip the node 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 |
Register Device |
Localized text to use on the Register Device button. The key is the language, such as |
Get Authenticator App |
Localized text to use on the Get Authenticator App button. The key is the language, such as |
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 |
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 this node does not change the user’s profile. Connect the Opt-out outcome to an Opt-out Multi-Factor Authentication node to persist the option in the user’s profile. The key is the language, such as |
Example
Refer to the Push authentication example journey for how to use the MFA Registration Options node in a journey handling push devices.
OATH Device Storage node
The OATH Device Storage node stores devices in the user profile after an OATH Registration node records them in the shared state.
Compatibility
Product | Compatible? |
---|---|
ForgeRock Identity Cloud |
Yes |
ForgeRock Access Management (self-managed) |
Yes |
ForgeRock Identity Platform (self-managed) |
Yes |
Authenticators
The OATH-related nodes can integrate with the following authenticator apps:
-
The ForgeRock Authenticator app for Android and iOS.
-
Third-party authenticator apps that support the following open standards:
Inputs
This node reads the device profile as the value of the shared state attribute oathDeviceProfile
.
Dependencies
Precede this node in the flow with an OATH Registration node with its Store device data in shared state setting enabled.
Errors
This node logs a No device profile found on shared state
error message
if it can’t get the device profile from the oathDeviceProfile
shared state attribute.
Example
The following journey includes both username-password and one-time passcode authentication:
-
The Page node with the Platform Username node and the Platform Password node prompts for the user credentials.
-
The Data Store Decision node confirms the username-password credentials.
-
The first OATH Token Verifier node prompts for a one-time passcode with an option to use a recovery code.
-
The OATH Registration node prompts the user to register a device and includes its profile in the shared state.
-
The Recovery Code Display node shows the recovery codes and prompts the user to keep them safe.
-
The second OATH Token Verifier node prompts for a one-time passcode using the newly registered device.
-
The OATH Device Storage node writes the device profile to the user’s account.
-
The Recovery Code Collector Decision node prompts for a recovery code.
-
The Retry Limit Decision node lets the user retry another code if they enter one incorrectly.
OATH Registration node
Lets the user register a device for OATH-based multi-factor authentication (MFA).
Based on the node settings, 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, and 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 with OTP verification.
You can use the OATH nodes in conjunction with the ForgeRock Authenticator application to register your phone, receive notifications, or generate one-time passwords. |
Refer to the OATH Token Verifier node example that demonstrates how use to use other MFA nodes to create a complete OATH authentication journey.
Outcomes
-
Success
-
Failure
If registration is successful and the device details are stored, 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 authenticator application displays the value. |
||
Account Name |
Define the profile attribute to display as the username in the authenticator application. If not specified, or if the specified profile attribute is empty, their username is used. |
||
Background Color |
The background color in hex notation that displays behind the issuer’s logo within the authenticator application. |
||
Logo Image URL |
The location of an image to download and display as the issuer’s logo within the authenticator application.
|
||
Generate Recovery Codes |
If enabled, recovery codes are generated and stored in the successful 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 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:
If this is set to HOTP, 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 is generated every 30 seconds and is valid for 30 seconds only. The default value is 30. |
||
TOTP Hash Algorithm |
The HMAC hash algorithm 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. Only set this if the user devices support it. |
||
HOTP Truncation Offset |
This is an option used by the HOTP algorithm that not all devices support. Leave the default value of -1 unless you know user devices use 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 |
||
Store device data in shared state |
If enabled, the device is not stored directly in the user profile upon successful completion of the node.
Instead, the device information is added into the shared node state on 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.
You can also use them with other MFA nodes such as the following to extend these capabilities:
You can use the OATH nodes in conjunction with the ForgeRock Authenticator application to register your phone, receive notifications, or generate one-time passwords. |
Outcomes
Evaluation continues along one of the following outcome paths:
Success
-
There is a registered device and the token code is verified.
Failure
-
The user is not authenticated, or the collected token code cannot be verified.
Not registered
-
There is no registered device for the user.
Properties
Property | Usage |
---|---|
OATH Algorithm |
Specify the algorithm your device uses to generate the OTP:
If this is set 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 accepts 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 is generated every 30 seconds, and is 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 permits 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 can be out of sync with the server before manual resynchronization is required. For example, with 3 allowed drifts and a time step interval of 30 seconds, the server allows 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 is 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. |
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, and the type of MFA device. For example, you can use a Username Collector node and a Push Sender node earlier in the flow to obtain these.
OTP Collector Decision node
Requests and verifies one-time passwords.
OTP Email Sender node
Sends an email containing a generated one-time password to the user.
Send mail requests time out after 10 seconds.
You can change the timeout in the following advanced server properties:
How Do I Configure Advanced Server Properties?
If the property you want to add or edit is already configured, click on the pencil () button to edit it. When you are finished, click on the tick () button. Save your changes. For more information, refer to Advanced Properties. |
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 for SSL/TLS, 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: |
The subject of the email |
Click Add to add a new email subject. Enter the locale, such as |
The content of the email |
Click Add to add the content of the email. Enter the locale, such as |
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:
Default: |
Gateway Implementation Class |
Specifies the class the node uses to send SMS and email messages.
A custom class must implement the Default: |
OTP SMS Sender 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
.
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 for SSL/TLS, 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: |
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, such as |
The content of the message |
Click Add to add the content of the message. Enter the locale, such as |
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:
Default: |
Gateway Implementation Class |
Specifies the class the node uses to send SMS and email messages.
A custom class must implement the Default: |
Push Registration 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 Username Collector 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, evaluation continues along the Success
outcome path.
If the node does not receive a response from the user’s 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,
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 application: For example, |
||
Account Name |
Specifies the profile attribute to display as the username in the authenticator application. 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, evaluation continues along the |
||
Background Color |
Specifies the background color, in hex notation, to display behind the issuer’s logo within the ForgeRock Authenticator application. |
||
Logo Image URL |
Specifies the location of an image to download and display as the issuer’s logo in the ForgeRock Authenticator application. |
||
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.
|
||
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, |
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
Works 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 For information on creating or customizing authentication nodes, refer to Node development. |
Outcomes
-
Success
-
Failure
-
Expired
-
Waiting
Evaluation continues along the Success
outcome path if the push notification was approved by the user.
Evaluation continues along the Failure
outcome path if the push notification was rejected by the user.
If no response to the push notification was received
within the Message Timeout value specified in the Push Sender node,
evaluation continues along the Expired
outcome path.
If no response to the push notification has been received yet,
evaluation continues along the Waiting
outcome path.
Push Sender node
Sends push notification messages to a device for multi-factor authentication.
Configure the AM Push Notification Service for the realm before using this node. 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 flow must have included the username in the shared state, for example, by using a Username Collector node.
Outcomes
-
Sent
-
Not Registered
-
Skipped
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, evaluation continues along the Not Registered
outcome path.
If the user chooses to skip push authentication, 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 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. For information about customizing and translating the default messages, refer to Internationalization. The following variables can be used in the
Example: |
||
Remove 'skip' option |
Enable this option in the node to make the push authentication mandatory. When disabled, the user can skip the push authentication requested by the node,
and evaluation continues along the Default: Disabled
|
||
Share Context info |
If enabled, context data such as For example:
For the location attribute to be set, the flow must contain a Device Profile Collector node with Collect Device Location 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 3 Kb or a 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:
|
Example
The following example shows one possible implementation of multi-factor push authentication:
Node connections
Source node | Outcome path | Target node |
---|---|---|
Page Node containing: Username Collector, Password Collector |
→ |
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 |
After verifying the user’s credentials, evaluation continues to the Push Sender node.
If the user has a registered device:
-
AM sends a push to their registered device.
-
The Push Wait node pauses authentication 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 positively, they are authenticated successfully and logged in.
-
If the user responds negatively, they are not authenticated successfully and do not receive a session.
-
If the push notification expires, AM sends a new push notification.
Use a Retry Limit Decision node to constrain the number of times a new code is sent. -
If the user has not yet responded, the flow loops back a step and the Push Wait node pauses authentication for another 5 seconds.
If the user exits the Push Wait node, they can enter a recovery code in order to authenticate.
For this situation, configure the Exit Message property in the Push Wait node with a message, such as
Lost phone? Use a recovery code
. -
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:
-
The MFA Registration Options node presents the user with the following options:
- Register Device
-
The flow continues to the Push Registration node, which displays the QR code that should be scanned with a suitable authenticator application.
- Get the App
-
The flow continues to the Get Authenticator App node, which displays the links needed to obtain a suitable application, such as the ForgeRock Authenticator.
- Skip this step
-
Displayed only if the node configuration lets the user skip. In this example, 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. Evaluation continues to the Opt-out Multi-Factor Authentication node, which updates the user’s profile to skip MFA with push in the future. In this example, after updating the profile the flow continues to the Success node.
-
The user registers the device with the Push Registration node.
After registration, the recovery codes are displayed to the user for safekeeping, and evaluation continues with the Push Sender node to start push notification.
To manage push devices, the user must log in using either the device or a recovery code. For more information, refer to Manage devices for MFA. |
Push Wait node
Pauses the authentication for the specified number of seconds during the processing of a push authentication request.
When push authentication 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 this node to a Push Result Verifier node to check the result of the code challenge.
Both nodes' waiting times and the messages 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.
For information about customizing and translating the default messages, refer to Internationalization.
Outcomes
-
Done
-
Exit
Evaluation continues along the Done
outcome path after the wait time has passed.
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 authentication. Default: |
Waiting Message |
Customize the message to display to the user. To include the remaining seconds in the message,
use the Click Add to enter a KEY and VALUE for a localized message and + to save. Repeat for each supported language. Default: |
Push Challenge Message |
Customize the message containing the challenge code. To include the number challenge,
use the Click Add to enter a KEY and VALUE for a localized message and + to save. Repeat for each supported language. Default: |
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: |
Example
Refer to the Push authentication example journey for how to use the Push Wait node in a journey handling push devices.
Recovery Code Collector Decision node
Lets users authenticate with a recovery code provided when registering a device for multi-factor authentication.
Use this node for a flow that includes push notifications or one-time passwords. When the user loses their registered device, they can use a recovery code as 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
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 shared state must include the username.
You can obtain this using a
Username Collector node.
If the recovery code does not match, or a username has not been acquired,
evaluation continues along the False
outcome path.
Recovery Code Display node
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.
Use this node with the WebAuthn Registration node, the OATH Registration node or the Push Registration node.
Generated recovery codes are inserted into transient state
when evaluation continues along the Success
outcome path of the MFA nodes configured to generate recovery codes.
Connect this node to the Success
outcome path to display the codes.
If no recovery codes are available in transient state, 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. This node is the one and only opportunity to view and save the recovery codes. |
WebAuthn Authentication node
Lets users on supported clients use a registered FIDO device during authentication.
To determine whether the user has a registered device, the shared node state must a username. You can use a Username Collector node for this.
Outcomes
-
Unsupported
-
No Device Registered
-
Success
-
Failure
-
Client Error
-
Recovery Code
(configurable)
If the user’s client does not support web authentication,
evaluation continue along the Unsupported
outcome path.
For example, clients connected over the HTTP protocol rather than HTTPS do not support WebAuthn; however,
HTTPS may not be required when testing locally, on http://localhost
.
For more information, refer to
Is origin potentially trustworthy?.
If the user does not have a registered device, evaluation continues along the No Device Registered
outcome path.
If AM encounters an issue when attempting to authenticate using the device,
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, 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 |
If Allow recovery code is enabled,
AM provides the user the option to enter a recovery code rather than authenticate using a device.
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, evaluation continues along the Success
outcome path.
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, 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:
|
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 |
Timeout |
Specify the number of seconds to wait for a response from an authenticator. If the specified time is reached, evaluation continues along the |
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 fails and evaluation continues along the 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. |
Example
This example shows one possible implementation of the flow for authenticating with WebAuthn devices:
After verifying the users credentials against the configured data store, evaluation continues to the WebAuthn Authentication node.
If the user’s client does not support WebAuthn, authentication 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 flow that lets the user register a device. This stage could also be an Inner Tree Evaluator node.
If the user’s client does support WebAuthn, and the connection is secured with TLS, the user is prompted to complete an authorization gesture, for example, scanning a fingerprint, or entering a PIN:
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 requesting access. |
The authenticators the client activates for authentication depends on 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 the response from an authenticator
matches the criteria configured for the node, and will reject—with the Failure
outcome—an authentication attempt
by an inappropriate authenticator type.
When the user completes an authorization gesture, for example,
by scanning a fingerprint or entering a PIN, 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, 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 authentication lead to the Failure
outcome,
including a timeout, or to the Client Error
outcome, resulting in an authentication failure.
WebAuthn Device Storage node
Writes information about FIDO2 devices to a user’s profile. The user can subsequently authenticate using the device.
Use this node to store the device data the WebAuthn Registration node places into the transient node state when its Store device data in transient state property is enabled.
Outcomes
-
Success
-
Failure
-
Exceed Device Limit
If AM encounters an issue when attempting to save the device data to the user’s profile;
for example, the user was not identified earlier, then evaluation continues along the Failure
outcome path.
If the Maximum Saved Devices property is set to an integer greater than zero, and registering a new device would take the number of devices above the specified threshold, then evaluation continues down the Exceed Device Limit
outcome path. In this case, you may need to instruct your users to log in with an existing device in order to remove one or more of their registered devices.
If the node successfully stores the device data to the user’s profile,
evaluation continues along the Success
outcome path.
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 transient node state, and stored alongside the device profile. Use the Recovery Code Display node to display the codes to the user for safe keeping.
|
||
Maximum Saved Devices |
Specify the maximum number of WebAuthn devices to save in a user’s profile. Set this property to When this property is greater than zero, the |
WebAuthn Registration node
Lets users of supported clients register FIDO2 devices for use during authentication.
AM interacts with FIDO2/WebAuthn capable browsers, such as Chrome
, Firefox
and Microsoft Edge
.
These browsers interact with CTAP2 authenticators, including U2F and FIDO2 Security Keys,
and platforms, such as Windows Hello or Apple Touch ID.
Outcomes
-
Unsupported
-
Success
-
Failure
-
Client Error
-
Exceed Device Limit
If the user’s client does not support WebAuthn, evaluation continues 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,
evaluation continues along the Failure
outcome path.
For example, AM could not verify
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 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 |
If the Maximum Saved Devices property is set to an integer greater than zero, and registering a new device would take the number of devices above the specified threshold, then evaluation continues down the Exceed Device Limit
outcome path. In this case, you may need to instruct your users to log in with an existing device in order to remove one or more of their registered devices.
If the user successfully registers an authenticator of the correct type as determined by the node’s properties,
evaluation continues along the Success
outcome path.
Properties
Property | Usage | ||
---|---|---|---|
Relying party |
Specify the name of the relying party entity registering and authenticating users by using WebAuthn. For example, |
||
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, such as 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:
|
||
Preferred mode of attestation |
Specifies whether AM requires that the authenticator provides attestation statements. The available options are:
AM supports the following attestation formats:
|
||
Accepted signing algorithms |
Specify the algorithms 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 attachments:
The available options are:
|
||
Trust Store alias |
Specifies the name of a secret store configured in the realm that contains CA-issued certificate chains, which can be used to verify attestation data provided by a device. 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 The value is also appended to the string |
||
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, evaluation continues along the |
||
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 property and are not saving the device data to the user’s profile immediately, do not enable the Generate recovery codes property in this node, but in the WebAuthn Device Storage node instead.
|
||
Store data in transient state |
Specify whether the information provided by the device to the node is stored
in the transient node state for later analysis by subsequent nodes, using the key In addition to the information provided by the device, the type of attestation achieved;
for example,
|
||
Store device data in transient state |
Specify whether the information about the device required for WebAuthn is stored in the transient node 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.
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 shared node 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 username 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 Devices |
Specifies the maximum number of WebAuthn devices stored in the user’s profile. Set this property to When this property is greater than zero, the
|
Example
The following example registers WebAuthn devices:
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, AM prompts the user to register 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 requesting access. |
The authenticators the client activates for registration depend on 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,
by scanning a fingerprint or entering a PIN,
the 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 click Rename.
Any problems encountered during the registration, including a timeout,
results in the evaluation continuing to the Failure
outcome.
Risk management nodes
Account Active Decision node
Checks whether the current account is active.
This node relies on the shared node state to determine which account to check.
Use this node, for example, 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 trees.
Account Lockout node
Locks or unlocks the authenticating user’s account profile.
For more information, refer to Account lockout for trees.
Properties
Property | Usage |
---|---|
Lock Action |
Choose whether to The Data Store Decision node checks whether the account is locked. |
Example
The following example uses this node with the Retry Limit Decision node to lock an account after a number of invalid attempts:
Auth Level Decision node
Compares the current authentication level value against a configured value.
CAPTCHA node
Adds CAPTCHA support.
This node verifies the response token received from the CAPTCHA provider and creates a CAPTCHA callback for the UI to interact with.
By default, the node is configured for Google’s reCAPTCHA v2.
Properties
Property | Usage |
---|---|
CAPTCHA Site Key (required) |
The CAPTCHA site key supplied by the CAPTCHA provider when you sign up for access to the API. |
CAPTCHA Secret Key (required) |
The CAPTCHA secret key supplied by the CAPTCHA provider when you sign up for access to the API. |
CAPTCHA Verification URL (required) |
The URL used to verify the CAPTCHA submission. Possible values are:
|
CAPTCHA API URL (required) |
The URL of the JavaScript that loads the CAPTCHA widget. Possible values are:
|
Class of CAPTCHA HTML Element |
The class of the HTML element required by the CAPTCHA widget. Possible values are:
|
ReCaptcha V3 node |
If you’re using Google reCAPTCHA, specify 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. The CAPTCHA provider returns a score for each user request, based on observed interaction with your site. CAPTCHA "learns" 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 the CAPTCHA provider. Start with a threshold of 0.5. For more information about score thresholds, refer to the Google documentation. |
Legacy CAPTCHA node
Verifies the response token received from the CAPTCHA verifier, and creates 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. |
Properties
Property | Usage |
---|---|
CAPTCHA Site Key (required) |
The CAPTCHA site key supplied by the CAPTCHA provider when you sign up for access to the API. |
CAPTCHA Secret Key (required) |
The CAPTCHA secret key supplied by the CAPTCHA provider when you sign up for access to the API. |
CAPTCHA Verification URL (required) |
The URL used to verify the CAPTCHA submission. Possible values are:
|
CAPTCHA API URL (required) |
The URL of the JavaScript that loads the CAPTCHA widget. Possible values are:
|
Class of CAPTCHA HTML Element |
The class of the HTML element required by the CAPTCHA widget. Possible values are:
|
Behavioral nodes
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 with the Login Count Decision node. To track the number of logins, include this node in the login authentication flows.
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. |
Add the Increment Login Count node to your login flows, so this node has the data to trigger a decision.
Properties
Property | Usage |
---|---|
Interval |
The type of interval the decision should trigger on. To trigger the action once when the user reaches the number of successful login attempts,
set Interval to To trigger the action on every login attempt after the user reaches the number of successful login attempts,
set Interval to |
Amount |
The amount (count) of logins the interval should trigger on. |
Identity Attribute |
The attribute used to identify the object in IDM. |
Contextual nodes
Certificate Collector node
Collects an X.509 digital certificate from the request to use the certificate as authentication credentials.
To validate the certificate, use a Certificate Validation node.
Outcomes
-
Collected
-
Not Collected
Evaluation continues through the Collected
path if certificate collection is successful;
otherwise, evaluation continues on the Not Collected
path.
Properties
Property | Usage |
---|---|
Certificate Collection Method |
Specifies how to collect the certificate from the request. Possible values are:
Default: |
HTTP Header Name for the Client Certificate |
Specifies the name of the HTTP header containing the certificate
when the Certificate Collection Method property is configured to Default: No value specified. |
Trusted Remote Hosts |
Specifies a list of IP addresses trusted to supply certificates on behalf of the authenticating client, such as load balancers doing TLS termination. If no value is specified, AM rejects certificates supplied by remote hosts.
If you specify the Default: No value specified. |
Certificate User Extractor node
Extracts a value from the certificate collected by the Certificate Collector node, and searches for it in the identity store. The goal is to match the certificate with a user in the identity store.
The extracted value is stored in the username
key in the shared node state.
Outcomes
-
Extracted
-
Not Extracted
Evaluation continues through the Extracted
path if AM finds a match for the certificate in the identity store;
otherwise, evaluation continues on the Not Extracted
path.
Properties
Property | Usage |
---|---|
Certificate Field Used to Access User Profile |
Specifies the field in the certificate that AM uses to search for the user in the identity store. Possible values are:
If you select Select Default: |
Other Certificate Field Used to Access User Profile |
Specifies a custom certificate field to use as the base of the user search. |
SubjectAltNameExt Value Type to Access User Profile |
Specifies how to look up the user profile:
Default: |
Certificate Validation node
Validates a digital X.509 certificate collected by the Certificate Collector node.
Outcomes
True
-
The node could validate the certificate.
When the outcome is
True
, add a Certificate User Extractor node to extract the values of the certificate. False
-
The node could not validate the certificate. The node will use this path when it cannot validate the certificate, and no more specific outcome is available.
Not found
-
The Match Certificate in LDAP property is enabled, but the certificate was not found in the LDAP store.
Expired
-
The Check Certificate Expiration property is enabled, and the certificate has expired.
Path Validation Failed
-
The Match Certificate to CRL property is enabled, and the certificate path is invalid.
Revoked
-
The OCSP Validation property is enabled, and the certificate has been revoked.
Properties
Property | Usage |
---|---|
Match Certificate in LDAP |
When enabled, AM matches the certificate collected with the one stored in an LDAP directory entry. This entry and additional security-related properties are defined later in the node. Default: Disabled |
Check Certificate Expiration |
When enabled, AM checks whether the certificate has expired. Default: Disabled |
Subject DN Attribute Used to Search LDAP for Certificates |
Specifies the attribute that AM uses to search the LDAP directory for the certificate. The search filter also uses the value of the Subject DN as it appears in the certificate. Default: |
Match Certificate to CRL |
When enabled, AM checks whether the certificate has been revoked according to a CRL in the LDAP directory. Related properties are defined later in the node. Default: Disabled. |
Issuer DN Attribute(s) Used to Search LDAP for CRLs |
Specifies which attribute and value in the certificate Issuer DN AM uses to find the CRL in the LDAP directory. If only one attribute is specified, the LDAP search filter used is For example, if the subject DN of the issuer certificate is Specify several CLRs for the same CA issuer in a comma-separated list (,) where the names are in the same order as they occur in the subject DN. In this case, the LDAP search filter used
is For example, if the subject DN of the issuer certificate is Default: |
HTTP Parameters for CRL Update |
Specifies parameters that AM includes in any HTTP CRL call to the CA that issued the certificate. If the client or CA contains the Issuing Distribution Point Extension, AM uses this information to retrieve the CRL from the distribution point. Add the parameters as key pairs of values in a comma-separated list (,).
For example, |
Cache CRLs in Memory |
(LDAP distribution points only) When enabled, AM caches CRLs. Default: Enabled |
Update CA CRLs from CRLDistributionPoint |
When enabled, AM updates the CRLs stored in the LDAP directory store
if the CA certificate includes either the Default: Enabled |
OCSP Validation |
When enabled, AM checks the revocation status of certificates using the Online Certificate Status Protocol (OCSP). The AM instance must have internet access, and you must configure OSCP for AM under Configure > Server Defaults > Security > Online Certificate Status Protocol Check. Default: Disabled |
LDAP Server Where Certificates are Stored |
Specifies the LDAP server that holds the certificates.
Enter each server in the AM servers can be associated with LDAP servers by writing multiple chains
with the format To configure a secure connection, enable the Use SSL/TLS for LDAP Access property. |
LDAP Search Start or Base DN |
Valid base DN for the LDAP search, such as |
LDAP Server Authentication User |
Specifies the DN of the service account that AM uses
to authenticate to the LDAP directory that holds the certificates.
For example, Default: |
LDAP Server Authentication Password |
Specifies the password of the user configured in the LDAP Server Authentication User property. |
Use SSL/TLS for LDAP Access |
Specifies whether AM should use SSL/TLS to access the LDAP. When enabled, AM must be able to trust the LDAP server certificate. Default: Disabled |
Example
The following is an example of how to use the certificate nodes. Note that all the failure outcomes of the Certificate Validation node are linked so that the user provides a username and password, but you could choose different authentication methods for each outcome:
Cookie Presence Decision node
Checks that a named cookie is present in the incoming authentication request.
This node does not check the value of the named cookie, only that it exists.
Device Geofencing node
Compares any collected device location metadata with the trusted locations configured in the authentication node.
Use this node with the Device Profile Collector node to determine if the authenticating user’s device is located within range of configured, trusted locations.
Outcomes
-
Inside
-
Outside
Evaluation continues along the Inside
path if the collected location
is within the specified range of a configured trusted location;
otherwise, evaluation continues along the Outside
path.
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, |
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
Compares any collected device location metadata with that stored in the user’s profile.
Use this node with 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 before attempting to match locations.
Outcomes
-
True
-
False
-
Unknown Device
Evaluation continues along the True
path if the collected location
is within the specified range of saved location data;
otherwise, evaluation continues along the False
path.
If the user has no saved device profiles, or the identity of the user has not been established,
evaluation continues along the Unknown Device
path.
Device Match node
Compares any collected device metadata with that stored in the user’s profile.
Use this node with 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 to compare captured device data against trusted device profiles.
AM includes a template script you can customize to your requirements. In the AM admin UI, go to Realms > Realm Name > Scripts, and click Device Match Template - Decision node Script.
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 before attempting to match device profiles.
Outcomes
-
True
-
False
-
Unknown Device
Evaluation continues along the True
path if the collected device profile matches a saved profile,
within the configured variance; otherwise, evaluation continues along the False
path.
If the user has no trusted device profiles, or the identity of the user has not been established,
evaluation continues along the Unknown Device
path.
Properties
Property | Usage | ||
---|---|---|---|
Acceptable Variance |
Specify the maximum amount of device attribute differences 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 saved to the user’s profile before this time will not be compared to the collected metadata. |
||
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
Default: |
||
Custom Matching Script |
Specifies the custom script to use if the Use Custom Matching Script property is enabled. Only scripts of type
|
Device Profile Collector node
Gathers metadata about the device used to authenticate.
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 shared state in a variable named
forgeRock.device.profile
. - 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 shared state in a variable named
forgeRock.device.location
.The collection of geographical information requires end-user approval. A browser function drives this process. A pop-up displays, prompting for access to share the geographical location. The browser connection must be secure.
It is up to you what information you collect from users and devices. Always use data responsibly and provide your users with 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 to create a trusted profile from the collected data. You can use the trusted device profile in subsequent authentication attempts; for example, with the Device Match node and Device Location Match node.
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: |
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 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
Persists collected device data to a user’s profile in the identity store.
Use this node with the Device Profile Collector node to reuse the collected data in future authentications; for example, with the Device Match node and Device Location Match node.
You must establish the identity of the user 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 Access Management UI does not display saved device profiles to end users.
You can manage device profiles over REST, by using the /json/users/user/devices/profile
endpoint for the realm.
Use the AM API Explorer for detailed information about the parameters
supported by the /devices/profile
endpoint, and to test it against your deployed AM instance.
In the AM admin UI, select the Help icon, and then go to API Explorer > /users > /{user} > /devices > /profile.
Properties
Property | Usage |
---|---|
Device Name Variable |
Specifies the name of a variable in the shared node 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 profile replaces the least-recently used profile. |
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
Specifies a threshold for deciding if the device has been tampered with; for example, if it has been rooted or jailbroken.
The device scores between zero and one,
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 with the Device Profile Collector node to retrieve the tampering score from the device.
Outcomes
-
Not Tampered
-
Tampered
Evaluation continues along the Not Tampered
path if the device scores less than or equal to the configured threshold;
otherwise, 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 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; |
Persistent Cookie Decision node
Checks for the existence of a specified persistent cookie, the default being session-jwt
.
If the cookie is present, the node verifies the signature of the JWT stored in the cookie with the signing key specified in the HMAC signing key property.
If the signature is valid, the node decrypts the payload of the JWT. It uses the key pair specified in the Persistent Cookie Encryption Certificate Alias property, found in the AM admin UI under Realms > Realm Name > Authentication > Settings > Security. The global level is found under Configure > Authentication > Core Attributes > Security.
The decrypted JSON payload includes information, such as the UID of the identity and the client IP address. Enable Enforce Client IP to verify that the current IP address and the client IP address in the cookie are identical.
This node recreates the received persistent cookie, updating the value for the idle time property. Cookie creation properties for the Set Persistent Cookie node are therefore available in this node as well. |
Outcomes
-
True
-
False
Evaluation continues along the True
outcome path
if the persistent cookie is present and all the verification checks above are satisfied;
otherwise, 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 If the |
||
Use HTTP Only Cookie |
When enabled, adds the When the |
||
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 generate an HMAC signing key, run one of the following commands:
or
|
||
Persistent cookie name |
Specifies the name of the persistent cookie to check. |
Set Custom Cookie node
Store an additional custom cookie on the client.
This 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.
You can use this node 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 node state.
Include all the attributes in the configuration provider script’s config
map.
The following example sets the attributes of the custom cookie to static values:
config = {
"name": "testname",
"value": "testvalue",
"maxAge": "60",
"domain": "am.example.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
:
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 |
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 If omitted, the cookie expires 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 |
Sets the domain that the custom cookie will be sent to. |
Custom Cookie Path |
Sets the path of the custom cookie. |
Use Secure Cookie |
When enabled, adds the If the |
Use HTTP Only Cookie |
When enabled, adds the When the |
Custom Cookie SameSite attribute |
Sets the The default value is Learn more in SameSite cookie rules. |
Set Persistent Cookie node
Creates the specified persistent cookie, the default being session-jwt
.
The cookie contains a JWT with a JSON payload including information such as the UID of the identity, and the client IP address.
The node encrypts the payload of the JWT. It uses the key pair specified in the Persistent Cookie Encryption Certificate Alias property, found in the AM admin UI under Realms > Realm Name > Authentication > Settings > Security. The global level is found under Configure > Authentication > Core Attributes > Security.
The node signs the cookie with the signing key specified in the HMAC signing key property. Any node that reads the persistent cookie must be configured with the same HMAC signing key.
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 before the timeout, the cookie is no longer valid. |
||
Max life |
Specifies the length of time the persistent cookie remains valid, in hours. After this time has passed, the cookie is no longer valid. |
||
Use Secure Cookie |
When enabled, adds the If the |
||
Use HTTP Only Cookie |
When enabled, adds the When the |
||
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 generate an HMAC signing key, run one of the following commands:
or
|
||
Persistent Cookie Name |
Specifies the name used for the persistent cookie. |
Federation nodes
OAuth 2.0 node
Lets AM authenticate users of OAuth 2.0-compliant resource servers.
References in this section are to RFC 6749, The OAuth 2.0 Authorization Framework.
This node and its related services, are deprecated. For information about the legacy/deprecated social authentication node and module implementations, refer to Social authentication in the ForgeRock Access Management 7 Authentication and Single Sign-On Guide. |
Outcomes
-
Account Exists
-
No account Exists
Evaluation continues along the Account Exists
path if an account
matching the attributes retrieved from the social identity provider is found in the user data store;
otherwise, evaluation continues along the No account exists
path.
Properties
Property | Usage | ||
---|---|---|---|
Client ID (required) |
Specifies the |
||
Client Secret (required) |
Specifies the |
||
Authentication Endpoint URL (required) |
Specifies the URL to the social provider’s endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749). Example: |
||
Access Token Endpoint URL (required) |
Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749). Example: |
||
User Profile Service URL (required) |
Specifies the user profile URL that returns profile information. Example: |
||
OAuth Scope (required) |
Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). Ensure you use the correct scope delimiter required by the identity provider, including commas or spaces. The list depends on the permissions that the resource owner, such as the end user, grants to the client application. |
||
Scope Delimiter (required) |
Specifies the delimiter used to separate scope values. Some authorization servers use non-standard separators for scopes, for example commas. |
||
Redirect URL (required) |
Specifies the URL the user is redirected to by the social identity provider after authenticating. For authentication trees in AM, set this property to the URL of the UI.
For example, |
||
Social Provider (required) |
Specifies the name of the social provider for which this module is being set up. Example: |
||
Auth ID Key (required) |
Specifies the attribute the social identity provider uses to identify an authenticated individual. Example: |
||
Use Basic Auth |
Specifies that the client uses HTTP Basic authentication when authenticating to the social provider. Default: |
||
Account Provider (required) |
Specifies the name of the class that implements the account provider. Default: |
||
Account Mapper (required) |
Specifies the name of the class that implements the method of locating local accounts based on the attributes returned from the social identity provider. Provided implementations are:
The Account Mapper classes can take two constructor parameters:
For example, to prefix all received property values with org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook- |
||
Attribute Mapper (required) |
Specifies the list of fully qualified class names for implementations that map attributes from the OAuth 2.0 authorization server to AM profile attributes. Provided implementations are:
The Attribute Mapper classes can take two constructor parameters to help differentiate between the providers:
For example, to prefix all incoming values with org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook- To prefix all incoming values use an asterisk ( |
||
Account Mapper Configuration |
Specifies the attribute configuration used to map the account of the user authenticated in the OAuth 2.0 provider to the local data store in AM. Valid values are in the form Examples: email=mail id=facebook-id
|
||
Attribute Mapper Configuration |
Map of OAuth 2.0 provider user account attributes to local user profile attributes,
with values in the form Examples: first_name=givenname last_name=sn name=cn email=mail id=facebook-id first_name=facebook-fname last_name=facebook-lname email=facebook-email
|
||
Save attributes in the session |
When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session. |
||
OAuth 2.0 Mix-Up Mitigation Enabled |
Controls whether the OAuth 2.0 authentication node carries out additional verification steps when it receives the authorization code from the authorization server. Specifies that the client must compare the issuer identifier of the authorization server
upon registration with the issuer value returned as the When this is enabled, set the Token Issuer property so that the validation can succeed.
The authorization code response contains an issuer value (
For more information, refer to section 4 of OAuth 2.0 Mix-Up Mitigation Draft. |
||
Token Issuer |
Corresponds to the expected issuer identifier value in the Example: |
OpenID Connect node
Lets AM authenticate users of OpenID Connect-compliant resource servers.
As OpenID Connect is an additional layer on top of OAuth 2.0, described in RFC 6749, The OAuth 2.0 Authorization Framework. OpenID Connect is described in the OpenID Connect Core 1.0 incorporating errata set 1 specification.
This node and its related services, are deprecated. For information about the legacy/deprecated social authentication node and module implementations, refer to Social authentication in the ForgeRock Access Management 7 Authentication and Single Sign-On Guide. |
The OpenID Connect node implements the Authorization code grant.
Outcomes
-
Account Exists
-
No account Exists
Evaluation continues along the Account Exists
path if an account matching the attributes
retrieved from the OpenID Connect identity provider is found in the identity store;
otherwise, evaluation continues along the No account exists
path.
Properties
Property | Usage | ||
---|---|---|---|
Client ID (required) |
Specifies the |
||
Client Secret (required) |
Specifies the |
||
Authentication Endpoint URL (required) |
Specifies the URL to the social provider’s endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749). Example: |
||
Access Token Endpoint URL (required) |
Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749). Example: |
||
User Profile Service URL (required) |
Specifies the user profile URL that returns profile information. If not specified, attributes are mapped from the claims returned by the Example: |
||
OAuth Scope |
Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). Ensure you use the correct scope delimiter required by the identity provider, including commas or spaces. The list depends on the permissions that the resource owner, such as the end user, grants to the client application. |
||
Redirect URL |
Specifies the URL the user is redirected to by the social identity provider after authenticating. For authentication trees in AM, set this property to the URL of the UI.
For example, |
||
Social Provider (required) |
Specifies the name of the OpenID Connect provider for which this node is being set up. Example: |
||
Auth ID Key |
Specifies the attribute the social identity provider uses to identify an authenticated individual. Example: |
||
Use Basic Auth |
Specifies that the client uses HTTP Basic authentication when authenticating to the social provider. Default: |
||
Account Provider |
Specifies the name of the class that implements the account provider. Default: |
||
Account Mapper |
Specifies the name of the class that implements the method of locating local accounts based on the attributes returned from the social identity provider. The provided implementations is The Account Mapper classes can take two constructor parameters:
For example, to prefix all received property values with org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|*|openid- |
||
Attribute Mapper |
Specifies the list of fully qualified class names for implementations that map attributes from the authorization server to AM profile attributes. The provided implementations is The Attribute Mapper classes can take two constructor parameters to help differentiate between the providers:
For example, to prefix incoming org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper |
||
iplanet-am-user-alias-list |
openid- To prefix all incoming values use an asterisk ( |
||
Account Mapper Configuration |
Specifies the attribute configuration used to map the account of the user authenticated in the provider to the local identity store in AM. To add a mapping, specify the name of the provider attribute as the key, and the local attribute to map to as the value. For example, click Add, then specify |
||
Attribute Mapper Configuration |
Specifies how to map provider user attributes to local user profile attributes. To add a mapping, specify the name of the provider attribute as the Key, and the local attribute to map to as the Value. For example, click Add, then specify Examples: first_name=givenname last_name=sn name=cn email=mail id=facebook-id first_name=facebook-fname last_name=facebook-lname email=facebook-email |
||
Save attributes in the session |
When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session. |
||
OAuth 2.0 Mix-Up Mitigation Enabled |
Controls whether the authentication node carries out additional verification steps when it receives the authorization code from the authorization server. Specifies that the client must compare the issuer identifier of the authorization server
upon registration with the issuer value returned as the When this is enabled, set the Token Issuer property so that the validation can succeed.
The authorization code response contains an issuer value (
For more information, refer to section 4 of OAuth 2.0 Mix-Up Mitigation Draft. |
||
Token Issuer (required) |
Corresponds to the expected issuer identifier value in the Example: |
||
OpenID Connect Validation Type (required) |
Specifies how to validate the ID token received from the OpenID Connect provider. This ignores keys specified in JWT headers, such as The following options are available to validate an incoming OpenID Connect ID token:
|
||
OpenID Connect Validation Value |
Provide the URL or secret key used to verify an incoming ID token, depending on the value selected in the OpenID Connect Validation Type property. |
Provision Dynamic Account node
Provision an account following successful authentication by a SAML2 authentication node or the Social Provider Handler node.
Accounts are provisioned using properties defined in the attribute mapper configuration of a social authentication or SAML2 authentication node earlier in the flow.
If a password has been acquired from the user, for example, by using the Password Collector node, it is used when provisioning the account; otherwise, a 20 character random string is used.
In addition to retrieving the password from the node state, the Provision Dynamic Account node
gets the realm
value, and attributes
and userNames
from userInfo
in the shared state.
It sets the username
attribute in the node’s shared state.
Provision IDM Account node
Redirects users to an IDM instance to provision an account.
This node and its related services, are deprecated. For information about the legacy/deprecated social authentication node and module implementations, refer to Social authentication in the ForgeRock Access Management 7 Authentication and Single Sign-On Guide. |
Ensure you have configured the details of the IDM instance in AM, by navigating to Configure > Global Services > IDM Provisioning.
SAML2 Authentication node
Integrates SAML v2.0 SSO into an AM authentication flow.
Use this node when deploying SAML v2.0 single sign-on in integrated mode (SP-initiated SSO only).
Regardless of the outcome, Account exists
or No account exists
,
if this node completes without failure, it sets the successURL
parameter in the shared node 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 service provider (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 identity provider (IdP) and a hosted SP in a circle of trust in the same realm where the authentication node is configured.
-
The service provider 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,
evaluation continues along the Account exists
outcome;
otherwise, 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 |
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 Default: |
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 in AM admin UI under Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context > Comparison Type. Valid comparison methods are For more information about the comparison methods, refer to the section on the Default: |
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 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. When specifying multiple authentication context classes, use the | character to separate the classes. For example: urn:oasis:names:tc:SAML:2.0:ac:classes:Password|urn:oasis:names:tc:SAML:2.0:ac:classes:TimesyncToken |
Authentication Context Declaration Reference |
(Optional) Specifies one or more URIs that identify authentication context declarations. When specifying multiple URIs, use the | character to separate the URIs. For more information, refer to the section on the |
Request Binding |
Specifies the format the SP will use to send the authentication request to the IdP. Valid values are Default: |
Response Binding |
Specifies the format the IdP will use to send the response to the SP. Valid values are Default: |
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: |
For examples, refer to SSO and SLO in integrated mode.
Social Facebook node
Duplicates OAuth 2.0 node, but is preconfigured to work with Facebook.
You specify only the Client ID
and Client Secret
.
This node and its related services, are deprecated. For information about the legacy/deprecated social authentication node and module implementations, refer to Social authentication in the ForgeRock Access Management 7 Authentication and Single Sign-On Guide. |
Outcomes
-
Account exists
-
No account exists
Evaluation continues along the Account Exists
path
if an account matching the attributes retrieved from Facebook are found in the user data store;
otherwise, evaluation continues along the No account exists
path.
Properties
Property | Usage | ||
---|---|---|---|
Client ID |
Specifies the |
||
Client Secret |
Specifies the |
||
Authentication Endpoint URL |
Specifies the URL to the social provider’s endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749). Default: |
||
Access Token Endpoint URL |
Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749). Default: |
||
User Profile Service URL |
Specifies the user profile URL that returns profile information. Default: |
||
OAuth Scope |
Specifies a comma-separated list of user profile attributes the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). The list depends on the permissions the resource owner, such as the end user, grants to the client application. |
||
Redirect URL |
Specifies the URL the user is redirected to by Facebook after authenticating to continue the flow. Set this property to the URL of the AM UI.
For example,
|
||
Social Provider |
Specifies the name of the social provider for which this node is being set up. Default: |
||
Auth ID Key |
Specifies the attribute the social identity provider uses to identify an authenticated individual. Default: |
||
Use Basic Auth |
Specifies that the client uses HTTP Basic authentication when authenticating to the social provider. Default: |
||
Account Provider |
Specifies the name of the class that implements the account provider. Default: |
||
Account Mapper |
Specifies the name of the class that implements the method of locating local accounts based on the attributes returned from Facebook. Default: |
||
Attribute Mapper |
Specifies the list of fully qualified class names for implementations that map attributes from Facebook to AM profile attributes. Default: |
||
Account Mapper Configuration |
Specifies the attribute configuration used to map the account of the user authenticated in the Social Facebook provider
to the local data store in AM.
Valid values are in the form Default:
|
||
Attribute Mapper Configuration |
Map of Facebook user account attributes to local user profile attributes,
with values in the form Default:
|
||
Save attributes in the session |
When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session. Default: |
||
OAuth 2.0 Mix-Up Mitigation Enabled |
Controls whether the authentication node carries out additional verification steps when it receives the authorization code from the authorization server. Specifies that the client must compare the issuer identifier of the authorization server
upon registration with the issuer value returned as the The Token Issuer property must be entered when the OAuth 2.0 Mix-Up Mitigation feature is enabled,
so that the validation can succeed.
The authorization code response contains an issuer value ( For more information, refer to section 4 of OAuth 2.0 Mix-Up Mitigation Draft. |
||
Token Issuer |
Corresponds to the expected issuer identifier value in the Example: |
Social Google node
Duplicates OAuth 2.0 node, but is preconfigured to work with Google.
You specify only the Client ID
and Client Secret
.
This node and its related services, are deprecated. For information about the legacy/deprecated social authentication node and module implementations, refer to Social authentication in the ForgeRock Access Management 7 Authentication and Single Sign-On Guide. |
Outcomes
-
Account exists
-
No account exists
Evaluation continues along the Account Exists
path
if an account matching the attributes retrieved from Google are found in the user data store;
otherwise, evaluation continues along the No account exists
path.
Properties
Property | Usage | ||
---|---|---|---|
Client ID (required) |
Specifies the |
||
Client Secret (required) |
Specifies the |
||
Authentication Endpoint URL |
Specifies the URL to the social provider’s endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749). Default: |
||
Access Token Endpoint URL |
Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749). Default: |
||
User Profile Service URL |
Specifies the user profile URL that returns profile information. Default: |
||
OAuth Scope |
Specifies a space-separated list of user profile attributes the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). The list depends on the permissions the resource owner, such as the end user, grants to the client application. Default: |
||
Redirect URL |
Specifies the URL the user is redirected to by Google after authenticating to continue the flow. Set this property to the URL of the AM UI.
For example,
|
||
Social Provider |
Specifies the name of the social provider for which this node is being set up. Default: |
||
Auth ID Key |
Specifies the attribute the social identity provider uses to identify an authenticated individual. Default: |
||
Use Basic Auth |
Specifies that the client uses HTTP Basic authentication when authenticating to Google. Default: |
||
Account Provider |
Specifies the name of the class that implements the account provider. Default: |
||
Account Mapper |
Specifies the name of the class that implements the method of locating local accounts based on the attributes returned from Google. Default: |
||
Attribute Mapper |
Specifies the list of fully qualified class names for implementations that map attributes from Google to AM profile attributes. Default:
|
||
Account Mapper Configuration |
Specifies the attribute configuration used to map the account of the user
authenticated in the Social Google provider to the local data store in AM.
Valid values are in the form Default:
|
||
Attribute Mapper Configuration |
Map of Google user account attributes to local user profile attributes,
with values in the form Default:
|
||
Save attributes in the session |
When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session. Default: |
||
OAuth 2.0 Mix-Up Mitigation Enabled |
Controls whether the authentication node carries out additional verification steps when it receives the authorization code from the authorization server. Specifies that the client must compare the issuer identifier of the authorization server
upon registration with the issuer value returned as the The Token Issuer property must be entered when the OAuth 2.0 Mix-Up Mitigation feature is enabled,
so that the validation can succeed.
The authorization code response contains an issuer value ( For more information, refer to section 4 of OAuth 2.0 Mix-Up Mitigation Draft. |
||
Token Issuer |
Corresponds to the expected issuer identifier value in the Example: |
Social Ignore Profile node
Specifies whether to ignore a local user profile.
If evaluation flows through this node after successful social authentication, AM issues an SSO token regardless of whether a user profile exists in the data store. AM does not check for whether a user profile is present.
This node and its related services, are deprecated. For information about the legacy/deprecated social authentication node and module implementations, refer to Social authentication in the ForgeRock Access Management 7 Authentication and Single Sign-On Guide. |
Social Provider Handler node
Takes the provider selection from the Select Identity Provider node and attempts to authenticate the user. This node collects relevant profile information from the provider and returns the user to the flow, transforming the profile information into the appropriate attributes.
Compatibility
Product | Compatible? |
---|---|
ForgeRock Identity Cloud |
Yes |
ForgeRock Access Management (self-managed) |
Yes |
ForgeRock Identity Platform (self-managed) |
Yes |
Inputs
This node reads the user’s selected social identity provider from shared state.
Implement the Select Identity Provider node before this node to capture the social provider name.
Dependencies
-
The Social Identity Provider service must be configured with the details of at least one social identity provider.
-
The user must have selected a social identity provider in a previous node in the journey.
Configuration
Property | Usage |
---|---|
Transformation Script (required) |
This script is used after the configured provider’s normalization script has mapped the social identity provider’s attributes to a profile format compatible with AM. The transformation script then transforms a normalized social profile to an identity. Select To view the scripts and bindings, refer to normalized-profile-to-identity.js. Normalization scripts ( |
Username Attribute |
ForgeRock Identity Platform deployments only. |
Client Type |
Specify the client type you are using to authenticate to the provider. Use the default, Select |
Outputs
-
When the node attempts to authenticate the user through the social provider, it sets
expectProfileInformation
totrue
in the node state. If no profile information is returned, the journey follows theSocial auth interrupted
outcome. -
If the node retrieves the profile information from the social identity provider, performs the required transformations, and locates a matching identity, it puts the identity into the node state to authenticate the user.
Outcomes
Account exists
-
Social authentication succeeded, and a matching ForgeRock account exists.
No account exists
-
Social authentication succeeded, but no matching ForgeRock account exists.
To ensure existing users are dynamically linked, complete these additional steps:
In a standalone AM deployment:
-
Connect the
No account exists
outcome to a Scripted Decision node. -
Write a Scripted Decision node script and use the
idRepository
binding’sget-
andsetAttribute
methods to check for an existing account and add a link by updating the account-linking attribute,iplanet-am-user-alias-list
.For multiple OIDC providers, add links to the existing list. For example:
"iplanet-am-user-alias-list": [ "google_IDP-123456789", "amazon_IDP-987654321" ],
-
Connect the Scripted Decision node to a Provision Dynamic Account node to update the account.
-
Social auth interrupted
-
The user interrupted the social authentication journey after the node requested profile information from the social identity provider. This can happen in the following situations:
-
The user clicks the Back button in their browser from the social identity provider’s login page
-
The user clicks the Cancel button on the social identity provider’s login page
-
The user re-enters the journey URL in the same browser window
In this case, the node routes the user back to the Select Identity Provider node to select a social identity provider again.
-
Example
This example shows the Social Provider Handler node in a social authentication journey.
a A Page node contains the Select Identity Provider node node that prompts the user to select a social identity provider or to authenticate with a username and password.
b If the user selects local authentication, the Data Store Decision node takes care of the authentication.
c If the user selects social authentication, the Social Provider Handler node does the following:
-
Routes the user to the selected social provider for authentication.
-
Retrieves the user’s profile information, and transforms it into a format that AM can use.
-
Assesses whether the user has an existing identity in AM.
-
If the user has an existing identity, authenticates that identity.
-
If the user doesn’t have an identity, routes the user to another page node.
-
If the user interrupts the social authentication, routes the user back to the Select Identity Provider node.
d The nodes on the page node request the information required to register a new identity.
e The Create Object node creates the new identity in AM.
Write Federation Information 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 with the SAML2 Authentication node, and ensure that the NameID Format is persistent
.
Properties
This node has no configurable properties.
For examples, refer to SSO and SLO in integrated mode.
Identity management nodes
Accept Terms and Conditions 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 terms and conditions in the Identity Platform admin UI. For more information, refer to Terms and conditions.
Use this node for registration, or combined with the Terms and Conditions Decision node for progressive profiling or log in.
Example
For progressive profiling, include this node after a Terms and Conditions Decision node. If the user has not accepted the latest version of the terms and conditions, evaluation takes them to a page that requires them to accept the current terms and conditions.
If the user accepts, the acceptance response is stored in IDM:
Attribute Collector node
Collects the values of attributes for use later in the flow; for example, to populate a new account during registration.
This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment. |
This node supports three types of attributes:
string
boolean
number
To request a value, the attribute must be present in the IDM schema of the current identity object.
The node lets you configure whether the attributes are required to continue, and whether to validate them through IDM’s policy filter.
Use the node alone or within a Page node.
Properties
Property | Usage |
---|---|
Attributes to Collect |
A list of the attributes to collect, based on those in the IDM schema for the current identity object. |
All Attributes Required |
When enabled, all attributes collected in this node are required in order to continue. |
Validate Input |
When enabled, validate the content against any policies specified in the IDM schema for each collected attribute. For more information, refer to Use policies to validate data in the IDM documentation. If you enable this property, the collected attributes must be User Editable in IDM. To make an attribute user-editable in the IDM admin UI:
For details, refer to Property Configuration Properties in the IDM documentation. |
Identity Attribute |
The attribute used to identify the object in IDM. |
Attribute Present Decision node
Checks whether an attribute is present on an object, including private attributes. There is no need to specify the value of the attribute.
This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment. |
Use this node during an update password flow to check whether the local account has a password, for example.
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.
Attribute Value Decision node
Verifies that the 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 the specified attribute was collected.
Examples:
-
To validate that a user provided the country attribute during registration, set the comparison operation to
PRESENT
, and the comparison attribute tocountry
. -
To validate that the country attribute is set to the United States, set the comparison operation to
EQUALS
, the comparison attribute tocountry
, and the comparison value toUnited 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:
|
Comparison Attribute |
The object attribute to compare. |
Comparison Value |
When Comparison Operation is |
Identity Attribute |
The attribute used to identify the object in IDM. |
Consent Collector node
Prompts the user for 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, AM does not show a consent message to the user.
This node is primarily used in progressive profile and 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 |
Create Object node
Creates a new object in IDM based on information collected during authentication, 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 must be collected during authentication in order to create the new object.
Properties
Property | Usage | ||
---|---|---|---|
Identity Resource |
The type of IDM managed identity resource object that this node creates. It must match the identity resource type for the current flow.
|
Create Password node
Lets users create a password when provisioning an account.
This node and its related services, are deprecated. For information about the legacy/deprecated social authentication node and module implementations, refer to Social authentication in the ForgeRock Access Management 7 Authentication and Single Sign-On Guide. |
Social identity providers do not provide a user’s password. Use this node to provide a password to complete the user’s credentials before provisioning an account.
The flow must provision an account after prompting the user for a password, for example, by using the Provision Dynamic Account node. If no account is provisioned, the flow does not save the password. Do not place any nodes that request additional input from the user between this node and the provisioning node; otherwise, the password is lost. |
Display Username node
Fetches a username based on a different identifying attribute, such as an email address, then displays it.
This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment. |
To email the username to the user instead, use the Identify Existing User node combined with a Email Suspend node or Email Template node.
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. When this node serves to recover a username, the identity attribute should be some other attribute that is unique to a user object, such as the email address. The node raises an exception when more than one value exists for this attribute. Make sure the value of whatever attribute you select is unique for each user. |
Identify Existing User 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 the shared node state.
This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment. |
Use this node in a forgotten password flow to fetch a username to email to the user. To display the username on the 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. When this node serves to recover a username, the identity attribute should be some other attribute that is unique to a user object, such as the email address. |
Example
The following is an example of a forgotten password flow. The user enters information that the Identify Existing User node uses to try to identify them. Next, AM uses the Email Suspend node to send an email to the user and suspend authentication. Once authentication resumes, AM sends the user to a different flow to reset their password:
KBA Decision node
Checks whether the user account has the required minimum number of KBA questions.
This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment. |
To set the number of KBA questions, edit Configure > Security Questions > Questions > Number in the IDM admin UI.
KBA Definition node
Collects KBA questions and answers and saves them to the user profile.
This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment. |
Use this node when creating or updating a user with Knowledge-Based Authentication enabled. For more information, refer to Security questions.
Properties
Property | Usage |
---|---|
Purpose Message |
A localized 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:
To edit an existing security question, click the edit icon ,make your changes, and click Save. |
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. |
Use this node for additional authentication when resetting a forgotten password or username.
To set the number of KBA questions, edit Configure > Security Questions > Questions > Number in the IDM admin UI.
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.
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, refer to 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, refer to Synchronization in the IDM documentation.
Use this node after collecting the authentication credentials. For example, use the Username Collector node and the Password Collector 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: |
Identity Attribute |
The username attribute for authentication. Default: |
Password Attribute |
The password attribute for authentication. Default: |
Patch Object node
Patches the attributes in an existing managed object in IDM.
This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment. |
Use this node for progressive profile completion 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, for example, when updating their password. |
||
Ignored Fields |
Fields from the shared node state that should be ignored as part of patch. Use this to patch only the fields you want to update. If this is empty, the node attempts to update all the node shared state fields as part of the patch. |
||
Identity Resource |
The type of IDM managed identity resource object that this node creates. It must match the identity resource type for the current flow.
|
||
Identity Attribute |
The attribute used to identify the object to update in IDM. |
Platform Password node
Prompts the user to enter their password and stores the input in a configurable state attribute.
This functionality requires that you configure 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 be in the shared state to evaluate user-specific policies,
such as password history, cannot-contain-others, and so on.
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:
|
||
Password Attribute |
The attribute used to store a password in the IDM object. |
||
Confirm Password |
Enable this option to require the user to enter the password identically in a second field.
|
Platform Username 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. |
Profile Completeness Decision node
Use progressive profile flows to check how much of a user’s profile has been completed,
where the completeness of a profile is expressed as a percentage of user-viewable,
and user-editable fields that are not null
.
This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment. |
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, 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, refer to Construct queries in the IDM documentation.
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 the shared node state.
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 this node creates. It must match the identity resource type for the current flow.
|
Select Identity Provider node
Presents the user with a list of configured, enabled, social identity providers to use for authentication.
Use this node with the Social Provider Handler node to use the Social Identity Provider Service.
The node has two possible outputs: social authentication and local authentication. Local authentication can be turned off by disabling Include local authentication.
This node returns the SelectIdPCallback when more than one social identity provider is enabled, or a single provider is enabled as well as the Local Authentication option, It then requires a choice from the user. If no choice from the user is required, authentication proceeds to the next node in the flow.
Outcomes
-
Social Authentication
-
Local Authentication
To turn off local authentication, disable Include local authentication.
Properties
Property | Usage | ||
---|---|---|---|
Include local authentication |
Whether local authentication is included as a method for authenticating. |
||
Offer only existing providers |
ForgeRock Identity Platform deployments only. |
||
Password attribute |
ForgeRock Identity Platform deployments only. |
||
Identity Attribute |
ForgeRock Identity Platform deployments only. |
||
Filter Enabled Providers |
By default, the node displays all identity providers 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.
If this field is not empty, providers must be in the list and must be enabled in the Social Identity Provider service to appear. If left blank, the node displays all enabled providers. |
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 Identity Platform admin UI. For more information, refer to Terms and conditions.
Use this node to verify the user has accepted terms and conditions before proceeding, for example, during login or progressive profile data collection.
You can use this node with the Accept Terms and Conditions node.
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, to prompt users to review your terms and conditions after the account is a week old,
set the Elapsed Time property to 1 week
.
After that time has elapsed, the next time the user logs in, they are prompted to review your terms and conditions.
Use this node 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 |
Identity Attribute |
The attribute used to identify the object to update in IDM. |
Utility nodes
Agent Data Store Decision node
Verifies that a provided agent ID and password match a web agent or Java agent profile configured in AM. Obtain the web or Java agent ID and password with a Zero Page Login Collector node.
Non-agent identities, such as users stored in configured identity repositories, cannot be verified by using this node. Use the Data Store Decision node instead. |
Anonymous Session Upgrade node
Upgrades an anonymous session to a non-anonymous session.
Use this as the first node in the flow.
Example
After using the Anonymous User Mapping node to access AM as an anonymous user, this node lets users upgrade their session to a non-anonymous one:
Anonymous User Mapping node
Lets users log in to an 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
.
Take care to limit access for such users. For example, grant anonymous users access to public downloads on your site.
Choice Collector node
Define two or more options to present to the user when authenticating.
Properties
Property | Usage | ||
---|---|---|---|
Choices |
Enter two or more choice strings to display to the user. To remove a choice, select its Delete icon . To delete all choices, select the Clear all button in the Choices field. |
||
Default Choice (required) |
Enter the value of the choice to be selected by 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:
|
Configuration Provider node
The Configuration Provider node is a scripted node that dynamically imitates another node and replaces it in the journey.
The script builds a map of configuration properties matching settings for the imitated node. The Configuration Provider node uses the settings to imitate the other node.
Compatibility
Product | Compatible? |
---|---|
ForgeRock Identity Cloud |
|
ForgeRock Access Management (self-managed) |
|
ForgeRock Identity Platform (self-managed) |
Inputs
The specific shared state inputs depend on your script and the configuration it builds. The shared state data must include all required Script Inputs properties.
In other words, shared state data must include whatever the Script requires to prepare configuration data for the imitated node.
Dependencies
To prepare to use this node:
-
Decide what type of node to imitate.
The imitated node must have a fixed set of outcomes. You can’t use a node type whose outcomes change based on the node configuration.
-
Create an appropriate Config Provider script.
Base your script on the
config-provider-node.js
sample. -
Obtain the list of required configuration properties for the imitated node.
In AM admin UI, use the API explorer endpoint
/realm-config/authentication/authenticationtrees/nodes/NodeType#_action_template
.The following request returns the configuration properties for a Message node:
$ curl \ --request POST \ --header "<cookie>: <token>" \ "https://openam.example.com:8443/openam/json/realm-config/authentication/authenticationtrees/nodes/MessageNode?_action=template" { "messageYes": {}, "message": {}, "messageNo": {} }
Your script builds a
config
object, a map of configuration properties matching the settings of the imitated node. The following example consumes theusername
shared state property to build the Message node configuration:config = { "message": {"en-GB": `Hi ${nodeState.get("username")}. Please confirm you are over 18.`}, "messageYes": {"en-GB": "Confirm"}, "messageNo": {"en-GB": "Deny"}, }
Configuration
Property | Usage |
---|---|
Script |
Select the script you created for this node. |
Node Type |
Select the type of node to imitate. |
Script Inputs |
Optionally limit the shared state data properties in the shared state input to the selected Script. Default: |
Outcomes
The Configuration Provider node inherits all the outcomes of its configured Node Type. Connect these as you would the outcomes of the imitated node.
This node also has a Configuration failure outcome. The Configuration failure outcome arises when:
-
The Configuration Provider node failed to build the configuration map.
-
The configuration map is missing required values.
-
The configuration map is invalid.
Errors
In addition to the messages from the imitated node, this node can log the following:
- Warnings
-
-
Failed to collect inputs of contained node: node-type
A required input property was missing.
-
Failed to get outcome provider for node type.
The Node Type outcomes were missing.
-
- Errors
-
-
Failed to configure node: node-type
This corresponds to the Configuration failure outcome.
-
To troubleshoot HTTP errors this node causes, refer to the Errors section of the imitated node.
Examples
In the following example, the Configuration Provider node imitates a Message node.
The Configuration Provider settings are the following:
- Script
-
A script to configure a Message node dynamically.
The script accesses the
username
from shared state data to set the message:config = { "message": {"en-GB": `Hi ${nodeState.get("username")}. Please confirm you are over 18.`}, "messageYes": {"en-GB": "Confirm"}, "messageNo": {"en-GB": "Deny"}, }
- Node Type
-
Message Node
- Script Inputs
-
username
The default,
*
, also works becauseusername
is one of the available shared state properties.
The Configuration Provider node is part of a journey where the user enters their username and password before getting the message screen, so their username is in the shared state data. Notice the outcomes of the node include those of the Message node (True, False):
When the journey reaches the Configuration Provider node,
the script for the node retrieves the username
and dynamically configures the node.
The Configuration Provider node, imitating a Message node, prompts the user with the message:
-
When the user clicks Confirm, the journey continues to the Increment Login Count node.
-
When the user clicks Deny, the journey continues to the Failure node.
-
If the configuration process fails, the node triggers the Configuration failure outcome and the journey continues to the Failure node. In this case, you can find the reason for the failure in the logs.
Email Suspend node
Generates and sends mail to a user, such as an address verification email, based on an email template in IDM. Authentication pauses until the user clicks a link in the email to resume the flow.
This functionality requires that you configure AM as part of a ForgeRock Identity Platform deployment. |
This node generates the link and passes it to IDM as the resumeURI
property of the email object.
It uses the email service configured in IDM to send email.
If there is no need to pause authentication 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. 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 return once AM suspends authentication. The default message is, "An email has been sent to your inbox." |
Object Lookup |
Determines whether to look up the object in IDM. If enabled, AM queries IDM for an existing object; otherwise, the node uses the object in the shared node state. For example, if the flow suspends user registration before creating the user object, disable this option. If registration has created the new user object while authentication was suspended, enable this option. |
Identity Attribute |
The attribute used to identify the object in IDM. |
Example
The following is an example of a forgotten password flow. The user enters information that the Identify Existing User node uses to try to identify them. Next, AM uses the Email Suspend node to send mail to the user and suspend authentication. Once authentication resumes, AM sends the user to a different flow to reset their password:
Email Template node
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 an email. If authentication should 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. 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. |
Failure URL node
Sets the redirect URL when authentication fails.
Specifying a failure URL overrides any |
For more information on how AM determines the redirection URL, and to configure the Validation Service to trust redirection URLs, refer to Success and failure redirection URLs.
The URL is also saved in the shared For more information, refer to Customize authentication trees. |
Get Session Data node
Retrieves the value of a specified key from a user’s session data,
and stores it in the specified key in the shared nodeState
object.
This 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.
This node fails with an error if you attempt to get a property when the user does not have an existing session. Use a Scripted Decision node with a script that determines if an existing session is present:
if (typeof existingSession !== 'undefined') {
outcome = "hasSession";
} else {
outcome = "noSession";
}
Properties
Property | Usage |
---|---|
Session Data Key (required) |
Specify the name of a key in the user’s session data used to retrieve the value. |
Shared State Key (required) |
Specify the name of a key in the |
Example
The following table includes example keys that may be available in an existing session and the corresponding sample values:
Key | Sample value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Inner Tree Evaluator node
Lets you nest authentication journeys as children within a parent. There is no limit to the depth of nesting.
Any information collected or set by the parent journey, such as a username or the authentication level, is available to child journeys.
Shared node state data collected by child journeys is available to the parent when evaluation of the child is complete, but data stored in transient and secure state is not. For instance, if a child journey collects and stores the user’s password in transient state, it cannot be retrieved by a node in the parent journey when evaluation continues.
For information about shared state data, refer to Access shared state data.
Message node
Presents a custom, localized message to the user.
In addition to the message, you can provide localized positive and negative responses the user must select to proceed.
Properties
Property | Usage |
---|---|
Message |
Click Add. Enter the message locale in the Locales that you specify here must be real locales; otherwise, AM returns an 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 To remove a message, select its delete icon (). |
Positive answer |
Specify a positive answer that causes evaluation to continue along the Click the Add button, and then enter the locale of the positive answer in the 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 To remove a message, select its delete icon (). |
Negative answer |
Specify a negative answer that causes evaluation to continue along the Click the Add button, and then enter the locale of the negative answer in the 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 To remove a message, select its delete icon (). |
Shared State Property Name |
The name of the shared state variable. |
Meter node
Increments a specified metric key each time evaluation passes through the node.
For information on the Meter
metric type, refer to Monitoring metric types.
The metric is exposed in all available interfaces, as described in Monitor AM instances.
Page 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. Only add nodes that use callbacks to request input. Do not add other nodes, such as the Data Store Decision node and the Push Sender node to this node.
Outcomes
The outcomes 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 labeled sections. |
Page Description |
Optional 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 |
An optional stage name to pass to the client to aid in rendering. |
This node’s optional properties are passed in the response, but a self-hosted or custom UI must support these properties to make them visible to the end user. |
Polling Wait node
Pauses authentication progress for a specified number of seconds, for example, to wait for a response to a one-time password email or push notification.
Requests 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
:
$ curl \
--request POST \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--header "Content-Type: application/json" \
--data '{
"authId": "eyJ0eXAiOiJK…u4WvZmiI",
"callbacks": [
{
"type": "PollingWaitCallback",
"output": [
{
"name": "waitTime",
"value": "10000"
},
{
"name": "message",
"value": "Waiting for response…"
}
]
}
]
}' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=Example'
The end user UI automatically waits for the required amount of time and resubmits the page to continue evaluation. The message displayed during the wait is configurable with the Waiting Message property.
Outcomes
-
Done
-
Exited
(configurable) -
Spam
(configurable)
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.
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.
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 authentication. Default: |
Enable Spam Detection |
Specify whether to track the number of responses received during the wait time,
and continue evaluation along the Default: Disabled |
Spam Tolerance |
Specify the number of responses to allow during the wait time
before continuing evaluation along the Default: |
Waiting Message |
Specifies the optional message to display to the user. Provide the message in multiple languages by specifying the locale in the KEY field, for example, Messages provided in the node override the defaults provided by AM. For information about customizing and translating the default messages, refer to Internationalization. |
Exitable |
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 evaluation to continue along the 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, Provide the message in multiple languages by specifying the locale in the KEY field, for example, Messages provided in the node override the defaults provided by AM. For information about customizing and translating the default messages, refer to Internationalization. |
Register Logout Webhook 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 evaluation passes through this 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.
Remove Session Properties node
Removes properties from the session. The session properties may have been set by a Set Session Properties node elsewhere in the flow.
If a specified key is not found in the list of session properties it is added to the session upon successful authentication, no error is thrown, and evaluation continues along the single outcome path.
If a specified key is found,
the evaluation continues along the single outcome path after setting the value of the property to null
.
Retry Limit Decision node
Permits the specified number of passes through to the Retry
outcome path
before continuing evaluation along the Reject
outcome path.
Properties
Property | Usage |
---|---|
Retry limit |
Specify the number of retries to allow. Default: |
Save Retry Limit to User |
Specify whether the number of failed login attempts persists between successful authentications. Possible values are:
For security reasons, ForgeRock recommends that you enable this setting. Default: Enabled. |
Scripted Decision node
Runs a script during authentication.
The script defines the possible outcome paths by setting one or more values of a string variable named outcome
.
For more information on creating scripts, refer to
Manage scripts (UI).
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 this node, refer to Scripted decision node API.
Properties
Property | Usage | ||
---|---|---|---|
Script |
Select the script to execute from the drop-down field. |
||
Outcomes |
Enter the possible strings that can be assigned to the |
||
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
Add 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 Configure authentication webhooks. |
State Metadata node
Returns selected attributes from the shared node state as metadata.
This node sends a MetaDataCallback
to retrieve shared state values,
which it adds to the JSON response from the /authenticate
endpoint.
This example shows how a shared state attribute, mail
, is returned:
"callbacks": [
{
"type": "MetadataCallback",
"output": [
{
"name": "data",
"value": {
"mail": "bjensen@example.com"
}
}
]
}
]
Use this node to display custom information that includes user attributes without having to alter the existing flow.
For example, for OTP authentication with a choice of email or SMS, use this node to return the user’s email address or phone number. You can use the attributes with an OTP Collector Decision node, and optionally, a Scripted Decision node, to customize the data for display later.
Success URL node
Sets the redirect URL when authentication succeeds.
Specifying a success URL overrides any |
For more information on how AM determines the redirection URL, and to configure the Validation Service to trust redirection URLs, refer to Success and failure redirection URLs.
The URL is also saved in the For more information, refer to Customize authentication trees. |
Timer Start node
Starts a named timer metric, which you can stop with a Timer Stop node.
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 evaluation passed through this node. |
Timer Stop node
Records the time elapsed since evaluation passed through the Timer Start node in the specified metric name.
For information on the Timer
metric type, refer to Monitoring metric types.
Note that this node does not reset the time stored in the specified Start Time Property property. Other Timer Stop nodes can also calculate the time elapsed since evaluation passed through the same Timer Start node.
The metric is exposed in all available interfaces, as described in Monitor AM instances.
Properties
Property | Usage | ||
---|---|---|---|
Start Time Property |
Specify the property name containing the time from which to calculate the elapsed time. |
||
Metric Key (required) |
Enter the name for a new metric that stores the calculated elapsed time. The name that you select is used to identify the metric that exposes the data collected
by this node. For example, if you enter
|
Thing nodes
Authenticate Thing node
This node authenticates a thing. A thing represents an IoT device, service, or the IoT Gateway.
Before you configure this node, ensure that the ref:pingam:reference:global-services-configuration.adoc#global-iot[IoT Service] is configured for the realm.
Support for this node is provided by the IoT SDK. |
The node supports two methods of authentication:
-
Proof of Possession JWT
The node collects a proof-of-possession JWT from the request and does the following:
-
Checks that the claims are valid.
-
Checks that an identity with the same ID as the name of the JWT subject exists.
-
Checks that the identity contains a confirmation key that matches the JWT
kid
. -
Validates the JWT signature, using the confirmation key stored in the identity.
-
-
Client Assertion
The node collects a JWT Bearer token from the request for authentication and validates the request according to the JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants.
Outcomes
-
Success
-
Failure
-
Requires Registration
If all checks are successful, evaluation continues through the Success
path,
and adds the username and the verified claims to the shared node state.
If the identity does not exist, or AM cannot match the identity with the confirmation key,
evaluation continues through the Requires Registration
outcome.
If any other check fails, evaluation continues through the Failure
outcome.
Properties
Property | Usage |
---|---|
JWT Authentication Method |
Choose the required JWT authentication method:
|
Issue Restricted Token |
If this setting is enabled, the node adds a Proof of Possession restriction to the session token issued on successful authentication. Any requests accompanied by the token must be signed with the key that was used to sign the authentication JWT. |
Additional Audience Values |
Specify any additional audience values that will be permitted when verifying JWTs. These audience values are in addition to the AM base, issuer and token endpoint URIs for the Client Assertion authentication method or the realm path for Proof of Possession. |
Examples
The following example shows how to authenticate a thing when the identity already exists in the identity store and when its profile contains a confirmation key:
The following example shows how to authenticate a thing when the identity does not exist, or when it needs to refresh its confirmation key:
Register Thing node
This node authenticates a thing. A thing represents an IoT device, service, or the IoT Gateway.
Before you configure this node, ensure that the ref:pingam:reference:global-services-configuration.adoc#global-iot[IoT Service] is configured for the realm.
Support for this node is provided by the IoT SDK. |
The node collects a JWT from the request and validates the JWT according to the configured JWT registration method.
If the JWT is valid, the node uses the claims in the JWT to create an identity for the thing
and register (or rotate) a confirmation key for it.
Then, evaluation continues through the Success
outcome.
If the node cannot validate the JWT, evaluation continues through the Failure
outcome.
For an example on how to use this node, refer to Authenticate Thing node.
Properties
Property | Usage |
---|---|
Choose the method to validate the JWT:
Default: Proof of Possession & Certificate |
|
Verify Certificate Subject |
If the configured JWT registration method is Default: Enabled |
Create Identity |
Specifies whether AM will create an ID for the thing if one does not exist. Default: Disabled |
Rotate Confirmation Key |
Specifies whether multiple confirmation keys can be registered for a thing. Disable this setting to allow only one key per thing. Default: Disabled |
Default Attribute Values |
Lets you set default values for the thing’s attributes, where KEY is the name of the attribute in the data store, and VALUE is the default value of the attribute. |
Claim to Attribute Mapping |
If Create Identity is enabled, this property lets you map verified claims in the JWT to attributes in the thing identity. KEY is the claim name and VALUE is the name of the attribute in the data store. |
Overwrite Attributes |
Specifies whether the node overwrites the value for an existing profile attribute when a claim with a different value is provided in the JWT. Default: Disabled |