CTS-based sessions reside in the CTS token store and can be cached in memory on one or more AM servers to improve system performance ^[1]. If the session request is redirected to an AM server that does not have the session cached, that server must retrieve the session from the CTS token store.

AM sends a reference to the session to the client, but the reference does not contain any of the session state information. AM can modify a session during its lifetime without changing the client's reference to the session.

Client-based sessions are those where AM returns session state to the client after each request, and require it to be passed in with the subsequent request.

You should configure AM to sign and/or encrypt client-based sessions and authentication sessions for security reasons. As decrypting and verifying the session may be an expensive operation to perform on each request, AM caches^[1] the decrypt sequence in memory to improve performance.

For more information about configuring client-based security, see "Configuring Client-Based Session and Authentication Session Security".

In-memory sessions reside in AM's memory. AM sends clients a reference to the session, but the reference does not contain any of the session state information.

AM stores CTS-based sessions in the CTS token store and caches sessions in server memory. If a server with cached sessions fails, or if the load balancer in front of AM servers directs a request to a server that does not have the user's session cached, the AM server retrieves the session from the CTS token store, incurring performance overhead.

Choosing where to store sessions is an important decision you must make by realm. Consider the information in the following tables before configuring sessions:

CTS-based sessions provide the following advantages:

Client-based sessions provide the following advantages:

In-memory authentication sessions provide the following advantages:

The following table contrasts the impact of storing authentication sessions in different locations:

The following table contrasts the impact of storing sessions in different locations:

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

Properties:

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

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:

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

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

Properties:

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

Properties:

Example:

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.

Properties:

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

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.

The tree evaluation continues along the True path if the credentials are located in the configured data store and the user account profile is not locked. Otherwise, the tree evaluation continues along the False path.

Properties:

This node has no configurable properties.

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

If not specified, the tree uses the value specified in the Default Failure Login URL property under Realms > Realm Name > Authentication > Settings > Post Authentication Processing.

Properties:

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 following table includes example keys that may be available in an existing session, and sample data that they might contain:

Properties:

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

Properties:

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

Example:

HmacOneTimePassword Tree With HOTP Generator 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, for example, a username or the authentication level, is available to the child trees. Information collected by child trees is available to the parent once evaluation of the child is complete.

The 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:

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.

The 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 credentials are not found, the tree evaluation continues along the False outcome path.

Properties:

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" in the Setup and Maintenance Guide. The metric is exposed in all available interfaces, as described in "Monitoring Interfaces" in the Setup and Maintenance Guide.

Properties:

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

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

Properties:

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.

The 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:

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

The 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:

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

Properties:

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:

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:

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.

Properties:

This node has no configurable properties.

Example:

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

Example Tree With Page Node

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

User View of Example Tree with Page 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.

The tree evaluation continues along the single outcome path after capturing the password.

Properties:

This node has no configurable properties.

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 \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
--header 'Content-Type: application/json' \
--data '{
  "authId": "eyJ0eXAiOiJK...u4WvZmiI",
  "callbacks": [
      {
          "type": "PollingWaitCallback",
          "output": [
              {
                  "name": "waitTime",
                  "value": "10000"
              },
              {
                  "name": "message",
                  "value": "Waiting for response..."
              }
          ]
      }
  ]
}' 'https://openam.example.com:8443/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=Example'

For more information on authenticating using the REST API, see "Authentication and Logout".

When using the XUI for authentication, it automatically waits for the required amount of time and resubmit 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:

The Provision Dynamic Account node provisions an account following successful authentication by a social identity provider node. Accounts are provisioned using properties defined in the attribute mapper configuration of a social 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.

Properties:

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

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 Integrating IDM With the ForgeRock Identity Platform in the Samples Guide.

Properties:

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

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.

Properties:

This node has no configurable properties.

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 set up AM Push Notification Service credentials 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".

Properties:

Example:

Example Push Tree

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

If the user has a registered device:

If the user does not have a registered device:

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

The Persistent Cookie Decision authentication node checks for the existence of the persistent cookie specified in the Persistent cookie name property, the default being session-jwt.

If the cookie is present, the node verifies the signature of the JWT stored in the cookie by using the signing key specified in the HMAC signing key property.

