Authentication Nodes Configuration Reference

This section covers the configuration of the authentication nodes that are built into AM.

Tip

A number of additional authentication nodes are available from the ForgeRock Marketplace website.

Basic Authentication Nodes

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

Data Store Decision Node

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

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

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

Note

Unlike the "LDAP Decision Node", which supports LDAP Behera Password Policies, the data store decision node does not have separate outcomes for accounts that are locked or their password has expired.

Properties:

This node has no configurable properties.

Kerberos Node

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

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

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

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

Properties:

PropertyUsage
Service Principal

Specifies the Kerberos principal for authentication in the format HTTP/AM-DOMAIN@AD-DOMAIN, where AM-DOMAIN corresponds to the host and domain names of the AM instance, and AD-DOMAIN is the domain name of the Kerberos realm (the FQDN of the Active Directory domain). AD-DOMAIN can differ from the domain name for AM.

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, HTTP/AM-LB.example.com@KERBEROSREALM.INTERNAL.COM.

For more information, see 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.

Tip

You generate the keytab file using the Windows ktpass utility; for example:

C:\> ktpass -out fileName.keytab -princ HTTP/openam.example.com@AD_DOMAIN.COM -pass +rdnPass -maxPass 256 -mapuser amKerberos@frdpcloud.com -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -kvno 0
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, tree evaluation continues along the False path.

This search uses the Alias Search Attribute Name from the core realm attributes. See User Profile for more information about this property.

Is Initiator

When enabled (true), specifies that the node is using initiator credentials, which is the default.

When disabled (false), specifies that the node is using acceptor credentials.

Example:

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

Kerberos Example Tree
An example of a tree that uses the Kerberos node.

LDAP Decision Node

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

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

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

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

Important

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:

PropertyUsage

Primary LDAP Server

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

For example, directory_services.example.com:389.

Secondary LDAP Server

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

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

For example, directory_services_backup.example.com:389.

DN to Start User Search

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

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

Bind User DN, Bind User Password

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

Attribute Used to Retrieve User Profile

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

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

The default value of uid will form the following search filter of uid=user. Specifying multiple values such as uid and cn causes the node to create a search filter of (|(uid=user)(cn=user)).

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

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

User Search Filter

Specifies an additional filter to append to user searches.

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

Search Scope

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

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

Default: SUBTREE

LDAP Connection Mode

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

Possible values: LDAP, LDAPS, and StartTLS

Default: LDAP

Return User DN to DataStore

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

Default: Enabled

User Creation Attributes

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

Minimum Password Length

Specifies the minimum acceptable password length.

Default: 8

LDAP Behera Password Policy Support

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

Default: Enabled

Trust All Server Certificates

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

Default: Disabled

LDAP Connection Heartbeat Interval

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

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

Default: 10

LDAP Connection Heartbeat Time Unit

Specifies the time unit corresponding to LDAP Connection Heartbeat Interval.

Default: Seconds

LDAP Operations Timeout

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

Default: 0 (means no timeout)

Password Collector Node

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

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

Properties:

This node has no configurable properties.

Username Collector Node

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

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

Properties:

This node has no configurable properties.

Zero Page Login Collector Node

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

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

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

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

Properties:

PropertyUsage
Username Header name

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

Default: X-OpenAM-Username

Password Header name

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

Default: X-OpenAM-Password

Allow without referer

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

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

Default: Enabled

Referer whitelist

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

Note

You must disable the Allow without referer property for the Referer whitelist property to take effect.

Example:

Example Tree With Zero Page Login Node
Example tree showing Zero Page Login node usage.

Multi-Factor Authentication Nodes

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

HOTP Generator Node

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

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

Properties:

PropertyUsage
One-time password length Specify the number of digits in the one-time password.

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

Example:

HmacOneTimePassword Tree With HOTP Generator Node
HmacOneTimePassword tree showing HOTP Generator node usage.

OTP Collector Decision Node

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

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

Properties:

PropertyUsage
One Time Password Validity Length

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

Default: 5

OTP Email Sender Node

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

Properties:

PropertyUsage
Mail Server Host Name

Specifies the hostname of the SMTP email server.

Mail Server Host Port

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

Mail Server Authentication Username

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

Mail Server Authentication Password

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

Email From Address

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

Email Attribute Name

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

Default: mail

Mail Server Secure Connection

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

The possible values for this property are:

  • NON SSL/TLS

  • SSL/TLS

  • Start TLS

Default: SSL/TLS

Gateway Implementation Class

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

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

OTP SMS Sender Node

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

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

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

  • The @ character.

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

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

Properties:

PropertyUsage
Mail Server Host Name

Specifies the hostname of the SMTP email server.

Mail Server Host Port

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

Mail Server Authentication Username

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

Mail Server Authentication Password

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

Email From Address

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

Mobile Phone Number Attribute Name

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

Default: telephoneNumber

Mobile Carrier Attribute Name

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

Mail Server Secure Connection

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

The possible values for this property are:

  • NON SSL/TLS

  • SSL/TLS

  • Start TLS

Default: SSL/TLS

Gateway Implementation Class

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

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

Push Result Verifier Node

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

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

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

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

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

Tip

If the push message contained any additional information, for example if it was a registration request, the values are stored in the sharedState object of the tree, in a key named pushContent. For information on creating or customizing authentication nodes, see Authentication Node Development Guide.

Properties:

This node has no configurable properties.

Push Sender Node

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

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

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

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

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

Properties:

PropertyUsage
Message Timeout

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

User Message

Specifies the optional message to send to the user.

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

Messages provided in the node override the defaults provided by AM. For information about customizing and translating the default messages, see Internationalization.

The following variables can be used in the VALUE field:

{{user}}

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

{{issuer}}

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

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

Remove 'skip' option

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

Default: Disabled

Note

Nodes in authentication trees are not affected by the Two Factor Authentication Mandatory property, available at Realms > Realm Name > Authentication > Settings > General, as it only applies to modules within authentication chains.

Example:

Example Push Tree
Push Example tree showing Push Sender and Push Result Verifier node usage.

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

If the user has a registered device:

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

  2. The Polling Wait Node pauses the authentication tree for 8 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, the tree will send a new push notification.

      Tip

      A Retry Limit Decision node could be used here to constrain the number of times a new code is sent.

    • If the user has not yet responded, the tree loops back a step and the Polling Wait Node pauses the authentication tree for another 8 seconds.

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

    Tip

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

    Example Exit Message

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

If the user does not have a registered device:

  1. Because trees cannot currently register devices, a Set Failure URL node redirects the user to an authentication chain which can register a device to the user's profile.

  2. That registration chain redirects the user back to the push example tree when registration is complete.

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

  1. An Inner Tree Evaluator node provides an alternative method of authentication, for example an LDAP Decision node.

  2. Depending on the outcome of the inner tree, the push example tree evaluation continues to the Success or Failure outcome.

Recovery Code Collector Decision Node

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

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

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

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

