Authentication node reference

Primary LDAP Server (required)

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

For example, directory_services.example.com:389.

Secondary LDAP Server

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

The journey uses the secondary servers when none of the primary servers are available.

For example, directory_services_backup.example.com:389.

DN to Start User Search (required)

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

If multiple entries with the same attribute values exist in the directory server, make sure this property is specific enough to return only one entry.

Bind User DN, Bind User Password

The credentials used to connect to the LDAP user data store.

Attribute Used to Retrieve User Profile (required)

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

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

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

The attributes the node uses to match the credentials provided by the user to an entry in the directory server.

For example, a value of uid forms the search filter uid=user. If you specify multiple values, such as uid and cn, the node forms a complex search filter (|(uid=user)(cn=user)).

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

User Search Filter

A filter to append to user searches.

For example, if your search attribute is mail and you set User Search Filter to (objectClass=inetOrgPerson), the node uses (&(mail=address)(objectClass=inetOrgPerson)) as the resulting search filter. In this example, address is the mail address provided by the user.

Search Scope

The extent of the search for users in the directory server:

Default: SUBTREE

LDAP Connection Mode

Specifies whether to use SSL or StartTLS to connect to the directory server. The node must be able to trust the certificates used.

Possible values: LDAP, LDAPS, and StartTLS

Default: LDAP

mTLS Enabled

Enables mTLS (mutual TLS) between AM and the directory server.

This setting applies to all configured LDAP servers; that is, AM uses mTLS to authenticate to all LDAP servers configured for this node.

When mTLS is enabled, AM ignores the values for Bind User DN and Bind User Password.

If you enable this property, you must:

Default: Disabled

mTLS Secret Label

Label used to create a secret ID for mapping to the mTLS certificate in the secret store. AM uses this label to create a specific secret ID for this node. The secret ID takes the form am.authentication.nodes.ldap.decision.mtls.label.cert , where label is the value of mTLS Secret Label. The label can only contain alphanumeric characters (a-z, A-Z, 0-9) and periods (.). It can’t start or end with a period. All LDAP servers configured for this node share the same secret label.

For more security, you should rotate certificates periodically. When you rotate a certificate, update the corresponding mapping in the realm secret store configuration to reflect this label. When you rotate a certificate, AM closes any existing connections using the old certificate. A new connection is selected from the connection pool and no server restart is required.

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

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

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, the server blindly trusts 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 doesn’t remain idle.

Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. Set the units for the interval in the LDAP Connection Heartbeat Time Unit property.

Default: 10

LDAP Connection Heartbeat Time Unit

The time unit for the LDAP Connection Heartbeat Interval.

Default: seconds

LDAP Operations Timeout

The timeout, in seconds, that AM should wait for a response from the directory server.

Default: 0 (means no timeout)

Use mixed case for password change messages

Specifies whether the server returns password change messages in mixed (sentence) case or transforms them to uppercase.

By default, the server transforms password reset and password change messages to uppercase. Enable this setting to return messages in sentence case.

Default: Disabled

Get App Authenticator Message

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

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

Continue Label

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

Apple App Store URL

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

Default: https://itunes.apple.com/app/forgerock-authenticator/id1038442926

Google Play URL

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

Default: https://play.google.com/store/apps/details?id=com.forgerock.authenticator

One-time password length

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

Default: 8

Remove 'skip' option

If checked, users can no longer skip the node and must interact with it.

Display Get Authenticator App

If enabled, display the Get the App button.

Message

Localized text to use as the title of the screen.

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

Register Device

Localized text to use on the Register Device button.

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

Get Authenticator App

Localized text to use on the Get Authenticator App button.

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

Skip this Step

Localized text to use on the Skip this Step button.

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

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

Opt-out

Localized text to use on the Opt-Out button.

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

Note that this node does not change the user’s profile. Connect the Opt-out outcome to an Opt-out Multi-Factor Authentication node to persist the option in the user’s profile.

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

Issuer

Specify an identifier to appear on the user’s device, such as a company name, a website, or an AM realm.

The authenticator application displays the value.

Account Name