If the signature is valid, the node will decrypt the payload of the JWT by using the key pair specified in the Persistent Cookie Encryption Certificate Alias property. This property can be found by navigating to Configure > Authentication > Core Attributes > Security.

Within the decrypted JSON payload is information such as the UID of the identity, and the client IP address. Enable the Enforce client IP property to verify that the current IP address and the client IP address in the cookie are identical.

The tree evaluation continues along the True outcome path if the persistent cookie is present and all the verification checks above are satisfied. Otherwise, tree evaluation continues along the False outcome path.

Properties:

$ openssl rand -base64 32

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

Example:

PersistentCookie Tree

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 obtaining the recovery codes for a registered device, see "Accessing Your Recovery Codes".

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:

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:

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:

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:

Example:

RetryLimit Tree

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 With the AM Console".

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

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

Properties:

The Set Persistent Cookie authentication node creates a persistent cookie named after the value specified in the Persistent cookie name property, the default being session-jwt.

The cookie contains a JWT, inside which there is a JSON payload with information such as the UID of the identity, and the client IP address.

The node encrypts the JWT using the key pair specified in the Persistent Cookie Encryption Certificate Alias property. This property can be found by navigating to Configure > Authentication > Core Attributes > Security.

The node signs the cookie with the signing key specified in the HMAC signing key property. Any node that will read the persistent cookie must be configured with the same HMAC signing key.

Properties:

$ openssl rand -base64 32

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

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

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

Properties:

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.

The 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:

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

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.

The 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:

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

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.

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

If not specified, the tree uses the value specified in the Default Success Login URL property under Realms > Realm Name > Authentication > Settings > Post Authentication Processing.

Properties:

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:

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" in the Setup and Maintenance Guide.

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 Interfaces" in the Setup and Maintenance Guide.

Properties:

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

The tree evaluation continues along the single outcome path after capturing the username.

Properties:

This node has no configurable properties.

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.

The 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:

Example:

Example Tree With Zero Page Login Node

AM connects to Active Directory over Lightweight Directory Access Protocol (LDAP). AM provides separate Active Directory and LDAP modules to support the use of both Active Directory and another directory service in an authentication chain.

For detailed information about this module's configuration properties, see "Active Directory Module Properties".

The Adaptive Risk module is designed to assess risk during authentication, so that AM can determine whether to require the user to complete further authentication steps. After configuring the Adaptive Risk module, insert it in your authentication chain with criteria set to Sufficient as shown in the following example:

Adaptive Risk Module in an Authentication Chain

In the example authentication chain shown, AM has users authenticate first using the LDAP module providing a user ID and password combination. Upon success, AM calls the Adaptive Risk module. The Adaptive Risk module assesses the risk based on your configured parameters. If the Adaptive Risk module calculates a total score below the threshold you set, the module returns success, and AM finishes authentication processing without requiring further credentials. Otherwise, the Adaptive Risk module evaluates the score to be above the risk threshold, and returns failure. AM then calls the HOTP module, requiring the user to authenticate with a one-time password delivered to her by email or by SMS to her mobile phone.

When you configure the Adaptive Risk module to save cookies and profile attributes after successful authentication, AM performs the save as post-authentication processing, only after the entire authentication chain returns success. You must set up AM to save the data as part of post-authentication processing by editing the authentication chain to add org.forgerock.openam.authentication.modules.adaptive.AdaptivePostAuthenticationPlugin to the list of post-authentication plugins.

When the Adaptive Risk module relies on the client IP address, and AM lies behind a load balancer or proxy layer, configure the load balancer or proxy to send the address by using the X-Forwarded-For header, and configure AM to consume and forward the header as necessary. For details, see "Handling HTTP Request Headers" in the Installation Guide.

For detailed information about this module's configuration properties, see "Adaptive Risk Authentication Module Properties".

This module lets you configure and track anonymous users, who can log in to your application or web site without login credentials. Typically, you would provide such users with very limited access, for example, an anonymous user may have access to public downloads on your site. When the user attempts to access resources that require more protection, the module can force further authentication for those resources.

For detailed information about this module's configuration properties, see "Anonymous Authentication Module Properties".