Properties:

PropertyUsage
Recovery Code Type

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

Default: OATH

Recovery Code Display Node

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

Generated recovery codes are inserted into transient state when tree evaluation continues along the Success outcome path of the WebAuthn Registration Node. Connect the Recovery Code Display node to the Success outcome path to display the codes.

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

Important

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

Properties:

This node has no configurable properties.

Example:

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

Example output of the Recovery Code Display node
User's view of the Recovery Code Display node.

WebAuthn Authentication Node

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

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

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

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

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

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

Tip

If a client error occurs, the error type and description are added to a property named WebAuthenticationDOMException in the shared state. This property can be read by other nodes later in the tree, if required.

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

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

Properties:

PropertyUsage
Relying party identifier

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

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

Origin domains

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

If left empty, AM accepts any incoming domain.

User verification requirement

Specifies the required level of user verification.

The available options are:

REQUIRED

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

PREFERRED

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

DISCOURAGED

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

Allow recovery codes

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

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

Timeout

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

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

Username from device

Specifies whether AM requests that the device provides the username.

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

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

Return challenge as JavaScript

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

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

Example:

Example WebAuthn Authentication Tree
WebAuthn Authentication example tree.

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

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

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

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

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

The WebAuthn Authentication node waiting for an authenticator.
The WebAuthn Authentication node waiting for an authenticator.

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

Tip

The relying party details configured in the node are often included in the consent message to help the user verify the entity that is requesting access.

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

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

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

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



[4] HTTPS may not be required when testing locally, on http://localhost, for example. For more information, see Is origin potentially trustworthy?.

WebAuthn Device Storage Node

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

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

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

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

Properties:

PropertyUsage
Generate recovery codes

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

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

Important

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

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

WebAuthn Registration Node

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

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

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

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

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

Tip

If a client error occurs, the error type and description are added to a property named WebAuthenticationDOMException in the shared state. This property can be read by other nodes later in the tree, if required.

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

Properties:

PropertyUsage
Relying party

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

For example, Example Inc..

Relying party identifier

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

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

Origin domains

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

If left empty, AM accepts any incoming domain.

User verification requirement

Specifies the required level of user verification.

The available options are:

REQUIRED

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

PREFERRED

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

DISCOURAGED

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

Preferred mode of attestation

Specifies whether AM requires that the authenticator provides attestation statements.

The available options are:

NONE

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

INDIRECT

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

DIRECT

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

AM supports the following attestation formats:

Important

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

Specifically, AM does not currently support:

Accepted signing algorithms

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

Authentication attachment

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

There are two types of authenticator attachment:

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

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

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

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

There are two types of authenticator attachment:

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

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

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

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

The available options are:

UNSPECIFIED

AM accepts any attachment type.

PLATFORM

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

CROSS_PLATFORM

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

Trust Store alias

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 value is also appended to the string am.authentication.nodes.webauthn.truststore. to form the dynamic secret ID used to map the certificate chains.

For more information, see "Configuring WebAuthn Trust Anchors".

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, tree evaluation continues along the Client error outcome path, and a relevant message is stored in the WebAuthenticationDOMException property of the shared state.

Limit registrations

Specify whether the same authenticator can be registered multiple times.

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

Generate recovery codes

Specify whether WebAuthn-specific recovery codes should be generated. If enabled, recovery codes are generated and stored in transient state if registration was successful.

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

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

Important

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

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

Store data in transient state

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

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

Warning

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

Store device data in transient state

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

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

Important

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

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

Use the "WebAuthn Device Storage Node" to write the device data to the user's profile when this option is enabled.

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

Username to device

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

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

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

Shared state attribute for display name

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

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

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

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

Return challenge as JavaScript

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

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

Example:

Example WebAuthn Registration Tree
WebAuthn Registration example tree.

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

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

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

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

The WebAuthn Registration node waiting for an authenticator.
The WebAuthn Registration node waiting for an authenticator.

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

Tip

The relying party details configured in the node are often included in the consent message to help the user verify the entity that is requesting access.

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

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

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

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



[4] HTTPS may not be required when testing locally, on http://localhost, for example. For more information, see Is origin potentially trustworthy?.

Risk Management Authentication Nodes

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

Account Active Decision Node

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

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

Properties:

This node has no configurable properties.

Account lockout Node

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

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

Properties:

PropertyUsage
Lock Action

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

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

Example:

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

RetryLimit Tree With Account lockout Decision Node
RetryLimit tree showing Account lockout Decision node usage.

Auth Level Decision Node

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

Properties:

PropertyUsage
Sufficient Authentication Level Tree evaluation continues along the True path if the current authentication level is equal to or greater than the entered integer. Otherwise, the tree evaluation continues along the False path.

Modify Auth Level Node

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

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

Properties:

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

CAPTCHA Node

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

Important

reCAPTCHA cannot work with a pure REST client, as it requires user interaction. See the Google documentation for information on implementing reCAPTCHA in your UI.

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

Properties:

PropertyUsage
CAPTCHA Site Key Specifies the CAPTCHA site key. This is provided by Google or hCaptcha when signing up for access to the API. This is a required property.
CAPTCHA Secret Key Specifies the CAPTCHA secret key. This is provided by Google or hCaptcha when signing up for access to the API. This is a required property.
CAPTCHA Verification URL Specifies the URL used to verify the CAPTCHA submission. This is a required property. Possible values are:

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

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

CAPTCHA API URL

Specifies the URL of the JavaScript that loads the CAPTCHA widget. This is a required property. Possible values are:

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

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

Class of CAPTCHA HTML <div>

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

  • Google: g-recaptcha

  • hCaptcha: h-captcha

Example:

Example Tree With CAPTCHA Node
An example tree showing the CAPTCHA node.

Behavioral Authentication Nodes

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

Increment Login Count Node

Increments the successful login count property of a managed object in IDM. This requires integration with IDM to work, and is used in conjunction with the "Login Count Decision Node". If you plan to track the number of logins, this node will need to be included in your login authentication flow, but can be safely omitted if you are not planning to use that functionality.

Properties:

PropertyUsage
Identity Attribute The attribute used to identify the object in IDM.

Login Count Decision Node

Triggers an action when a user's successful login count property reaches a specified number. The action can either be triggered once, by setting the interval property to happen AT the set amount of successful login attempts; or set to occur EVERY time the specified number of additional successful login attempts occur. This requires integration with IDM to work, and is used in conjunction with the "Increment Login Count Node". The Increment Login Count Node needs to be present in your login authentication flow for the Login Count Decision Node to have the data necessary to trigger a decision.

Properties:

PropertyUsage
Interval The type of interval the decision should trigger on. Valid types are every and at. Every refers to a recurring action that happens every specified number of successful logins, such as prompting a user to update their contact information every 30 days. At refers to an action that occurs once, after the specified number of successful logins. For example, prompting the user to set their communication preferences once they have logged in 10 times.
Amount The amount (count) of logins the interval should trigger on.
Identity Attribute The attribute used to identify the object in IDM.