Define the profile attribute to display as the username in the authenticator application.

If not specified, or if the specified profile attribute is empty, their username is used.

Background Color

The background color in hex notation that displays behind the issuer’s logo within the authenticator application.

Logo Image URL

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

Generate Recovery Codes

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

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

One Time Password Length

The length of the generated OTP in digits.

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

Minimum Secret Key Length

Number of hexadecimal characters allowed for the Secret Key.

OATH Algorithm

Specify the algorithm your device uses to generate the OTP:

If this is set to HOTP, set the same value in the OATH Token Verifier node.

TOTP Time Step Interval

The length of time that an OTP is valid in seconds.

For example, if the time step interval is 30 seconds, a new OTP is generated every 30 seconds and is valid for 30 seconds only.

The default value is 30.

TOTP Hash Algorithm

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

HOTP Checksum Digit

This adds a digit to the end of the OTP generated to be used as a checksum to verify the OTP was generated correctly. This is in addition to the actual password length. Only set this if the user devices support it.

HOTP Truncation Offset

This is an option used by the HOTP algorithm that not all devices support. Leave the default value of -1 unless you know user devices use an offset.

QR code message

The message with instructions to scan the QR code to register the device.

Click Add. Enter the message locale in the Key field; for example, en-gb. Enter the message to display to the user in the Value field.

Store device data in shared state

If enabled, the device data isn’t stored in the user profile on successful completion of the node. Instead, the node adds the device data as a base64-encoded string to the oathDeviceProfile property in the shared node state. This string is decoded as an unescaped plain string representation of a JSON object. For example:

In the shared node state:

Decoded value:

Use the OATH Device Storage node to store the device data in the user profile instead.

OATH Algorithm

Specify the algorithm your device uses to generate the OTP:

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

HOTP Window Size

This property sets the window that the OTP device and the server counter can be out of sync.

For example, if the window size is 100 and the server’s last successful login was at counter value 2, the server accepts an OTP that is generated between counter 3 and 102.

The default value is 100.

TOTP Time Step Interval

The length of time that an OTP is valid, in seconds.

For example, if the time step interval is 30 seconds, a new OTP is generated every 30 seconds, and is valid for 30 seconds only.

The default value is 30.

TOTP Time Steps

This is the number of time step intervals that the OTP is permitted to be out of sync. This applies to codes that are generated before or after the current code.

For example, with a time step of 1, the server permits either the previous, the current, or the next code.

The default value is 2.

TOTP Hash Algorithm

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

TOTP Maximum Allowed Clock Drift

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

For example, with 3 allowed drifts and a time step interval of 30 seconds, the server allows codes from up to 90 seconds from the current time to be treated as the current time step.

The drift for a user’s device is calculated each time they enter a new code. If the drift exceeds this value, the user’s authentication code is rejected.

The default value is 5.

Allow recovery codes

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

One Time Password Validity Length

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

Default: 5

Mail Server Host Name (required)

Specifies the hostname of the SMTP email server.

Mail Server Host Port

Specifies the outgoing mail server port.

Common ports are 25, 465 for SSL/TLS, or 587 for StartTLS.

Mail Server Authentication Username

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

Mail Server Authentication Password

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

Email From Address (required)

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

Email Attribute Name

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

Default: mail

The subject of the email

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

The content of the email

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

Mail Server Secure Connection

Specifies how to connect to the mail server.

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

The possible values for this property are:

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

Mail Server Host Name (required)

Specifies the hostname of the SMTP email server.

Mail Server Host Port

Specifies the outgoing mail server port.

Common ports are 25, 465 for SSL/TLS, or 587 for StartTLS.

Mail Server Authentication Username

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

Mail Server Authentication Password

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

Email From Address (required)

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

Mobile Phone Number Attribute Name

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

Default: telephoneNumber

Mobile Carrier Attribute Name

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

The subject of the message

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

The content of the message

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

Mail Server Secure Connection

Specifies how to connect to the mail server.

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

The possible values for this property are:

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

Issuer

Specify an identifier so that the user knows which service their account relates to.