X.509 digital certificates can enable secure authentication without the need for user names and passwords or other credentials. Certificate authentication can be used to manage authentication by applications. If all certificates are signed by a recognized Certificate Authority (CA), then you might not need additional configuration. If you need to look up public keys of AM clients, this module can also look up public keys in an LDAP directory server.

When you store certificates and certificate revocation lists (CRL) in an LDAP directory service, you must configure:

Access to the LDAP server and how to search for users is similar to LDAP module configuration as in "LDAP Authentication Module". The primary difference is that, unlike for LDAP configuration, AM retrieves the user identifier from a field in the certificate that the client application presents, then uses that identifier to search for the LDAP directory entry that holds the certificate, which should match the certificate presented. For example, if the Subject field of a typical certificate has a DN C=FR, O=Example Corp, CN=Barbara Jensen, and Barbara Jensen's entry in the directory has cn=Barbara Jensen, then you can use CN=Barbara Jensen from the Subject DN to search for the entry with cn=Barbara Jensen in the directory.

For detailed information about this module's configuration properties, see "Certificate Authentication Module Properties".

The Data Store authentication module allows a login using the identity repository of the realm to authenticate users. The Data Store module removes the requirement to write an authentication plugin module, load, and then configure the authentication module if you need to authenticate against the same data store repository. Additionally, you do not need to write a custom authentication module where flatfile authentication is needed for the corresponding repository in that realm.

The Data Store module is generic. It does not implement data store-specific capabilities, such as the password policy and password reset features provided by LDAP modules. Therefore, the Data Store module returns failure when such capabilities are invoked.

For detailed information about this module's configuration properties, see "Data Store Authentication Module Properties".

The Device ID (Match) module provides device fingerprinting functionality for risk-based authentication. The Device ID (Match) module collects the unique characteristics of a remote user's computing device and compares them to characteristics on a saved device profile. The module computes any variances between the collected characteristics to those stored on the saved device profile and assigns penalty points for each difference.

For detailed information about this module's configuration properties, see "Device ID (Match) Authentication Module Properties".

In general, you can configure and gather the following device characteristics:

For example, when a user who typically authenticates to AM using Firefox and then logs on using Chrome, the Device ID (Match) module notes the difference and assigns penalty points to this change in behavior. If the module detects additional differences in behavior, such as browser fonts, geolocation, and so forth, then additional points are assessed and calculated.

If the total number of penalty points exceeds a pre-configured threshold value, the Device ID (Match) module fails and control is determined by how you configured your authentication chain. If you include the HOTP module in your authentication chain, and if the Device ID (Match) module fails after the maximum number of penalty points have been exceeded, then the authentication chain issues a HOTP request to the user, requiring the user to identify themselves using two-factor authentication.

The Device ID (Match) module comes pre-configured with default client-side and server-side JavaScript code, supplying the logic necessary to fingerprint the user agent and computer. Scripting allows you to customize the code, providing more control over the device fingerprint elements that you would like to collect. While AM scripting supports both the JavaScript (default) and Groovy languages, only server-side scripts can be written in either language. The client-side scripts must be written in the JavaScript language.

The Device ID (Match) module does not stand on its own within an authentication chain and requires additional modules. For example, you can have any module that identifies the user (for example, DataStore, Active Directory or others), Device ID (Match), any module that provides two-factor authentication, for example the ForgeRock Authenticator (OATH) or ForgeRock Authenticator (Push) authentication modules, and Device ID (Save) within your authentication chain.

As an example, you can configure the following modules with the specified criteria:

The Device ID (Save) module saves a user's device profile. The module can either save the profile upon request, requiring the user to provide a name for the device and explicitly save it, or it can save the profile automatically. If a user has multiple device profiles, the profile that is the closest match to the current client details is used for the comparison result.

For detailed information about this module's configuration properties, see "Device ID (Save) Authentication Module Properties".

Within its configured authentication chain, the Device ID (Save) module also takes the device print and creates a JSON object that consists of the ID, name, last selected date, selection counter, and device print itself.

The Federation authentication module is used by a service provider to create a user session after validating single sign-on protocol messages. This authentication module is used by the SAML, SAMLv2, ID-FF, and WS-Federation protocols.

For detailed information about this module's configuration properties, see "Federation Authentication Module Properties".