Contextual Authentication Nodes

Use the following nodes to examine the authentication context and act on it:

Certificate Collector Node

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

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

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

Properties:

PropertyUsage
Certificate Collection Method

Specifies how AM should collect the certificate from the request. Possible values are:

  • Request. AM looks for the certificate in the request. Use this value if TLS termination happens at the container where AM runs.

  • Header. AM looks for the certificate in the HTTP header name specified in the HTTP Header Name for the Client Certificate property. Use this value if TLS termination happens in a proxy or load balancer placed in front of the container where AM runs.

  • Either. AM looks for the certificate in the request; if it cannot find it, AM looks for the certificate in the HTTP header specified in the HTTP Header Name for the Client Certificate property.

Default: Either

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 Header or Either.

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

If no value is specified, AM will reject certificates supplied by remote hosts. If you specify the any value, AM will trust certificates on behalf of the authenticating client supplied by any remote host.

Default: No value specified.

Certificate Validation Node

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

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

  • True: The node could validate the certificate.

  • False: The node could not validate the certificate. The node will use this path when it cannot validate the certificate but the cause is not managed by any of the other outcomes.

  • 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 rhe certificate has been revoked.

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

Properties:

PropertyUsage
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 will use to search the LDAP directory for the certificate. The search filter will also use the value of the Subject DN as it appears in the certificate.

Default: CN

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 will use to find the CRL in the LDAP directory.

If only one attribute is specified, the LDAP search filter used is (attr-name=attr-value-in-subject-DN).