The value is displayed by the authenticator application:

For example, Example Inc. or the name of your application.

Account Name

Specifies the profile attribute to display as the username in the authenticator application.

If not specified, or if the specified profile attribute is empty, their username is used.

Registration Response Timeout

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

If the specified time is reached, evaluation continues along the Time Out outcome path.

Background Color

Specifies the background color, in hex notation, to display behind the issuer’s logo within the ForgeRock Authenticator application.

Logo Image URL

Specifies the location of an image to download and display as the issuer’s logo in the ForgeRock Authenticator application.

Generate Recovery Codes

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

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

QR code message

The message with instructions to scan the QR code to register the device.

Click Add. Enter the message locale in the Key field; for example, en-gb. Enter the message to display to the user in the Value field.

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.

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

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

The following variables can be used in the VALUE field:

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

Remove 'skip' option

Enable this option in the node to make the push authentication mandatory.

When disabled, the user can skip the push authentication requested by the node, and evaluation continues along the Skipped outcome path.

Default: Disabled

Share Context info

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

For example:

The ForgeRock Authenticator displays this additional information to the user to help verify that the request is genuine and initiated by them.

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

Custom Payload Attributes

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

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

Push Type

Select the type of the push authentication the user must perform on their device to continue the journey.

Possible values are:

The actions the user performs vary depending on the selected option. Refer to Respond to push notifications.

Capture failure (optional)

If enabled, and the node fails to send the Push Notification, the journey skips the node. The journey stores the reason for the failure in the PushAuthFailureReason key in the shared state for use by subsequent nodes in the journey.

Possible failure reasons include MISSING_USERNAME, SENDER_ALREADY_USED, CTS_ERROR, and TRANSMISSION_FAILURE.

Seconds To Wait

Specify the number of seconds to pause authentication.

Default: 5

Waiting Message

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

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

Default: Waiting for response…​

Push Challenge Message

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

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

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

Exit Message

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

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

Default: Cancel

Recovery Code Type

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

Default: OATH

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, am.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:

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 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, 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 fails and evaluation continues along the Failure path.

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

Return challenge as JavaScript

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

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

Generate recovery codes

Specify whether WebAuthn device recovery codes should be generated.

If enabled, recovery codes are generated and stored in the transient node state, and stored alongside the device profile.

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

Maximum Saved Devices

Specify the maximum number of WebAuthn devices to save in a user’s profile.

Set this property to 0 if you do not want to limit the number of devices.

When this property is greater than zero, the Exceed Device Limit outcome path becomes available.

Relying party

Specify the name of the relying party entity 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, such as am.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:

Preferred mode of attestation

Specifies whether AM requires that the authenticator provides attestation statements.

The available options are:

AM supports the following attestation formats:

Accepted signing algorithms

Specify the algorithms authenticators can use to sign their assertions.

Authentication attachment

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

There are two types of authenticator attachments:

The available options are:

Trust Store alias

Specifies the name of a secret store configured in the realm that contains CA-issued certificate chains, which can be used to verify attestation data provided by a device.

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

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.

Enforce revocation check

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

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

Timeout

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

If the specified time is reached, evaluation continues along the 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 property and are not saving the device data to the user’s profile immediately, do not enable the Generate recovery codes property in this node, but in the WebAuthn Device Storage node instead.

Store data in transient state

Specify whether the information provided by the device to the node is stored in the transient node state for later analysis by subsequent nodes, using the key webauthnData.

In addition to the information provided by the device, the type of attestation achieved; for example, BASIC, CA, SELF and so on, is stored in the transient node state, using the key webauthnAttestationType.

Store device data in transient state

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

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

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

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

Username to device

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

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

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

Shared state attribute for display name

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

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

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

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

Return challenge as JavaScript

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

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

Maximum Saved Devices

Specifies the maximum number of WebAuthn devices stored in the user’s profile.

Set this property to 0 if you do not want to limit the number of devices.

When this property is greater than zero, the Exceed Device Limit outcome path becomes available.

Lock Action

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

The Data Store Decision node checks whether the account is locked.

Sufficient Authentication Level