The ForgeRock Authenticator (OATH) module provides a more secure method for users to access their accounts with the help of a device such as a mobile phone. For detailed information about two-step verification with the ForgeRock Authenticator (OATH) module in AM, see "Implementing Multi-Factor Authentication".

For detailed information about this module's configuration properties, see "ForgeRock Authenticator (OATH) Authentication Module Properties".

The ForgeRock Authenticator (Push) module provides a way to send push notification messages to a device such as a mobile phone, enabling multi-factor authentication. For detailed information about multi-factor authentication with the ForgeRock Authenticator (Push) module in AM, see "Implementing Multi-Factor Authentication".

For detailed information about this module's configuration properties, see "ForgeRock Authenticator (Push) Authentication Module Properties".

The ForgeRock Authenticator (Push) Registration module provides a way to register a device such as a mobile phone for multi-factor authentication. For detailed information about multi-factor authentication with the ForgeRock Authenticator (Push) module in AM, see "Managing Devices for Multi-Factor Authentication".

For detailed information about this module's configuration properties, see "ForgeRock Authenticator (Push) Registration Authentication Module Properties".

The HOTP authentication module works with an authentication chain with any module that stores the username attribute. The module uses the username from the sharedState set by the previous module in the chain and retrieves the user's email address or telephone number to send a one-time password to the user. The user then enters the password on a Login page and completes the authentication process if successful.