For example, if the subject DN of the issuer certificate is C=US, CN=Some CA, serialNumber=123456, and the attribute specified is CN, then the LDAP search filter used to find the CRL is (CN=Some CA).

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 (cn=attr1=attr1-value-in-subject-DN,attr2=attr2-value-in-subject-DN,..., and so on.

For example, if the subject DN of the issuer certificate is C=US, CN=Some CA, serialNumber=123456, and the attributes specified are CN,serialNumber, then the LDAP search filter used to find the CRL is (cn=CN=Some CA,serialNumber=123456).

Default: CN

HTTP Parameters for CRL Update

Specifies parameters that AM will include 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,param1=value1,param2=value2.

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 IssuingDistributionPoint or the CRLDistributionPoint extensions.

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 by going to 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 ldap_server:port format.

AM servers can be associated with LDAP servers by writing multiple chains with the format openam_server|ldapserver:port. For example, openam.example.com|ldap1.example.com:636.

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 dc=example,dc=com. To associate AM servers with different search base DNs, use the format am_server|base_dn. For example, openam.example.com|dc=example,dc=com openam1.test.com|dc=test, dc=com.

LDAP Server Authentication User

Specifies the DN of the service account that AM will use to authenticate to the LDAP that holds the certificates. For example, cn=LDAP User.

Default: cn=Directory Manager

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.

Certificate User Extractor Node

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

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

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

Properties:

PropertyUsage
Certificate Field Used to Access User Profile

Specifies the field in the certificate that AM will use to search for the user in the identity store. Possible values are:

  • Subject DN

  • Subject CN

  • Subject UID

  • Email Address

  • Other

  • None

If you select Other, provide an attribute name in the Other Certificate Field Used to Access User Profile property.

Select None if you want to specify an alternate way of looking up the user profile in the SubjectAltNameExt Value Type to Access User Profile property.

Default: Subject CN

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. Possible values are:

  • None. AM uses the value specified in the Certificate Field Used to Access User Profile or the Other Certificate Field Used to Access User Profile properties when looking up the user profile.

  • RFC822Name. AM looks up for the user profile using the value of the RFC822Name field.

  • UPN. AM looks up the user profile as the User Principal Name attribute used in Active Directory.

Default: None

Device Profile Collector

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

The Device Profile Collector authentication node sends a DeviceProfileCallback callback. For more information, see "Interactive Callbacks".

Important

The AM XUI user interface does not support completing the callback that this node uses.

Support for the callback this node uses is provided by:

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 tree's 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 tree's shared state, in a variable named forgeRock.device.location.

Important

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

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

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

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

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

Properties:

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

Collect Device Metadata

Specifies whether device metadata is requested.

Collect Device Location

Specifies whether device location is requested.

Message

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

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

Messages provided in the node override the defaults provided by AM. For information about customizing and translating the default messages, see Internationalization.

Device Match

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

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

You can choose between two methods of comparison:

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

  2. Custom Matching

    Create scripts to do the comparison of captured device data against trusted device profiles.

    AM includes a template script that you can customize to your requirements. Go to Realms > Realm Name > Scripts, and then 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 in the tree before attempting to match device profiles.

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

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

Properties:

PropertyUsage
Acceptable Variance

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

Expiration

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

Use Custom Matching Script

Specifies whether to use a custom script to compare the collected metadata with saved device profiles. The script type has to be Decision node script for authentication trees.

Note

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

Custom Matching Script

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

Only scripts of type Decision node script for authentication trees appear in the list.

Device Profile Save

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

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

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

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

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

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

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

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

Properties:

PropertyUsage
Device Name Variable

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

Maximum Saved Profiles

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

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

Save Device Metadata

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

Save Device Location

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

Device Profile Location Match

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

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

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

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

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

Properties:

PropertyUsage
Maximum Radius (km)

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

The distance is calculated point-to-point.

Device Geofencing

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

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

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

Properties:

PropertyUsage
Trusted Locations

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

Geofence Radius (km)

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

The distance is calculated point-to-point.

Device Tampering Verification

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

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

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

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

Properties:

PropertyUsage
Score Threshold

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

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

Note

Emulators score the maximum; 1.

Federation Authentication Nodes

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

OAuth 2.0 Node

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

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

Properties:

PropertyUsage
Client ID

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

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

Example: https://accounts.google.com/o/oauth2/v2/auth

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

Example: https://www.googleapis.com/oauth2/v4/token

User Profile Service URL

Specifies the user profile URL that returns profile information.

Exaple: https://www.googleapis.com/oauth2/v3/userinfo

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 as required by the identity provider, for example 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

Specifies the delimiter used to separate scope values.

Some authorization servers use non-standard separators for scopes, for example commas.

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, https://openam.example.com:8443/openam/XUI/.

Social Provider

Specifies the name of the social provider for which this module is being set up.

Example: Google

Auth ID Key

Specifies the attribute the social identity provider uses to identify an authenticated individual.

Example: id

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Default: true

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

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.

Provided implementations are:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

The Account Mapper classes can take two constructor parameters: a comma-separated list of attributes and a prefix to apply to their values. For example, to prefix all received property values with facebook- before searching, specify:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook-

Attribute Mapper

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:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

The Attribute Mapper classes can take two constructor parameters: a comma-separated list of attributes and a prefix to apply to their values, to help differentiate between the providers. For example, to prefix all incoming values with facebook-, specify:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook-

Be aware however using an asterisk applies the prefix to all values, including email addresses, postal addresses, and so on.

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 provider-attr=local-attr.

Examples: email=mail and id=facebook-id.

Tip

When using the org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper class, you can parse JSON objects in mappings, by using dot notation.

For example, given a JSON payload of:

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

You can create a mapper such as:

name.first_name=cn

Attribute Mapper Configuration

Map of OAuth 2.0 provider user account attributes to local user profile attributes, with values in the form provider-attr=local-attr.

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.

Tip

When using the org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper class, you can parse JSON objects in mappings, by using dot notation.

For example, given a JSON payload of:

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

You can create a mapper such as:

name.first_name=cn

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 in the iss response parameter. If they do not match, the client must abort the authorization process. The client must also confirm that the authorization server's response is intended for the client by comparing the client's client identifier to the value of the client_id response parameter.

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 will contain an issuer value (iss) that will be validated by the client.

Note

Consult with the authorization server's documentation on what value it uses for the issuer field.

For more information, see section 4 of OAuth 2.0 Mix-Up Mitigation Draft.

Token Issuer

Corresponds to the expected issuer identifier value in the iss field of the ID token.

Example: https://accounts.google.com

OpenID Connect Node

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

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

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

Properties:

PropertyUsage
Client ID

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

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

Example: https://accounts.google.com/o/oauth2/v2/auth

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

Example: https://www.googleapis.com/oauth2/v4/token

User Profile Service URL

Specifies the user profile URL that returns profile information.

If not specified, attributes are mapped from the claims returned by the id_token, and no call to a user profile endpoint is made.

Exaple: https://www.googleapis.com/oauth2/v3/userinfo

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 as required by the identity provider, for example 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 https://openam.example.com:8443/openam/XUI/.

Social Provider

Specifies the name of the OpenID Connect provider for which this node is being set up.

Example: Google

Auth ID Key

Specifies the attribute the social identity provider uses to identify an authenticated individual.

Example: sub

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Default: true

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

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 org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper.

The Account Mapper classes can take two constructor parameters: a comma-separated list of attributes and a prefix to apply to their values. For example, to prefix all received property values with openid- before searching, specify:

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 org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper.

The Attribute Mapper classes can take two constructor parameters: a comma-separated list of attributes and a prefix to apply to their values, to help differentiate between the providers. For example, to prefix incoming iplanet-am-user-alias-list values with openid-, specify:

org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|iplanet-am-user-alias-list|openid-

To prefix all incoming values use an asterisk (*) as the attribute list. Note that an asterisk prefixes all values, including email addresses, postal addresses, and so on.

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 the Add button, then specify sub in the Key field and iplanet-am-user-alias-list in the Value field, and then click the Plus button ().

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 the Add button, then specify id in the Key field and facebook-id in the Value field, and then click the Plus button ().

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 in the iss response parameter. If they do not match, the client must abort the authorization process. The client must also confirm that the authorization server's response is intended for the client by comparing the client's client identifier to the value of the client_id response parameter.

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 will contain an issuer value (iss) that will be validated by the client.

Note

Consult with the authorization server's documentation on what value it uses for the issuer field.

For more information, see section 4 of OAuth 2.0 Mix-Up Mitigation Draft.

Token Issuer

Corresponds to the expected issuer identifier value in the iss field of the ID token.

Example: https://accounts.google.com

OpenID Connect Validation Type

Specifies how to validate the ID token received from the OpenID Connect provider. AM ignores keys specified in JWT headers, such as jku and jwe; the following options are available to validate an incoming OpenID Connect ID token:

Well Known URL (Default)

Retrieves the provider's keys based on the information provided in its OpenID Connect configuration URL.

Specify the provider's configuration URL in the OpenID Connect Validation Value field, for example https://accounts.google.com/.well-known/openid-configuration.

Client Secret

Validates the ID token signature with a specified client secret key.

Specify the key to use in the OpenID Connect Validation Value field.

JWK URL

Retrieve the necessary JSON web key from the URL that you specify.

Specify the provider's JWK URI in the OpenID Connect Validation Value field, for example https://www.googleapis.com/oauth2/v3/certs.

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

The Provision Dynamic Account node provisions an account following successful authentication by a social identity provider node, or a SAML2 authentication node. Accounts are provisioned using properties defined in the attribute mapper configuration of a social authentication or SAML2 authentication node earlier in the tree evaluation; for example, the OAuth 2.0 Node.

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

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

Properties:

PropertyUsage
Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

Example:

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

Google-DynamicAccountCreation Tree With Provision Dynamic Account Node
Google-DynamicAccountCreation tree showing Provision Dynamic Account node usage.

Provision IDM Account Node

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

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

For information on using IDM for provisioning, see the Platform Setup Guide.

Properties:

PropertyUsage
Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

Example:

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

Facebook-ProvisionIDMAccount Tree With Provision IDM Account Node
Facebook-ProvisionIDMAccount tree showing Provision IDM Account node usage.

SAML2 Authentication Node

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

Important

SLO is not supported, even though the UI has an option to enable it.

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

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, as described in the example below.

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

Properties:

PropertyUsage
IdP Entity ID

Specifies the name of the remote IdP.

SP MetaAlias

Specifies the local alias for the SP, in the format /Realm Name/SP Name.

Allow IdP to Create NameID

Specifies whether the IdP should create a new identifier for the authenticating user if none exists.

For detailed information, see the section on the AllowCreate property in SAML Version 2.0 Errata 05.

Default: Enabled

Comparison Type

Specifies a comparison method to evaluate authentication context classes or statements. The value specified in this property overrides the value set in the SP configuration under Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context > Comparison Type.

Valid comparison methods are exact, minimum, maximum, or better.

For more information about the comparison methods, see the section on the <RequestedAuthnContext> element in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

Default: minimum

Authentication Context Class Reference

(Optional) Specifies one or more URIs for authentication context classes to be included in the SAML request.

They are unique identifiers for an authentication mechanism. The SAML v2.0 protocol supports a standard set of authentication context classes, defined in Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0. In addition to the standard authentication context classes, you can specify customized authentication context classes.

Any authentication context class that you specify in this field must be supported for the service provider.

Go to Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context.

When specifying multiple authentication context classes, use the | character to separate the classes. For example:

urn:oasis:names:tc:SAML:2.0:ac:classes:Password|urn:oasis:names:tc:SAML:2.0:ac:classes:TimesyncToken
Authentication Context Declaration Reference

(Optional) Specifies one or more URIs that identify authentication context declarations.

When specifying multiple URIs, use the | character to separate the URIs.

For more information, see the section on the <RequestedAuthnContext> element in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

Request Binding

Specifies the format the SP will use to send the authentication request to the IdP.

Valid values are HTTP-Redirect and HTTP-POST.

Default: HTTP-Redirect

Response Binding

Specifies the format the IdP will use to send the response to the SP.

Valid values are HTTP-POST and HTTP-Artifact.

Default: HTTP-Artifact

Force IdP Authentication

Specifies whether the IdP forces authentication or if it can reuse existing security contexts.

Default: Disabled

Passive Authentication

Specifies whether the IdP uses passive authentication or not. Passive authentication requires the IDP to only use authentication methods that do not require user interaction. For example, authenticating using an X.509 certificate.

Default: Disabled

NameID Format

Specifies the SAML name ID format that will be requested in the SAML authentication request. For example:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Default: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

Single Logout Enabled

Not implemented.

Single Logout URL

Not implemented.

Example:

The following example federates to a remote IdP, and dynamically provisions an account for the user in the SP if one does not exist:

Example Tree With SAML2 Authentication Node
Example Tree With SAML2 Authentication Node

To create a persistent link with an existing account in the SP, see the "Write Federation Information Node".

Social Facebook Node

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

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

Properties:

PropertyUsage
Client ID

Specifies the client_id parameter as provided by Facebook.

Client Secret

Specifies the client_secret parameter as provided by Facebook.

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: https://www.facebook.com/dialog/oauth

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: https://graph.facebook.com/v2.12/oauth/access_token

User Profile Service URL

Specifies the user profile URL that returns profile information.

Default: https://graph.facebook.com/v2.6/me?fields=name%2Cemail%2Cfirst_name%2Clast_name

OAuth Scope

Specifies a comma-separated list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749) . 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 Facebook after authenticating, to continue the authentication tree flow.