Evaluation continues along the True path if the current authentication level is equal to or greater than this integer; otherwise, the evaluation continues along the False path.

The CAPTCHA site key supplied by the CAPTCHA provider when you sign up for access to the API.

The CAPTCHA secret key supplied by the CAPTCHA provider when you sign up for access to the API.

The URL used to verify the CAPTCHA submission.

Possible values are:

The URL of the JavaScript that loads the CAPTCHA widget.

Possible values are:

The class of the HTML element required by the CAPTCHA widget.

Possible values are:

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

If you’re using Google reCAPTCHA v3, or hCaptcha, enter a score threshold.

The CAPTCHA provider returns a score for each user request, based on observed interaction with your site. CAPTCHA "learns" by observing real site traffic, so scores in a staging environment or in a production deployment that has just been implemented might not be very accurate.

A score of 1.0 is likely a good user interaction, while 0.0 is likely to be a bot.

The threshold you set here determines whether to allow or deny access, based on the score returned by the CAPTCHA provider.

Start with a threshold of 0.5.

For more information about score thresholds, refer to the Google documentation.

CAPTCHA Site Key (required)

The CAPTCHA site key supplied by the CAPTCHA provider when you sign up for access to the API.

CAPTCHA Secret Key (required)

The CAPTCHA secret key supplied by the CAPTCHA provider when you sign up for access to the API.

CAPTCHA Verification URL (required)

The URL used to verify the CAPTCHA submission.

Possible values are:

CAPTCHA API URL (required)

The URL of the JavaScript that loads the CAPTCHA widget.

Possible values are:

Class of CAPTCHA HTML Element

The class of the HTML element required by the CAPTCHA widget.

Possible values are:

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.

ForgeRock Identity Cloud

ForgeRock Access Management (self-managed)

ForgeRock Identity Platform (self-managed)

Identity Attribute

The attribute used to identify the object in IDM.

ForgeRock Identity Cloud

ForgeRock Access Management (self-managed)

ForgeRock Identity Platform (self-managed)

Interval

The type of interval the decision should trigger on.

To trigger the action once when the user reaches the number of successful login attempts, set Interval to AT.

To trigger the action on every login attempt after the user reaches the number of successful login attempts, set Interval to EVERY.

Amount

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

Identity Attribute

The attribute used to identify the object in IDM.

Certificate Collection Method

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

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

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

Default: No value specified.

Certificate Field Used to Access User Profile

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

If you select 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:

Default: None

Match Certificate in LDAP

When enabled, AM matches the certificate collected with the one stored in an LDAP directory entry. This entry and additional security-related properties are defined later in the node.

Default: Disabled

Check Certificate Expiration

When enabled, AM checks whether the certificate has expired.

Default: Disabled

Subject DN Attribute Used to Search LDAP for Certificates

Specifies the attribute that AM uses to search the LDAP directory for the certificate. The search filter also uses the value of the Subject DN as it appears in the certificate.

Default: 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 uses 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 includes in any HTTP CRL call to the CA that issued the certificate.

If the client or CA contains the Issuing Distribution Point Extension, AM uses this information to retrieve the CRL from the distribution point.

Add the parameters as key pairs of values in a comma-separated list (,). For example, 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 under Configure > Server Defaults > Security > Online Certificate Status Protocol Check.

Default: Disabled

LDAP Server Where Certificates are Stored

Specifies the LDAP server that holds the certificates. Enter each server in the ldap-server:port format.

AM servers can be associated with LDAP servers by writing multiple chains with the format am_server|ldapserver:port. For example, am.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, am.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 uses to authenticate to the LDAP directory 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

Name of Cookie (required)

Evaluation continues along the True path if the named cookie is present in the incoming authentication request; otherwise, evaluation continues along the False path.

Trusted Locations (required)

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

Geofence Radius (km)

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

The distance is calculated point-to-point.

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.

Acceptable Variance

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

Expiration

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

Use Custom Matching Script

Specifies whether to use a custom script to compare the collected metadata with saved device profiles.