For example, to set up HOTP in an authentication chain, you can configure the Data Store module (or any module that stores the user's username) as the requisite first module, and the HOTP module as the second requisite module. When authentication succeeds against the Data Store module, the HOTP module retrieves the Email Address and Telephone Number attributes from the data store based on the username value. For the HOTP module to use either attribute, the Email Address must contain a valid email address, or the Telephone Number must contain a valid SMS telephone number.

You can set the HOTP module to automatically generate a password when users begin logging into the system. You can also set up mobile phone, mobile carrier, and email attributes for tighter controls over where the messages are generated and what provider the messages go through to reach the user.

For detailed information about this module's configuration properties, see "HOTP Authentication Module Properties".

HTTP basic authentication takes a user name and password from HTTP authentication and tries authentication against the backend module in AM, depending on what you configure as the Backend Module Name.

For detailed information about this module's configuration properties, see "HTTP Basic Authentication Module Properties".

The Java Database Connectivity (JDBC) module lets AM connect to a database, such as MySQL or Oracle DB to authenticate users.

For detailed information about this module's configuration properties, see "JDBC Authentication Module Properties".

AM connects to directory servers using Lightweight Directory Access Protocol (LDAP). To build an easy-to-manage, high-performance, pure Java directory service, try ForgeRock Directory Services.

For detailed information about this module's configuration properties, see "LDAP Authentication Module Properties".

The Legacy OAuth 2.0/OpenID Connect authentication module lets AM authenticate clients of OAuth resource servers. References in this section are to RFC 6749, The OAuth 2.0 Authorization Framework.

If the module is configured to create an account if none exists, then you must provide valid SMTP settings. As part of account creation, the OAuth 2.0/OpenID Connect client authentication module sends the resource owner an email with an account activation code. To send email, AM uses the SMTP settings from the configuration for the OAuth 2.0/OpenID Connect authentication module.

For detailed information about this module's configuration properties, see "Legacy OAuth 2.0/OpenID Connect Authentication Module Properties".

The Mobile Station Integrated Services Digital Network (MSISDN) authentication module enables non-interactive authentication using a mobile subscriber ISDN associated with a terminal, such as a mobile phone. The module checks the subscriber ISDN against the value found on a user's entry in an LDAP directory service.

For detailed information about this module's configuration properties, see "MSISDN Authentication Module Properties".

The Open Authentication (OATH) module provides a more secure method for users to access their accounts with the help of a device, such as their mobile phone or Yubikey. Users can log into AM and update their information more securely from a one-time password (OTP) displayed on their device. The OATH module includes the OATH standard protocols (RFC 4226 and RFC 6238). The OATH module has several enhancements to the HMAC One-Time Password (HOTP) Authentication Module, but does not replace the original module for those already using HOTP prior to the 10.1.0 release. The OATH module includes HOTP authentication and Time-Based One-Time Password (TOTP) authentication. Both types of authentication require an OATH compliant device that can provide the OTP.

HOTP authentication generates the OTP every time the user requests a new OTP on their device. The device tracks the number of times the user requests a new OTP, called the counter. The OTP displays for a period of time you designate in the setup, so the user may be further in the counter on their device than on their account. AM will resynchronize the counter when the user finally logs in. To accommodate this, you set the number of passwords a user can generate before their device cannot be resynchronized. For example, if you set the number of HOTP Window Size to 50 and someone presses the button 30 on the user's device to generate a new OTP, the counter in AM will review the OTPs until it reaches the OTP entered by the user. If someone presses the button 51 times, you will need to reset the counter to match the number on the device's counter before the user can login to AM. HOTP authentication does not check earlier passwords, so if the user attempts to reset the counter on their device, they will not be able to login until you reset the counter in AM to match their device. See "Resetting Registered Devices by using REST" for more information.

TOTP authentication constantly generates a new OTP based on a time interval you specify. The device tracks the last two passwords generated and the current password. The Last Login Time monitors the time when a user logs in to make sure that user is not logged in several times within the present time period. Once a user logs into AM, they must wait for the time it takes TOTP to generate the next two passwords and display them. This prevents others from being able to access the users account using the OTP they entered. The user's account can be accessed again after the generation of the third new OTP is generated and displayed on their device. For this reason, the TOTP Time-Step Interval should not be so long as to lock users out, with a recommended time of 30 seconds.

An authentication chain can be created to generate an OTP from either HOTP or TOTP.

For detailed information about this module's configuration properties, see "OATH Authentication Module Properties".

The OpenID Connect id_token bearer module lets AM rely on an OpenID Connect 1.0 provider's ID Token to authenticate an end user.

The OpenID Connect id_token bearer module expects an OpenID Connect ID Token in an HTTP request header. It validates the ID Token, and if successful, looks up the AM user profile corresponding to the end user for whom the ID Token was issued. Assuming the ID Token is valid and the profile is found, the module authenticates the AM user.

You configure the OpenID Connect id_token bearer module to specify how AM gets the information needed to validate the ID Token, which request header contains the ID Token, the issuer identifier for the provider who issued the ID Token, and how to map the ID Token claims to an AM user profile.

OpenID Connect id_token Bearer Example

The OpenID Connect id_token bearer module configuration must match the claims returned in the id_token JWT used to authenticate.

Before configuring the module, use an OpenID Connect client to obtain an id_token. Decode the id_token value to see the claims in the middle portion of the JWT. The claims in the decoded id_token look something like the following example, which was obtained at Google's OAuth 2.0 Playground:

{
      azp: "azp_id.apps.googleusercontent.com",
      aud: "aud_id.apps.googleusercontent.com",
      sub: "subject_id",
      at_hash: "access_token_hash",
      iss: "https://accounts.google.com",
      iat: 1505814261,
      exp: 1505817861,
      name: "Google User",
      picture: "https://lh5.googleusercontent.com/***/photo.jpg",
      given_name: "Google",
      family_name: "User",
      locale: "en"
      }

The azp, aud, and iss values are literally reused in the module configuration. Also notice that, in this example, name is mapped to cn for user accounts in the identity repository. The following figure shows an example configuration for this id_token format.

Sample OpenID Connect id_token Bearer Module Configuration

The following example command demonstrates a REST call that authenticates the user using the module:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--header "oidc_id_token: eyJ...ifQ.eyJ...In0.BT1...iZA" \
https://openam.example.com:8443/openam/json/realms/root/authenticate?authIndexType=module&authIndexValue=OIDCBearer
{
    "tokenId": "nIq...AA*",
    "successUrl": "/openam/console",
    "realm": "/"
}

Notice that the id_token value, abbreviated as eyJ...ifQ.eyJ...In0.BT1...iZA, is the value of the oidc_id_token header as seen in the configuration. The request targets a module named OIDCBearer as specified by the authIndexType and authIndexValue parameters. For detailed information about the authentication REST API, see "Authentication and Logout".

For detailed information about this module's configuration properties, see "OpenID Connect id_token bearer Authentication Module Properties".

The Persistent Cookie module supports the configuration of cookie lifetimes based on requests and a maximum time. Note that by default, the persistent cookie is called session-jwt.

Before you begin, make sure a public key alias is defined in AM. The Persistent Cookie module encrypts a JSON Web Token (JWT) using a public key from the AM keystore. The keystore must be configured under Realms > Realm Name > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias. If the keystore changes and the default test key is no longer present, the public key alias must be updated to reflect the change, otherwise the module will fail. Similarly, in multi-instance deployments, the keypair must be available on all AM instances.

When the Persistent Cookie module enforces the client IP address, and AM lies behind a load balancer or proxy layer, configure the load balancer or proxy to send the address by using the X-Forwarded-For header, and configure AM to consume and forward the header as necessary. For details, see "Handling HTTP Request Headers" in the Installation Guide.

The Persistent Cookie module belongs with a second module in an authentication chain. To see how this works, navigate to Realms > Realm Name > Authentication > Chains. Create a new chain and add modules as shown in the figure. The following example shows how a Persistent Cookie module is sufficient. If the persistent cookie does not yet exist, authentication relies on LDAP:

Persistent Cookie Module in an Authentication Chain

Select the Settings tab and locate settings for the post-authentication processing class. Set the Class Name to org.forgerock.openam.authentication.modules.persistentcookie.PersistentCookieAuthModulePostAuthenticationPlugin, as shown in the following figure:

You should now be able to authenticate automatically, as long as the cookie exists for the associated domain.

For detailed information about this module's configuration properties, see "Persistent Cookie Authentication Module Properties".

The Remote Authentication Dial-In User Service (RADIUS) module lets AM authenticate users against RADIUS servers.

For detailed information about this module's configuration properties, see "RADIUS Authentication Module Properties".

The Secure Attribute Exchange (SAE) module lets AM authenticate a user who has already authenticated with an entity that can vouch for the user to AM, so that AM creates a session for the user. This module is useful in virtual federation, where an existing entity instructs the local AM instance to use federation protocols to transfer authentication and attribute information to a partner application.

For detailed information about this module's configuration properties, see "SAE Authentication Module Properties".

The SAML2 authentication module lets administrators integrate SAML v2.0 single sign-on and single logout into an AM authentication chain.

You use the SAML2 authentication module when deploying SAML v2.0 single sign-on in integrated mode. In addition to configuring SAML2 authentication module properties, integrated mode deployment requires that you make several changes to service provider configurations. Before attempting to configure a SAML2 authentication module instance, review "Implementing SAML v2.0 Single Sign-On in Integrated Mode" in the SAML v2.0 Guide and make sure that you have made any required changes to your service provider configuration.

For detailed information about this module's configuration properties, see "SAML2 Authentication Module Properties".

A scripted authentication module runs scripts to authenticate a user. The configuration for the module can hold two scripts, one to include in the web page run on the client user-agent, another to run in AM on the server side.

The client-side script is intended to retrieve data from the user-agent. This must be in a language the user-agent can run, such as JavaScript, even if the server-side script is written in Groovy.

The server-side script is intended to handle authentication.

Scripts are stored not as files, but instead as AM configuration data. This makes it easy to update a script on one AM server, and then to allow replication to copy it to other servers. You can manage the scripts through the AM console, where you can write them in the text boxes provided or upload them from files.

You can also upload scripts and associate them with a scripted authentication module by using the ssoadm command.

The following example shows how to upload a server-side script from a file, create a scripted authentication module, and then associate the uploaded script with the new module.

     #
     # Upload a server-side script from a script file, myscript.groovy.
     #

     ssoadm create-sub-cfg \
     --realm / \
     --adminid amadmin \
     --password-file /tmp/pwd.txt \
     --servicename ScriptingService \
     --subconfigname scriptConfigurations/scriptConfiguration \
     --subconfigid myScriptId \
     --attributevalues \
     "name=My Scripted Auth Module Script" \
     "script-file=myscript.groovy" \
     "context=AUTHENTICATION_SERVER_SIDE" \
     "language=GROOVY"
     #
     # Create a scripted authentication module, myScriptedAuthModule.
     #

     ssoadm create-auth-instance \
     --realm / \
     --adminid amadmin \
     --password-file /tmp/pwd.txt \
     --authtype Scripted \
     --name myScriptedAuthModule

     #
     # Associate the script with the auth module, and disable client-side scripts.
     #

     ssoadm update-auth-instance \
     --realm / \
     --adminid amadmin \
     --password-file /tmp/pwd.txt \
     --name myScriptedAuthModule \
     --attributevalues \
     "iplanet-am-auth-scripted-server-script=myScriptId" \
     "iplanet-am-auth-scripted-client-script-enabled=false"

If you have multiple separate sets of client-side and server-side scripts, then configure multiple modules, one for each set of scripts.

For details on writing authentication module scripts, see "Using Server-side Authentication Scripts in Authentication Modules".

For detailed information about this module's configuration properties, see "Scripted Authentication Module Properties".

The SecurID module lets AM authenticate users with RSA Authentication Manager software and RSA SecurID authenticators.

For detailed information about this module's configuration properties, see "SecurID Authentication Module Properties".

The social authentication modules let AM authenticate clients of OAuth 2.0 or OpenID Connect 1.0 resource servers. References in this section are to RFC 6749, The OAuth 2.0 Authorization Framework.

AM provides pre-configured authentication modules for the following social identity providers:

AM provides two authentication modules for the WeChat social identity provider. The Social Auth WeChat authentication module implements a login flow that requires the user to scan an on-screen QR code with the WeChat app. The Social Auth WeChat Mobile authentication module implements an alternative login flow for users authenticating on their mobile device, who would not be able to scan a QR code displayed on the mobile device's screen.

AM provides two generic authentication modules, one for OAuth 2.0, and another for OpenID Connect 1.0, for authenticating users of standards-compliant social identity providers, for example Facebook and Google.

If the social authentication module is configured to create an account when none exists, then you must provide valid SMTP settings in the Email tab. The social identity provider must also provide the user's email address. As part of account creation, the social authentication module sends the resource owner an email with an account activation code. To send email, AM uses the SMTP settings from the Email tab of the configuration of the social authentication module.

For detailed information about the social authentication module's configuration properties, see the following sections:

The Windows Desktop SSO module uses Kerberos authentication. The user presents a Kerberos token to AM through the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) protocol. The Windows Desktop SSO authentication module 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. Users might 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.