Set this property to the URL of the AM UI. For example, https://openam.example.com:8443/openam/XUI/.

Tip

If the tree is not in the Top Level Realm, you can specify the realm in the redirect URL. Use a DNS alias for the realm, or add the realm as a query parameter, for example https://openam.example.com:8443/openam/XUI/?realm=/mySubRealm.

For more information, see "To Configure DNS Aliases for Accessing a Realm".

Social Provider

Specifies the name of the social provider for which this node is being set up.

Default: facebook

Auth ID Key

Specifies the attribute the social identity provider uses to identify an authenticated individual.

Default: id

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Default: true

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

Account Mapper

Specifies the name of the class that implements the method of locating local accounts based on the attributes returned from Facebook.

Default:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from Facebook to AM profile attributes.

Default:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|uid|facebook-

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 provider-attr=local-attr.

Default: id=uid.

Tip

When using the org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper class, you can parse JSON objects in mappings, by using dot notation.

For example, given a JSON payload of:

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

You can create a mapper such as:

name.first_name=cn

Attribute Mapper Configuration

Map of Facebook user account attributes to local user profile attributes, with values in the form provider-attr=local-attr.

Default: name=cn, last_name=sn, id=uid, first_name=givenname, email=mail.

Tip

When using the org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper class, you can parse JSON objects in mappings, by using dot notation.

For example, given a JSON payload of:

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

You can create a mapper such as:

name.first_name=cn

Save attributes in the session

When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session.

Default: true.

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 in the iss response parameter. If they do not match, the client must abort the authorization process. The client must also confirm that the authorization server's response is intended for the client by comparing the client's client identifier to the value of the client_id response parameter.

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 will contain an issuer value (iss) that will be validated by the client.

Note

Consult with the authorization server's documentation on what value it uses for the issuer field.

For more information, see section 4 of OAuth 2.0 Mix-Up Mitigation Draft.

Token Issuer

Corresponds to the expected issuer identifier value in the iss field of the ID token.

Example: https://graph.facebook.com

Example:

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

Facebook-ProvisionIDMAccount Tree With Provision IDM Account Node
Facebook-ProvisionIDMAccount tree showing Provision IDM Account node usage.

Social Google Node

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

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

Properties:

PropertyUsage
Client ID

Specifies the client_id parameter as provided by Google.

Client Secret

Specifies the client_secret parameter as provided by Google.

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: https://accounts.google.com/o/oauth2/v2/auth

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: https://www.googleapis.com/oauth2/v4/token

User Profile Service URL

Specifies the user profile URL that returns profile information.

Default: https://www.googleapis.com/oauth2/v3/userinfo

OAuth Scope

Specifies a space-separated list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749) . The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Default: profile email.

Redirect URL

Specifies the URL the user is redirected to by Google after authenticating, to continue the authentication tree flow.

Set this property to the URL of the AM UI. For example, https://openam.example.com:8443/openam/XUI/.

Tip

If the tree is not in the Top Level Realm, you can specify the realm in the redirect URL. Use a DNS alias for the realm, or add the realm as a query parameter, for example https://openam.example.com:8443/openam/XUI/?realm=/mySubRealm.

For more information, see "To Configure DNS Aliases for Accessing a Realm".

Social Provider

Specifies the name of the social provider for which this node is being set up.

Default: google

Auth ID Key

Specifies the attribute the social identity provider uses to identify an authenticated individual.

Default: sub

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to Google.

Default: true

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

Account Mapper

Specifies the name of the class that implements the method of locating local accounts based on the attributes returned from Google.

Default:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from Google to AM profile attributes.

Default:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|iplanet-am-user-alias-list|google-

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 provider-attr=local-attr.

Default: sub=uid.

Tip

When using the org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper class, you can parse JSON objects in mappings, by using dot notation.

For example, given a JSON payload of:

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

You can create a mapper such as:

name.first_name=cn

Attribute Mapper Configuration

Map of Google user account attributes to local user profile attributes, with values in the form provider-attr=local-attr.

Default: sub=uid, name=cn, given_name=givenName, family_name=sn, email=mail.

Tip

When using the org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper class, you can parse JSON objects in mappings, by using dot notation.

For example, given a JSON payload of:

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

You can create a mapper such as:

name.first_name=cn

Save attributes in the session

When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session.

Default: true.

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 in the iss response parameter. If they do not match, the client must abort the authorization process. The client must also confirm that the authorization server's response is intended for the client by comparing the client's client identifier to the value of the client_id response parameter.

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 will contain an issuer value (iss) that will be validated by the client.

Note

Consult with the authorization server's documentation on what value it uses for the issuer field.

For more information, see section 4 of OAuth 2.0 Mix-Up Mitigation Draft.

Token Issuer

Corresponds to the expected issuer identifier value in the iss field of the ID token.

Example: https://accounts.google.com

Example:

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

Google-AnonymousUser Tree With Anonymous User Mapping Node
Google-AnonymousUser tree showing Anonymous User Mapping node usage.

Social Ignore Profile Node

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

Properties:

This node has no configurable properties.

Social Provider Handler Node

This node is used alongside the "Select Identity Provider Node" to enable use of the platform's Social Identity Provider Service (located in AM). It takes the provider selection from the Select Identity Provider node and attempts to authenticate the user with that provider. It then collects relevant profile information from the provider and returns the user to the login or registration flow, and transforms that profile information into attributes the platform can use. The default transformation script can be found and edited in AM, by navigating to your Realm dashboard, selecting Scripts, then opening the Normalized Profile to Managed User script.