The script type must be Decision node script for authentication trees (standalone AM) or Journey Decision Node (ForgeRock Identity Platform deployment).

Default: Authentication Tree Decision Node Script

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 (standalone AM) or Journey Decision Node (ForgeRock Identity Platform deployment) appear in the list.

Maximum Profile Size (KB)

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

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

Default: 3

Collect Device Metadata

Specifies whether device metadata is requested.

Collect Device Location

Specifies whether device location is requested.

Message

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

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

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

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

Device Name Variable

Specifies the name of a variable in the shared node state that contains an alias label for the device profile.

Maximum Saved Profiles

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

When the maximum is reached, saving a new profile replaces the least-recently used profile.

Save Device Metadata

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

Save Device Location

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

Score Threshold

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

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

Emulators score the maximum; 1.

Idle Timeout

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

Enforce Client IP

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

Use Secure Cookie

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

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

Use HTTP Only Cookie

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

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

HMAC Signing Key (required)

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

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

or

Persistent cookie name

Specifies the name of the persistent cookie to check.

Custom Cookie Name (required)

The name of the custom cookie.

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

Custom Cookie Value (required)

The value of the custom cookie.

Max Age

The length of time the custom cookie remains valid, in seconds. If that time is exceeded, the cookie is no longer valid.

AM sets the Max-Age and Expires attributes in the cookie to increase compatibility with different browsers.

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

Custom Cookie Domain

The domain the custom cookie will be sent to. If you specify a value here, AM sets a domain cookie. For example, if you set this property to am.example.com, AM sets a cookie on .am.example.com. Note the leading . indicating a domain cookie rather than a host cookie.

If you don’t set a value here, AM sets a host level cookie on the FQDN on which the client accessed AM. For example, if the client accesses AM at https://am.example.com and this property is empty, AM sets a host cookie on am.example.com.

Custom Cookie Path

The path of the custom cookie.

Use Secure Cookie

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

If you include the Secure flag, the cookie can only be transferred over HTTPS. When a request is made over HTTP, the cookie isn’t made available to the application.

Use HTTP Only Cookie

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

If you include the HttpOnly flag, the cookie isn’t accessible to scripts.

Custom Cookie SameSite attribute

Sets the SameSite attribute of the custom cookie.

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

Learn more in SameSite cookie rules.

Idle Timeout

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

Max life

Specifies the length of time the persistent cookie remains valid, in hours. After this time has passed, the cookie is no longer valid.

Use Secure Cookie

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

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

Use HTTP Only Cookie

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

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

HMAC Signing Key (required)

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

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

or

Persistent Cookie Name

Specifies the name used for the persistent cookie.

Client ID (required)

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

Client Secret (required)

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

Authentication Endpoint URL (required)

Specifies the URL to the social provider’s endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

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

Access Token Endpoint URL (required)

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

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

User Profile Service URL (required)

Specifies the user profile URL that returns profile information.

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

OAuth Scope (required)

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749).

Ensure you use the correct scope delimiter required by the identity provider, including commas or spaces.

The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Scope Delimiter (required)

Specifies the delimiter used to separate scope values.

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

Redirect URL (required)

Specifies the URL the user is redirected to by the social identity provider after authenticating.

For authentication trees in AM, set this property to the URL of the UI. For example, https://openam.example.com:8443/openam/XUI/.

Social Provider (required)

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

Example: Google

Auth ID Key (required)

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 (required)

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

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

Account Mapper (required)

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

Provided implementations are:

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

The Account Mapper classes can take two constructor parameters:

For example, to prefix all received property values with facebook- before searching, specify:

Attribute Mapper (required)

Specifies the list of fully qualified class names for implementations that map attributes from the OAuth 2.0 authorization server to AM profile attributes.

Provided implementations are:

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

The Attribute Mapper classes can take two constructor parameters to help differentiate between the providers:

For example, to prefix all incoming values with facebook-, specify:

To prefix all incoming values use an asterisk (*) as the attribute list. This 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 OAuth 2.0 provider to the local data store in AM.

Valid values are in the form provider-attr=local-attr.

Examples:

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:

Save attributes in the session