For detailed information about this module's configuration properties, see "Windows Desktop SSO Authentication Module Properties".

The Windows NT module lets AM authenticate against a Microsoft Windows NT server.

This module requires that you install a Samba client in a bin directory under the AM configuration directory, such as $HOME/openam/openam/bin.

For detailed information about this module's configuration properties, see "Windows NT Authentication Module Properties".

Configure a JWT signature to prevent malicious tampering of client-based session and authentication session JWTs.

Perform the following steps to configure the JWT signature:

For detailed information about Session Service configuration attributes, see the entries for "Session" in the Reference.

Configure JWT encryption to prevent man-in-the-middle attackers from accessing users' session details, and to prevent end users from examining the content in the JWT.

Perform the following steps to encrypt the JWT:

For detailed information about Session Service configuration attributes, see the entries for "Session" in the Reference.

AM supports Elliptic Curve Digital Signature Algorithms (ECDSA) as an alternative to RSA cryptography (RS256) or HMAC with SHA (HS256, HS384, HS512) signatures (see the JSON Web Algorithms specification, RFC 7518). The elliptic curve algorithms provide smaller key lengths for the same level of security that RSA provides (256-bit elliptic curve key vs 2048-bits RSA). The smaller key lengths result in faster signature and key generation times, and faster data transmission over TLS. One disadvantage for ECDSA is that signature verification can be significantly slower on the JVM.

AM supports the following elliptic curve signature algorithms:

To ensure that the client-based session cookie size does not surpass the browser supported size, Web Agents 5.x and Java Agents 5.x do not support both signing and encrypting the session cookie. To configure agents with client-based sessions, implement one of the following configurations:

Failure to set up client-based sessions correctly may cause unexpected errors when accessing a protected resource, such as blank pages and redirection loops.

Client-based sessions do not support restricted tokens. Therefore, Web Agents 5.x and Java Agents 5.x configured in a realm configured for client-based sessions are not protected against cookie hijacking. ForgeRock recommends using web or Java agents with CTS-based sessions.