Properties:

PropertyUsage
Transformation Script A script that can transform a normalized social profile to object data.
Username Attribute The attribute in IDM that contains the username for this object.

Write Federation Information Node

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

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

Properties:

This node has no configurable properties.

Example:

Connect the Write Federation Information node to the tree branch that collects and validates the end user's login information in the SP.

Example Tree With Write Federation Information Node
Example Tree With Write Federation Information Node

Identity Management Authentication Nodes

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

Accept Terms and Conditions Node

This node prompts the user to accept the currently active Terms and Conditions. It requires that you configure AM as part of a ForgeRock Identity Platform deployment. The node is used in a registration tree, or combined with the "Terms and Conditions Decision Node" in a progressive profile or login tree.

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

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

Properties:

This node has no configurable properties.

Example:

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

Example Tree With Accept Terms and Conditions Node
Example tree showing Accept Terms and Conditions node usage.

Anonymous User Mapping Node

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

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

Properties:

PropertyUsage
Anonymous User Name

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

Example:

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

Google-AnonymousUser Tree With Anonymous User Mapping Node
Google-AnonymousUser tree showing Anonymous User Mapping node usage.

Anonymous Session Upgrade Node

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

Properties:

This node has no configurable properties.

Example:

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

Example Tree With Anonymous Session Upgrade Node
Example tree showing Anonymous Session Upgrade node usage.

Attribute Collector Node

The Attribute Collector node is used to collect the values of attributes for use elsewhere in a tree, such as collecting user information to populate a new account in a registration tree. This node relies on integration with IDM, and supports three types of attributes: string, boolean, and number. The node configuration allows the admin to specify if the attributes are required to continue, and if they should be subject to validation through IDM's policy filter.

Properties:

PropertyUsage
Attributes to Collect A list of the attributes you wish to collect, based on the attributes found in the IDM schema for the chosen object type.
All Attributes Required When enabled, all attributes collected in this node are required in order to continue.
Validate Input When enabled, the content input in this node should be validated against IDM policy settings specified in the IDM schema.
Identity Attribute The attribute used to identify the object in IDM.

Attribute Present Decision Node

Checks if an attribute is present on an object, regardless of whether the field is private. Use this to verify an attribute is present, without needing to know the value of the attribute itself. A good example of this is during an update password flow, where you want to check if the account has a password (rather than no password and logging in through a social identity) before continuing. This node is similar to the "Attribute Value Decision Node" when that node is set to use the PRESENT operator, except it cannot return the value of the attribute, and can work on private attributes.

Properties:

PropertyUsage
Present Attribute The object attribute to verify is present in the IDM object. This can be an otherwise private attribute, such as password.
Identity Attribute The attribute used to identify the object in IDM.

Attribute Value Decision Node

Verifies that the user's specified attribute satisfies a specific condition. Use this node to check whether an attribute's expected value is equal to a collected attribute value, or to validate that a specified attribute has been collected (regardless of the value of that attribute). For example, if you wish to validate that a user filled out the country attribute when registering, set the comparison operation to PRESENT, and the comparison attribute to country. If you instead need to ensure the country attribute is set to the United States, set the comparison operation to EQUALS, the comparison attribute to country, and the comparison value to United States.

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

This node requires integration with IDM to function.

Properties:

PropertyUsage
Comparison Operation The operation to perform on the object attribute; PRESENT checks for existence of an attribute, EQUALS checks if the object's attribute value equals the configured comparison value.
Comparison Attribute The object attribute to compare.
Comparison Value This property is only relevant when using the EQUALS comparison operation, and is the value to compare the object's attribute value to.
Identity Attribute The attribute used to identify the object in IDM.

Create Object Node

The Create Object node is used to create a new object in IDM based on information collected during an auth tree flow, such as user registration. Any managed object attributes that are marked as required in IDM will need to be collected during the auth tree flow in order for the new object to be created. This node requires IDM integration to function.

Properties:

PropertyUsage
Identity Resource The type of managed object in IDM that this node will create. This needs to match the identity resource for the current tree.

Create Password Node

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

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

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

Note

You must not place any nodes that request additional input from the user between the Create Password node and the provisioning node, otherwise the password will be lost.

Properties:

PropertyUsage
minPasswordLength

Specifies the minimum number of characters the password must contain.

Example:

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

Google-DynamicAccountCreation Tree With Create Password Node
Google-DynamicAccountCreation tree showing Create Password node usage.

Display Username Node

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

Properties:

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

Identify Existing User Node

This node verifies a user exists based on an identifying attribute, such as an email address, then makes the value of a specified attribute available in a tree's shared state. For example, use this node in a "Forgot Username" flow to fetch a username to email to the user. If you want to display the username on screen, use the "Display Username Node" instead. The Identify Existing User node requires IDM integration to function.

Properties:

PropertyUsage
Identifier The attribute to collect from an IDM object.
Identity Attribute The attribute used to identify the object in IDM. Since this node is generally used for recovering a username, the identity attribute in this case should be some other attribute that is unique to a user object, such as the user's email address.

KBA Decision Node

The KBA Decision node is used to check if the minimum number of KBA questions required by the system are defined for the user. This node relies on integration with IDM; the number of KBA questions is determined by the minimumAnswersToDefine property in selfservice.kba.json in IDM. This node is mainly used for Progressive Profile completion.

Properties:

PropertyUsage
Identity Attribute The attribute used to identify the object in IDM.

KBA Definition Node

The KBA Definition node collects KBA questions and answers from the user and saves them to the user object. This is used when creating or updating a user with Knowledge-Based Authentication enabled. For more information, see Configure Security Questions in the Platform Self-Service Guide.

Properties:

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

KBA Verification Node

The KBA Verification node presents KBA questions to the user, collects answers to those questions, and verifies the input against the user's stored answers. This is used during self-service actions such as Forgot Password or Forgot Username, where additional authentication is needed. This node relies on integration with IDM; the number of KBA questions is determined by the minimumAnswersToVerify property in selfservice.kba.json in IDM.

Properties:

PropertyUsage
KBA Attribute The IDM object attribute in which KBA questions and answers are stored.
Identity Attribute The attribute used to identify the object in IDM.

Patch Object Node

The Patch Object node is used to update attributes in an existing managed object in IDM. This is used in cases such as progressive profile completion, where you may wish to collect additional profile data from a user after they have logged in several times. This node requires integration with IDM to function.

Properties:

PropertyUsage
Patch as Object Allows patching as the object being updated. Enable this property to patch a user object as part of the user's current session, such as when updating their password.
Ignored Fields Fields from the tree's shared state that should be ignored as part of patch. If this is empty, all fields in sharedState are attempted as part of the patch. Use this to keep your patch focused only on the fields you want to update.
Identity Resource The type of managed object in IDM that this node will patch. This needs to match the identity resource for the current tree.
Identity Attribute The attribute used to identify the object to update in IDM.

Platform Password Node

Similar to the "Password Collector Node", this node prompts the user to enter their password. Instead of being transient, however, the input is stored in a configurable state attribute. Use this node instead of the Password Collector node when working with AM and IDM as an integrated platform. The Platform Password node requires IDM integration to function.

Properties:

PropertyUsage
Validate Password When enabled, this node checks the user's input against IDM's password policies, and returns any policy failures as errors. For example, if you submitted an invalid password on registration, the response from this node would include a list of failed policies:
{
    "name": "failedPolicies",
    "value": [
        "{ \"params\": { \"minLength\": 8 },
           \"policyRequirement\": \"MIN_LENGTH\" }",
        "{ \"params\": { \"numCaps\": 1 },
           \"policyRequirement\": \"AT_LEAST_X_CAPITAL_LETTERS\" }",
        "{ \"params\": { \"numNums\": 1 },
           \"policyRequirement\": \"AT_LEAST_X_NUMBERS\" }"
    ]
},
Password Attribute The attribute used to store a password in the IDM object.

Platform Username Node

Similar to the "Username Collector Node", this node prompts the user to enter their username. The input is stored in a configurable state attribute. Use this node instead of the Username Collector node when working with AM and IDM as an integrated platform. The Platform Username node requires IDM integration to function.

Properties:

PropertyUsage
Validate Username When enabled, this node checks the user's input against IDM's username policies, and returns any policy failures as errors.
Username Attribute The attribute used to store a username in the IDM object.

Profile Completeness Decision Node

The Profile Completeness Decision node is used in progressive profile flows. It checks how much of a user's profile has been filled out, where the completeness of a profile is expressed as a percentage of user-viewable, user-editable fields that aren't null. This node requires integration with IDM to function.

Properties:

PropertyUsage
Profile Completeness Threshold Percentage of user-viewable and user-editable fields in a profile that need to be filled out for the node to pass. Expressed as a number between 0 and 100.
Identity Attribute The attribute used to identify the object in IDM.

Query Filter Decision Node

Checks if the contents of a user's profile matches a specified query filter. Use this to verify whether a particular field has been filled out, or that the contents of a field match a specific pattern. For instance, use this in progressive profile flows to check if marketing preferences are set on a user's profile. For more information on constructing effective query filters, see Construct Queries in the IDM Object Modeling Guide.

This node requires integration with IDM to function.

Properties:

PropertyUsage
Query Filter A query filter used to check the contents of an object.
Identity Attribute The attribute used to identify the object that will be queried in IDM.

Required Attributes Present Node

The Required Attributes Present node checks the specified identity resource in IDM (by default, managed/user), and determines if all attributes required to create the specified object exist within shared state of the tree. This node is meant for use with the platform, and requires integration with IDM to function.

Properties:

PropertyUsage
Identity Resource The type of managed object in IDM that this node checks for required attributes. This needs to match the identity resource for the current tree.

Select Identity Provider Node

This node is used in combination with the "Social Provider Handler Node" to enable use of the platform's Social Identity Provider Service (found in AM). It presents the user with a list of configured, enabled, social identity providers to use for authentication. It can also be configured to only show identity providers the user has already associated with their account, such as in account claiming flows, where a user wishes to associate a new social identity provider with an account that is being authenticated with social authentication.

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

Properties:

PropertyUsage
Include local authentication Determines whether local authentication will be included as an available method for authenticating.
Offer only existing providers Enable this when the social identity provider choices offered should be limited to those already associated with a user object. Use this when a user is authenticating using a new social identity provider, and an account associated with that user already exists (also known as "account claiming").
Password attribute The attribute in the user object that stores a user's password, for use during local authentication.
Identity Attribute The attribute used to identify an existing user. Required to support the offer of only existing providers.

Terms and Conditions Decision Node

This node verifies that the user has accepted the active set of Terms and Conditions. It requires that you configure AM as part of a ForgeRock Identity Platform deployment. Use this node when you want to verify that a user has accepted your Terms and Conditions before proceeding (such as logging in, or in a progressive profile tree). The node is often used with the "Accept Terms and Conditions Node".

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

Properties:

PropertyUsage
Identity Attribute The attribute used to identify the object to check in IDM.

Time Since Decision Node

Checks if a specified amount of time has passed since the user was registered. For example, if you wanted to prompt users to review your terms and conditions after the account is a week old, you could set the Elapsed Time property to 10080 minutes. After that time has elapsed, the next time the user logs in, they will be prompted to review your terms and conditions. This node is mainly used for Progressive Profile completion, and requires integration with IDM to work.

Properties:

PropertyUsage
Elapsed Time

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

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

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

Utility Authentication Nodes

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

Agent Data Store Decision Node

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

Note

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

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

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

Properties:

This node has no configurable properties.

Choice Collector Node

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

Outcomes

  • Choice 1

    ...

  • Choice n

Properties

PropertyUsage
Choices

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

To remove a choice, select its Delete icon (x). 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.

Important

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

Prompt (required)Enter the prompt string to display to the user when presenting the choices.

Email Suspend Node

The Email Suspend node is used to generate and send an email to a user, such as an address verification email, based on an email template in IDM. The authentication tree will pause until the user clicks a link in the email to resume the tree flow. The link is generated by the Email Suspend node, and is passed along to IDM as part of the email object, in a property called resumeURI.

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

Properties:

PropertyUsage
Email Template Name The name of the IDM email template to be sent. Check IDM for the names of available email templates, or to create a new template.
Email Attribute The IDM attribute storing the address to send the email to.
Email Suspend Message The localized message to be returned once the tree is suspended. The default message is "An email has been sent to your inbox."
Object Lookup Determines whether the object should be looked up in IDM. If true, IDM is queried for an existing object. Otherwise, the object in the authentication tree's shared state is used. For example, if suspending a user registration flow before the user object is created in IDM, this should be set to false. If the registration flow has already created the new user object when the flow is suspended, then this should be set to true.
Identity Attribute The attribute used to identify the object in IDM.

Email Template Node

The Email Template node is used to generate and send an email to a user, such as a welcome email, based on an email template in IDM. This node relies on integration with IDM; it uses the email service configured in IDM to send email. If you need the auth tree to pause and wait for a response from email, use the "Email Suspend Node" instead.

Note

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

Properties:

PropertyUsage
Email Template Name The name of the IDM email template to be sent. Check IDM for the names of available email templates, or to create a new template.
Email Attribute The IDM attribute storing the address to send the email to.
Identity Attribute The attribute used to identify the object in IDM.

Failure URL Node

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

Note

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

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

Tip

The URL is also saved into the sharedState object, under a property named failureUrl, which can be useful for custom node developers. For more information, see "Customizing Authentication Trees".

Properties:

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

Get Session Data Node

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

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

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

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

Example:

The following table includes example keys that may be available in an existing session, and sample data that they might contain:

Get Session Data Example Keys and Values
KeySample value
AMCtxIde370cca2-02d6-41f9-a244-2b107206bd2a-122934
amlbcookie01
authInstant2018-04-04T09:19:05Z
AuthLevel0
CharSetUTF-8
clientTypegenericHTML
FullLoginURL/openam/XUI/?realm=alpha#login/
Host198.51.100.1
HostNameopenam.example.com
Localeen_US
Organizationdc=openam,dc=forgerock,dc=org
Principaluid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org
PrincipalsamAdmin
ServiceldapService
successURL/openam/console
sun.am.UniversalIdentifieruid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org
UserIdamAdmin
UserProfileRequired
UserTokenamAdmin
webhooksmyWebHook

Properties:

PropertyUsage
Session Data Key Specify the name of a key in the user's session data from which to retrieve the value.
Shared State Key Specify the name of a key in the sharedState object in which to store the retrieved value.

Inner Tree Evaluator Node

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

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

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

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

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

Properties:

PropertyUsage
Tree name Enter the name of the tree to evaluate.

Message Node

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

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

Properties:

PropertyUsage
Message

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

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

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

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

Positive answer

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

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

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

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

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

Negative answer

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

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

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

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

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

Example:

Meter Node

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

Properties:

PropertyUsage
Metric Key Specify the name of a metric to increment when tree evaluation passes through the node.

Page Node

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

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

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

PropertyUsage
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.
Description Optional. A localized description for the page node and the nodes contained within it. Use this when additional descriptive text is needed in an authentication flow.
Stage Optional. This is used in UI development, to help identify what node or series of nodes are being returned so they can be rendered in the UI appropriately.

Note

The Page Node's optional properties are passed in the response, but the UI needs to support these properties before they will be visible to the end user.

Example:

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

Example Tree With Page Node
Example tree showing Page node usage.

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

User View of Example Tree with Page Node
User's view of an example tree containing a page node.

Polling Wait Node

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

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

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

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

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

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

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

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

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

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

Properties:

PropertyUsage
Seconds To Wait

Specify the number of seconds to pause the authentication tree.

Default: 8

Enable Spam Detection

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

Default: Disabled

Spam Tolerance

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

Default: 3

Waiting Message

Specifies the optional message to display to the user.

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

Messages provided in the node override the defaults provided by AM. For information about customizing and translating the default messages, see Internationalization.

Exitable

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

Default: Disabled

Exit Message

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

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

Messages provided in the node override the defaults provided by AM. For information about customizing and translating the default messages, see Internationalization.

Register Logout Webhook Node

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

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

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

Properties:

PropertyUsage
Webhook name Specify the name of the webhook to register.

Remove Session Properties Node

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

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

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

Properties:

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

Retry Limit Decision Node

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

Properties:

PropertyUsage
Retry limit

Specify the number of times to allow a retry.

Default: 3

Save Retry Limit to User

(Introduced in AM 7.0.2) Specify whether the number of failed login attempts persists between successful authentications. Possible values are:

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

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

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

    Important

    After upgrading to AM 7.0.2 or later, you must update the identity store's schema manually before enabling this feature.

    To update the identity store schema for the Retry Limit Decision Node, perform the following steps:

    1. Change directories to the path where you deployed the openam.war file. For example, /path/to/tomcat/webapps/openam.

    2. Locate the opendj_retry_limit_node_count.ldif file in the WEB-INF/template/ldif/opendj path.

    3. Update the identity store schema using the LDIF file. For example:

      $ /path/to/opendj/bin/ldapmodify \
      --hostname 'id.example.com' \
      --port 1636 \
      --useSsl \
      --usePkcs12TrustStore /path/to/opendj/config/keystore \
      --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
      --continueOnError \
      --bindDN uid=admin \
      --bindPassword str0ngAdm1nPa55word \
      /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_retry_limit_node_count.ldif

      Now you are ready to enable the Save Retry Limit to User switch in the "Retry Limit Decision Node".

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

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

Default: Disabled.

Example:

RetryLimit Tree
RetryLimit tree showing Retry Limit Decision node usage.

Scripted Decision Node

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

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

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

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

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

Properties:

PropertyUsage
Script Select the script to execute from the drop-down field.
Outcomes Enter the possible strings that can be assigned to the outcome variable by the script. These strings provide the possible outcome paths the tree can continue along.
Script Inputs A list of state inputs required by the script. Defaults to *.
Script Outputs A list of state outputs produced by the script. Defaults to *.

Set Session Properties Node

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

Tip

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

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

Properties:

PropertyUsage
Properties To add a session property, select the Add button, enter a key name and a value, and then select the plus icon. Repeat the steps to add multiple properties.

State Metadata Node

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

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

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

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

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

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

Properties:

PropertyUsage
Attributes

Specify one or more shared state attribute names for return.

Example:

State Metadata Tree (Standalone AM)
An example of OTP authentication with a State Metadata node.

State Metadata Tree (ForgeRock Identity Platform)
An example of OTP authentication with a State Metadata node.

Success URL Node

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

Note

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

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

Tip

The URL is also saved into the sharedState object, under a property named successUrl, which can be useful for custom node developers. For more information, see "Customizing Authentication Trees".

Properties:

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

Timer Start Node

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

Properties:

PropertyUsage
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 tree evaluation passed through this node.

Timer Stop Node

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

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

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

Properties:

PropertyUsage
Start Time Property Specify the property name containing the time from which to calculate the elapsed time.
Metric Key Specify the name of a metric in which to store the calculated elapsed time.

Thing Authentication Nodes

Use the following nodes to perform various tasks related to authenticating IoT things:

Authenticate Thing Node

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

Important

Support for this node is provided by the Thing SDK.

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

  • That the claims are valid.

  • That the thing is of a valid type.

  • That an identity with the same ID as the name of the JWT subject exists.

  • That the identity contains a confirmation key that matches the JWT's kid.

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

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

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

Properties:

This node has no configurable properties.

Examples:

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

Authenticating a Thing Without Registration
Authenticate a thing when an identity already exists and 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:

Authenticating a Thing With Registration
Authenticate a thing when an identity does not exist, or when it needs to refresh their confirmation key.

Register Thing Node

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

Important

Support for this node is provided by the Thing SDK.

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

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

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

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

Properties:

PropertyUsage
Verify Certificate Subject

Specifies whether to verify that the subject provided in the JWT is the same as the one specified in the CN or UID fields of the X.509 certificate.

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 one key per thing.

Default: Disabled

Claim to Attribute Mapping

When Create Identity is enabled, maps verified claims in the JWT to attributes in the new identity.

The key of the map is the claim name, and the value is the name of the attribute in the identity store.

Overwrite Attributes

Specifies whether the node will overwrite the value for an existing profile attribute when a claim with a different value is provided in the JWT.

Default: Disabled



[4] HTTPS may not be required when testing locally, on http://localhost, for example. For more information, see Is origin potentially trustworthy?.

Read a different version of :