The ForgeRock Authenticator (OATH) module supports HMAC one-time password (HOTP) and time-based one-time password (TOTP) authentication as defined in the OATH standard protocols for HOTP (RFC 4226) and TOTP (RFC 6238). Both HOTP and TOTP authentication require an OATH-compliant device that can provide the password.

HOTP authentication generates the one-time password every time the user requests a new password on their device. The device tracks the number of times the user requests a new one-time password with a counter. The one-time password 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 times on the user's device to generate a new password, the counter in AM will review the passwords until it reaches the one-time password 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. For more information, see "Resetting Registered Devices by using REST".

TOTP authentication constantly generates a new one-time password based on a time interval you specify. The device tracks the last several passwords generated and the current password. The TOTP Time Steps setting configures the number of passwords tracked. The Last Login Time setting monitors the time when a user logs in to make sure that user is not logged in several times within the present time period. The TOTP Time-Step Interval should not be so long as to lock users out, with a recommended time of 30 seconds.

The ForgeRock Authenticator (OATH), OATH, and HOTP authentication modules let you configure authentication that prompts users to enter HMAC one-time passwords. It is important that administrators understand the differences among these authentication modules:

Before deciding on an implementation strategy, assess your requirements against the following capabilities in AM:

You can use push notifications as part of the authentication process in AM.

To receive push notifications when authenticating, end users must register an Android or iOS device with AM. The registered device can then be used as an additional factor when authenticating to AM. AM can send the device a push notification, which can be accepted by the ForgeRock Authenticator app. In the app, the user can allow or deny the request that generated the push notification and return the response to AM.

Overview of Push Authentication

The following steps occur when AM receives an authentication request and is configured for multi-factor authentication using push notifications:

The ForgeRock Authenticator (Push) authentication module operates in passwordless mode if not preceded by a Data Store module in an authentication chain. When authenticating using such a chain, the user will be asked to enter their user ID, but not their password. A push notification is then sent to their registered device to complete the authentication by using the ForgeRock Authenticator app.

You should be aware of the following potential limitations before deciding to implement passwordless push authentication:

Consider using push notifications as part of a multi-factor authentication chain For an example, see "Creating Authentication Chains for Push Authentication".

AM sessions are "stateful" or "stateless," and are described in detail in the following sections.

1.9.1.6. Session Cookies

AM writes a cookie in the authenticated user's browser for both stateful and stateless sessions. By default, the cookie's name is iPlanetDirectoryPro. For stateful sessions, the cookie contains a reference to the stateful session in the CTS token store and several other pieces of information. For stateless sessions, the cookie is larger and contains all the information that would be held in the CTS token store if the session were stateful.

Stateless session cookies are comprised of two parts. The first part of the cookie is identical to the cookie for stateful sessions, which ensures the compatibility of the cookies regardless of the session type. The second part is a base 64-encoded JSON Web Token (JWT), and it contains session information, as illustrated in the figure below.

Stateful and Stateless Session Cookies

Note that the diagram is not to scale. The size of the stateless session cookie increases when you customize AM to store additional attributes in users' sessions. You are responsible for ensuring that the size of the cookie does not exceed the maximum cookie size allowed by your end users' browsers.

1.9.1.6.1. Stateless Session Cookie Security

When using stateless session cookies, you should configure AM to sign and encrypt the JWT inserted in the iPlanetDirectoryPro cookie.

Configuring stateless session cookies for JWT signing and encryption is discussed in "Configuring Stateless Session Cookie Security".

JWT Signing

AM sets the iPlanetDirectoryPro cookie in the user's browser as proof of previous authentication whenever single sign-on is desired. AM verifies that the cookie is authentic by validating a signature configured in the Session Service. AM thwarts attackers who might attempt to tamper with the contents of the cookie or its signature, or who might attempt to sign the cookie with an incorrect signature.

JWT Encryption

Knowledgeable users can easily decode base 64-encoded JWTs. Because an AM session contains information that might be considered sensitive, encrypting the JWT that contains the session protects its contents by ensuring opaqueness.

Encrypting the JWT prevents man-in-the-middle attacks that could log the state of every AM session. Encryption also ensures that end users are unable to access the information in their AM session.

Authorization policies may also require a particular authentication level to access sensitive resources, which may be at a higher level than the user currently has in the session. When an authenticated user tries to access a sensitive resource with a valid session that does not have the required authentication level, AM returns an authorization decision that denies access to the resource and returns an advice indicating that the user needs to reauthenticate at the required authentication level to access the resource. The web or Java agent or policy enforcement point can then send the user back to AM for session upgrade.

During session upgrade, the user authenticates with a stronger authentication module. The stronger module is typically part of the same authentication chain that handled the original authentication, though not required for access to less sensitive resources. Upon successful stronger authentication, the user session is upgraded to the new authentication level and modified to include any settings related to the stronger authentication.

If unsuccessful, session upgrade leaves the user session as it was before the attempt at stronger authentication. If session upgrade failed because the login page times out, AM redirects the user's browser to the success URL from the last successful authentication.

In general, session upgrade can occur when the following events occur:

AM web and Java agents handle session upgrade without additional configuration, because the agents are built to handle AM's advices. If you build your own policy enforcement point (PEP), however, you must take advices and session upgrade into consideration. For RESTful PEPs and for indications on how to handle advices, see "Requesting Policy Decisions" in the Authorization Guide. For session upgrade see "Authentication and Logout".

In some deployments, you need to limit how many active sessions a user can have at a given time. For example, you might want to prevent a user from using more than two devices at once.

AM lets you limit the number of active sessions for a user by setting session quotas. You also configure session quota exhaustion actions so that when a user goes beyond the session quota, AM takes the appropriate action.

See "Implementing Session Quotas" for instructions.

AM's support for session quotas requires stateful sessions. Be sure that AM is configured for stateful sessions—the default configuration—before attempting to configure session quotas.

Cross-domain single sign-on (CDSSO) provides a safe mechanism for managing access across one or multiple domains in a single organization. For example, CDSSO allows your AM servers in the DNS domain .internal.net to provide authentication and authorization to web and Java agents from the .internal.net domain and other DNS domains, such as .example.net.

When implementing CDSSO in your deployment, take into account the following points:

Web Agents 5 and Java Agents 5 wrap the SSO session token inside an OpenID Connect (OIDC) JSON Web Token (JWT) ^[1]. During the CDSSO flow, the agents create cookies for the different domains specified in the agent profile, and the oauth2/authorize endpoint authorizes the different cookie domains as required.

The following diagram illustrates the stateful CDSSO flow for Web Agents 5 and Java Agents 5:

Agents 5 CDSSO Flow

For information about how to configure CDSSO, see "Implementing Cross-Domain Single Sign-On".

When changing authentication realms, a subject leaves the current SSO realm. The new SSO realm might apply to different applications, and use a different authentication process. For AM, logging in to a new realm means logging out of the current realm.

When a user interactively changes realms through the AM console, AM offers the option of logging out of the current realm to log in to the new realm, or choosing to remain logged in to the current realm.

Classic cross-domain single sign-on (CDSSO) provides a mechanism for web and Java agents earlier than version 5 to manage access across multiple domains in a single organization. For example, CDSSO allows your AM servers in the DNS domain .internal.net to provide authentication and authorization to agents from other DNS domains, such as .example.net.

When implementing classic CDSSO in your deployment, take into account the following points:

Java agents ^[2] use a mechanism to write the SSO token from AM authentication to a cookie with the domain of the host where the agent runs. The following sequence diagram illustrates this mechanism:

CDSSO Flow for Java Agents (earlier than version 5)

Whereas Java agents^[2] have an endpoint specifically to handle the cookie domain translation, web agents ^[2] handle the request directly as shown in the following sequence diagram:

CDSSO Flow for Web Agents (earlier than version 5)

For information about how to configure cross-domain SSO, see "Implementing Classic Single Domain and Cross-Domain SSO".

Classic single domain SSO provides web and Java agents earlier than version 5 with SSO capabilities when AM and the agents are in the same DNS domain.

The following diagram illustrates single domain SSO:

SSO With Web and Java Agents (earlier than version 5)

A client points their browser to a protected resource application. An agent protecting the application checks the client browser cookies for the presence of a session. If a session cookie exists and is valid, the agent requests validation (see arrow 8).

If no valid session cookie exists, the agent redirects the client to AM for authentication (AuthN). If the client submits valid credentials, the AuthN service creates a session cookie for the configured domain. The contents of the session cookie varies, depending on the configuration of the realm to which the user authenticates:

AM issues an HTTP redirect to send the client browser back to the protected resource.

The agent then verifies the validity of the session with the AM session service, before granting access.

For information about how to configure SSO in a single domain, see "Implementing Classic Single Domain and Cross-Domain SSO".

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 "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 a Server-side Authentication Script".

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

By default, AM configures a default authentication chain, ldapService, which uses the DataStore module for authentication. This default authentication chain is configured for both administrators and non-administrators out-of-the-box after installation.

This section covers the configuration of the following authentication nodes, which are built into AM:

2.4.1.1. Auth Level Decision Authentication Node

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

Properties:

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

2.4.1.2. Choice Collector Authentication Node

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

Properties:

Property	Usage
Choices	Enter two or more choice strings to display to the user. To remove a choice, select its delete icon. To delete all choices, select the delete button in the Choices field.
Default choice	Enter the value of the choice to be selected by default.
Prompt	Enter the prompt string to display to the user when presenting the choices.

Example:

2.4.1.3. Data Store Decision Authentication Node

The Data Store Decision authentication node verifies that provided 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. Otherwise, the tree evaluation continues along the False path.

Properties:

This node has no configurable properties.

2.4.1.4. Inner Tree Evaluator Authentication 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:

Property	Usage
Tree name	Enter the name of the tree to evaluate.

2.4.1.5. Modify Auth Level Authentication Node

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

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

Properties:

Property	Usage
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.

2.4.1.6. Password Collector Authentication Node

The Password Collector authentication node prompts the user to enter their password.

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

Properties:

This node has no configurable properties.

2.4.1.7. Remove Session Properties Authentication Node

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

The tree evaluation continues along the single output path after removing specified properties from the session.

Properties:

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

2.4.1.8. Scripted Decision Authentication Node

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

The script defines the possible output paths by setting one or more values of a string variable named outcome.

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

Properties:

Property	Usage
Script	Select the script to execute from the drop-down field.
outcomes	Enter the possible strings that can be assigned to the outcome variable by the script. These strings provide the possible output paths the tree can continue along.

2.4.1.9. Set Session Properties Authentication Node

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

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

Properties:

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

2.4.1.10. Username Collector Authentication Node

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

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

Properties:

This node has no configurable properties.

2.4.1.11. Zero Page Login Collector Authentication Node

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

The tree evaluation continues along the Has Credentials output 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 output connector to the input of a Data Store Decision node, and the No Credentials output 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".

Properties:

Property	Usage
Username Header name	Enter the name of the header that contains the username value. Default: X-OpenAM-Username
Password Header name	Enter the name of the header that contains the password value. Default: X-OpenAM-Password

Example:

Example Tree With Zero Page Login Node

The wizards configure the settings for logging in to AM using social identity providers such as Google, Facebook, and VKontakte.

To use AM social authentication as part of an IDM deployment, some additional configuration of the created authentication modules is required.

Push authentication uses two separate authentication modules:

You can insert both modules into a single chain to register devices and then authenticate with push notifications. See "To Create an Authentication Chain for Push Registration and Authentication".

The ForgeRock Authenticator (Push) module can also be used for passwordless authentication using push notifications. If the module is placed at the start of a chain, it will ask the user to enter their user ID, but not their password. A push notification is then sent to their registered device to complete the authentication by using the ForgeRock Authenticator app.

For information on configuring an authentication chain for passwordless authentication, see "To Create an Authentication Chain for Push Registration and Passwordless Authentication".

For information on the potential limitations of passwordless authentication, see "Limitations When Using Passwordless Push Authentication".

This section covers one-time password authentication.

If you have not already done so, download and install the ForgeRock Authenticator app on your phone, so that you can perform multi-factor authentication.

The ForgeRock Authenticator app supports push authentication notifications and one-time passwords.

The app is available for both Android and iOS devices, and is free to download. Source code is also available:

Registering a device with AM by using the ForgeRock Authenticator app enables it to be used as an additional factor when logging in.

The ForgeRock Authenticator app supports registration of multiple accounts and multiple different authentication methods in each account, such as push notifications and one-time passwords.

Device registration only needs to be completed the first time an authentication method is used with an identity provider. Use of a different authentication method may require that device registration with the identity provider is repeated for that additional method.

The device needs access to the internet to register to receive push notifications. Registering for one-time password authentication does not require a connection to the internet.

Your device is now registered. You will able to use it to perform multi-factor authentication.

After successful first-time authentication with multi-factor authentication, you should safeguard your ability to use multi-factor authentication in case you lose your phone. AM provides each device you register with a set of one-time recovery codes that you can use in cases where you cannot complete multi-factor authentication using your registered device.

See "Recovering After Replacing a Lost Device" for the procedure to authenticate to AM using a recovery code instead of performing multi-factor authentication.

Unless the AM administrator has made one-time password authentication mandatory, users can choose to opt out of using one-time passwords by clicking the Skip This Step button on the ForgeRock Authenticator (OATH) screen. ^[3] This button appears:

Users who decide to opt out of using one-time passwords are not prompted to enter one-time passwords when authenticating to AM.

The decision to opt out of using one-time passwords in AM is revocable: users who have decided to opt out of using one-time passwords can reverse their decisions, so that one-time password authentication is once again required.

End users should follow these steps to opt out or opt in to using one-time passwords:

If you register a device with AM and then lose it, you must authenticate to AM using a recovery code, delete the lost device, and then register the new device. Follow these steps:

Users who do not save recovery codes or who run out of recovery codes and cannot authenticate to AM without a verification code require administrative support to reset their device profiles. See "Resetting Registered Devices by using REST" for more information.

If you repeatedly enter valid one-time passwords that appear to be valid passwords, but AM rejects the passwords as unauthorized, it is likely that your device has become out of sync with AM.

When a registered device becomes out of sync with AM, you must authenticate to AM using a recovery code, delete your device, and then re-register your device. You can do so by performing the steps in "To Register a New Device After Losing a Registered Device".

Users who do not save recovery codes or who run out of recovery codes and cannot authenticate to AM without a verification code require administrative support to reset their device profiles. See "Resetting Registered Devices by using REST" for more information.

As described in "Recovering After Replacing a Lost Device", a user who has lost a mobile phone registered with AM can register a replacement device by authenticating using a recovery code, deleting their existing device, and then re-registering a new device.

Additional support is required for users who lose mobile phones but did not save their recovery codes when they initially registered the phone, and for users who have used up all their recovery codes.

AM provides a REST API to reset a device profile by deleting information about a user's registered device. Either the user or an administrator can call the REST API to reset a device profile. Device profile reset can be implemented as follows:

Reset OATH Devices

To reset a user's OATH device profile, perform an HTTP POST to the /users/user/devices/2fa/oath?_action=reset endpoint.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm, starting at the top-level realm. Prefix each realm in the hierarchy with the realms/ keyword. For example /realms/root/realms/customers/realms/europe.

The following example resets the OATH devices of a user named myUser in a subrealm of the top-level realm called mySubrealm:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
--data '{}' \
https://openam.example.com:8443/openam/json/realms/root/realms/mySubrealm/users/myUser/devices/2fa/oath?_action=reset
{"result":true}

Reset Push Devices

To reset push devices over REST, perform an HTTP POST to the /users/user/devices/push?_action=reset endpoint as follows:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
--data '{}' \
http://openam.example.com:8080/openam/json/realms/root/realms/mySubrealm/users/myUSER/devices/push?_action=reset
{"result":true}

Before configuring your AM deployment to use stateless sessions, perform the following tasks:

To configure stateless sessions for a realm, follow these steps:

To verify that AM creates a stateless session when non-administrative users authenticate to the realm, follow these steps:

When using stateless sessions, you should sign and encrypt JWTs in the iPlanetDirectoryPro cookie.

Prior to configuring stateless session cookie security, ensure that you have deployed certificates as needed. For more information about managing certificates for AM, see "Setting Up Keys and Keystores" in the Setup and Maintenance Guide.

When deploying multiple AM servers in a site, every server must have the same security configuration. Shared secrets and security keys must be identical. If you modify shared secrets or keys, you must update all the servers in the site.

To ensure security of stateless session cookie JWTs, configure a JWT signature and encrypt the entire JWT. The sections that follow provide detailed steps for configuring stateless session cookie security.

For more information about stateless session cookie security, see "Stateless Session Cookie Security".

Session blacklisting ensures that users who have logged out of stateless sessions cannot achieve single sign-on without reauthenticating to AM.

Perform the following steps to configure session blacklisting:

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

The following AM features are not supported in realms that use stateless sessions:

AM supports an HttpOnly flag, which is affixed to the Set-cookie HTTP response header transmitted from the server to the browser. The HttpOnly flag mitigates against cross-site scripting (XSS) vulnerabilities that can be exploited through JavaScript or other scripting languages.

When the HttpOnly flag is enabled:

Perform the following steps to configure the HttpOnly flag:

A malicious user who steals a CDSSO cookie can potentially use it to access any realms that session has logged into, which may span multiple domains. For example, a token stolen from myapp.example.com could be used to access payroll.internal.com or any other protected domain in the same realm. Cookie hijacking protection restricts cookies to the fully-qualified domain name (FQDN) of the host where they are issued, such as openam-server.example.com and server-with-agent.example.com, using CDSSO to handle authentication and authorization.

For CDSSO with cookie hijacking protection, when a client successfully authenticates, AM issues the master SSO token cookie for its FQDN. AM issues restricted token cookies for the other FQDNs where the web or Java agents reside. The client ends up with cookies having different session identifiers for different FQDNs, and the AM server stores the correlation between the master SSO token and restricted tokens, such that the client only has one master session internally in AM.

To protect against cookie hijacking, you restrict the AM server domain to the server where AM runs. This sets the domain of the SSO token cookie to the host running the AM server that issued the token. You also enable use of a unique SSO token cookie. For your Java agents, you enable use of the unique SSO token cookie in the agent configuration.

This section describes how to configure AM for classic SSO on a single domain, for example, when using web or Java agents earlier than version 5. For general information about how classic single domain SSO works in AM, see "Classic Single Domain SSO".

The following procedure assumes that you know how to configure AM, the Apache Web server, and associated AM Apache agent.

If you want to configure AM and an application on two different cookie domains, such as example.org and example.net, you need to set up cross-domain SSO (CDSSO). For more information, see "Implementing Cross-Domain Single Sign-On".

This section describes how to configure AM for classic CDSSO, which concerns web or Java agents earlier than version 5. For general information about how classic CDSSO works in AM, see "Classic Cross-Domain SSO".

This section comprises several procedures:

When using the XUI, the base URL to authenticate to points to /XUI/#login under the deployment URL, such as http://openam.example.com:8080/openam/XUI/#login.

The base URL to log out is similar, for example, http://openam.example.com:8080/openam/XUI/#logout/.

By default, AM redirects the user to the URL specified in the goto and gotoOnFail query string parameters supplied to the authentication interface during login and logout. You can increase security against possible phishing attacks through open redirect by specifying a list of valid URL resources using the Validation Service.

AM only redirects a user if the goto and gotoOnFail URL matches any of the resources specified in this setting. If no setting is present, it is assumed that the goto or gotoOnFail URL is valid.

The URL whitelisting and pattern matching follow the wildcard rules as specified in "Specifying Resource Patterns with Wildcards" in the Authorization Guide.

Here are some general examples of URL pattern matching:

Source code for sample mobile applications is available in sample repositories in the ForgeRock commons project. Get local clones of one or more of the following repositories so that you can try these sample applications on your system:

The sample authentication module prompts for a user name and password to authenticate the user, and handles error conditions. The sample shows how you integrate an authentication module into AM such that you can configure the module through the AM console, and also localize the user interface.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for OpenAM 12.x, 13.x and AM (All versions)? in the Knowledge Base.

AM uses a Java properties file per locale to retrieve the appropriate, localized strings for the authentication module.

The following is the Sample Authentication Module properties file, amAuthSampleAuth.properties.

sampleauth-service-description=Sample Authentication Module
a500=Authentication Level
a501=Service Specific Attribute

sampleauth-ui-login-header=Login
sampleauth-ui-username-prompt=User Name:
sampleauth-ui-password-prompt=Password:

sampleauth-error-1=Error 1 occurred during the authentication
sampleauth-error-2=Error 2 occurred during the authentication

AM callbacks XML files are used to build the deprecated classic UI to prompt the user for identity information needed to process the authentication. The document type for a callback XML file is described in WEB-INF/Auth_Module_Properties.dtd where AM is deployed.

The value of the moduleName property in the callbacks file must match your custom authentication module's class name. Observe that the module name SampleAuth, shown in the example below, matches the class name in "The Sample Authentication Logic".

The following is the SampleAuth.xml callbacks file.

<!DOCTYPE ModuleProperties PUBLIC
 "=//iPlanet//Authentication Module Properties XML Interface 1.0 DTD//EN"
        "jar://com/sun/identity/authentication/Auth_Module_Properties.dtd">

<ModuleProperties moduleName="SampleAuth" version="1.0" >
    <Callbacks length="0" order="1" timeout="600" header="#NOT SHOWN#" />
    <Callbacks length="2" order="2" timeout="600" header="#TO BE SUBSTITUTED#">
        <NameCallback isRequired="true">
            <Prompt>#USERNAME#</Prompt>
        </NameCallback>
        <PasswordCallback echoPassword="false" >
            <Prompt>#PASSWORD#</Prompt>
        </PasswordCallback>
    </Callbacks>
    <Callbacks length="1" order="3" timeout="600" header="#TO BE SUBSTITUTED#"
        error="true" >
        <NameCallback>
            <Prompt>#THE DUMMY WILL NEVER BE SHOWN#</Prompt>
        </NameCallback>
    </Callbacks>
</ModuleProperties>

An AM authentication module must extend the com.sun.identity.authentication.spi.AMLoginModule abstract class, and must implement the methods shown below.

See the ForgeRock Access Management Java SDK API Specification for reference.

public void init(Subject subject, Map sharedState, Map options)

// OpenAM calls the process() method when the user submits authentication
// information. The process() method determines what happens next:
// success, failure, or the next state specified by the order
// attribute in the callbacks XML file.
public int process(Callback[] callbacks, int state) throws LoginException

// OpenAM expects the getPrincipal() method to return an implementation of
// the java.security.Principal interface.
public Principal getPrincipal()

AM does not reuse authentication module instances. This means that you can store information specific to the authentication process in the instance.

The implementation, SampleAuth.java, is shown below.

/**
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2011-2016 ForgeRock AS. All Rights Reserved
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt.
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file at legal/CDDLv1.0.txt.
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 */

package org.forgerock.openam.examples;

import java.security.Principal;
import java.util.Map;
import java.util.ResourceBundle;

import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;
import javax.security.auth.login.LoginException;

import com.sun.identity.authentication.spi.AMLoginModule;
import com.sun.identity.authentication.spi.AuthLoginException;
import com.sun.identity.authentication.spi.InvalidPasswordException;
import com.sun.identity.authentication.util.ISAuthConstants;
import com.sun.identity.shared.datastruct.CollectionHelper;
import com.sun.identity.shared.debug.Debug;

/**
 * SampleAuth authentication module example.
 *
 * If you create your own module based on this example, you must modify all
 * occurrences of "SampleAuth" in addition to changing the name of the class.
 *
 * Please refer to OpenAM documentation for further information.
 *
 * Feel free to look at the code for authentication modules delivered with
 * OpenAM, as they implement this same API.
 */
public class SampleAuth extends AMLoginModule {

    // Name for the debug-log
    private final static String DEBUG_NAME = "SampleAuth";
    private final static Debug debug = Debug.getInstance(DEBUG_NAME);

    // Name of the resource bundle
    private final static String amAuthSampleAuth = "amAuthSampleAuth";

    // User names for authentication logic
    private final static String USERNAME = "demo";
    private final static String PASSWORD = "changeit";

    private final static String ERROR_1_USERNAME = "test1";
    private final static String ERROR_2_USERNAME = "test2";

    // Orders defined in the callbacks file
    private final static int STATE_BEGIN = 1;
    private final static int STATE_AUTH = 2;
    private final static int STATE_ERROR = 3;

    // Errors properties
    private final static String SAMPLE_AUTH_ERROR_1 = "sampleauth-error-1";
    private final static String SAMPLE_AUTH_ERROR_2 = "sampleauth-error-2";

    private Map<String, String> options;
    private ResourceBundle bundle;
    private Map<String, String> sharedState;

    public SampleAuth() {
        super();
    }


    /**
     * This method stores service attributes and localized properties for later
     * use.
     * @param subject
     * @param sharedState
     * @param options
     */
    @Override
    public void init(Subject subject, Map sharedState, Map options) {

        debug.message("SampleAuth::init");

        this.options = options;
        this.sharedState = sharedState;
        this.bundle = amCache.getResBundle(amAuthSampleAuth, getLoginLocale());
    }

    @Override
    public int process(Callback[] callbacks, int state) throws LoginException {

        debug.message("SampleAuth::process state: {}", state);

        switch (state) {

            case STATE_BEGIN:
                // No time wasted here - simply modify the UI and
                // proceed to next state
                substituteUIStrings();
                return STATE_AUTH;

            case STATE_AUTH:
                // Get data from callbacks. Refer to callbacks XML file.
                NameCallback nc = (NameCallback) callbacks[0];
                PasswordCallback pc = (PasswordCallback) callbacks[1];
                String username = nc.getName();
                String password = String.valueOf(pc.getPassword());

                //First errorstring is stored in "sampleauth-error-1" property.
                if (ERROR_1_USERNAME.equals(username)) {
                    setErrorText(SAMPLE_AUTH_ERROR_1);
                    return STATE_ERROR;
                }

                //Second errorstring is stored in "sampleauth-error-2" property.
                if (ERROR_2_USERNAME.equals(username)) {
                    setErrorText(SAMPLE_AUTH_ERROR_2);
                    return STATE_ERROR;
                }

                if (USERNAME.equals(username) && PASSWORD.equals(password)) {
                    debug.message("SampleAuth::process User '{}' " +
                            "authenticated with success.", username);
                    return ISAuthConstants.LOGIN_SUCCEED;
                }

                throw new InvalidPasswordException("password is wrong",
                        USERNAME);

            case STATE_ERROR:
                return STATE_ERROR;
            default:
                throw new AuthLoginException("invalid state");
        }
    }

    @Override
    public Principal getPrincipal() {
        return new SampleAuthPrincipal(USERNAME);
    }

    private void setErrorText(String err) throws AuthLoginException {
        // Receive correct string from properties and substitute the
        // header in callbacks order 3.
        substituteHeader(STATE_ERROR, bundle.getString(err));
    }

    private void substituteUIStrings() throws AuthLoginException {
        // Get service specific attribute configured in OpenAM
        String ssa = CollectionHelper.getMapAttr(options, "specificAttribute");

        // Get property from bundle
        String new_hdr = ssa + " " +
                bundle.getString("sampleauth-ui-login-header");
        substituteHeader(STATE_AUTH, new_hdr);

        replaceCallback(STATE_AUTH, 0, new NameCallback(
                bundle.getString("sampleauth-ui-username-prompt")));
        replaceCallback(STATE_AUTH, 1, new PasswordCallback(
                bundle.getString("sampleauth-ui-password-prompt"), false));
    }
}

The implementation, SampleAuthPrincipal.java, is shown below.

/**
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2011-2016 ForgeRock AS. All Rights Reserved
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt.
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file at legal/CDDLv1.0.txt.
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 */

package org.forgerock.openam.examples;

import java.io.Serializable;
import java.security.Principal;

/**
 * SampleAuthPrincipal represents the user entity.
 */
public class SampleAuthPrincipal implements Principal, Serializable {
    private final static String COLON = " : ";

    private final String name;

    public SampleAuthPrincipal(String name) {

        if (name == null) {
            throw new NullPointerException("illegal null input");
        }

        this.name = name;
    }

    /**
     * Return the LDAP username for this SampleAuthPrincipal.
     *
     * @return the LDAP username for this SampleAuthPrincipal
     */
    @Override
    public String getName() {
        return name;
    }

    /**
     * Return a string representation of this SampleAuthPrincipal.
     *
     * @return a string representation of this
     *         TestAuthModulePrincipal.
     */
    @Override
    public String toString() {
        return new StringBuilder().append(this.getClass().getName())
                .append(COLON).append(name).toString();
    }

    /**
     * Compares the specified Object with this SampleAuthPrincipal
     * for equality. Returns true if the given object is also a
     *  SampleAuthPrincipal  and the two SampleAuthPrincipal have
     * the same username.
     *
     * @param o Object to be compared for equality with this
     *          SampleAuthPrincipal.
     * @return true if the specified Object is equal equal to this
     *         SampleAuthPrincipal.
     */
    @Override
    public boolean equals(Object o) {
        if (o == null) {
            return false;
        }

        if (this == o) {
            return true;
        }

        if (!(o instanceof SampleAuthPrincipal)) {
            return false;
        }
        SampleAuthPrincipal that = (SampleAuthPrincipal) o;

        if (this.getName().equals(that.getName())) {
            return true;
        }
        return false;
    }

    /**
     * Return a hash code for this SampleAuthPrincipal.
     *
     * @return a hash code for this SampleAuthPrincipal.
     */
    @Override
    public int hashCode() {
        return name.hashCode();
    }
}

AM requires that all authentication modules be configured by means of an AM service. At minimum, the service must include an authentication level attribute. Your module can access these configuration attributes in the options parameter passed to the init() method.

The service configuration file, amAuthSampleAuth.xml, is shown below. Save a local copy of this file, which you use when registering the module.

<?xml version="1.0" encoding="UTF-8"?>
<!--
   DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

   Copyright (c) 2011-2016 ForgeRock AS.

   The contents of this file are subject to the terms
   of the Common Development and Distribution License
   (the License). You may not use this file except in
   compliance with the License.

   You can obtain a copy of the License at legal/CDDLv1.0.txt.
   See the License for the specific language governing
   permission and limitations under the License.

   When distributing Covered Code, include this CDDL
   Header Notice in each file and include the License file at legal/CDDLv1.0.txt.
   If applicable, add the following below the CDDL Header,
   with the fields enclosed by brackets [] replaced by
   your own identifying information:
   "Portions Copyrighted [year] [name of copyright owner]"
-->
<!DOCTYPE ServicesConfiguration
    PUBLIC "=//iPlanet//Service Management Services (SMS) 1.0 DTD//EN"
    "jar://com/sun/identity/sm/sms.dtd">

<ServicesConfiguration>
 <Service name="iPlanetAMAuthSampleAuthService" version="1.0">
  <Schema
   serviceHierarchy="/DSAMEConfig/authentication/iPlanetAMAuthSampleAuthService"
   i18nFileName="amAuthSampleAuth" revisionNumber="10"
   i18nKey="sampleauth-service-description" resourceName="sample">
   <Organization>
    <!-- Specify resourceName for a JSON-friendly property in the REST SMS -->
    <AttributeSchema name="iplanet-am-auth-sampleauth-auth-level" resourceName="authLevel"
     type="single" syntax="number_range" rangeStart="0" rangeEnd="2147483647"
     i18nKey="a500">
     <DefaultValues>
      <Value>1</Value>
     </DefaultValues>
    </AttributeSchema>

    <!-- No need for resourceName when the name is JSON-compatible -->
    <AttributeSchema name="specificAttribute"
     type="single" syntax="string" validator="no" i18nKey="a501" />

    <!--
     For Auth Modules, the parent Schema element specifies the REST SMS resourceName,
     and the nested SubSchema must have resourceName="USE-PARENT"
    -->
    <SubSchema name="serverconfig" inheritance="multiple" resourceName="USE-PARENT">
     <AttributeSchema name="iplanet-am-auth-sampleauth-auth-level" resourceName="authLevel"
      type="single" syntax="number_range" rangeStart="0" rangeEnd="2147483647"
      i18nKey="a500">
      <DefaultValues>
       <Value>1</Value>
      </DefaultValues>
     </AttributeSchema>

     <!-- No need for a DefaultValues element when the default is blank -->
     <AttributeSchema name="specificAttribute"
      type="single" syntax="string" validator="no" i18nKey="a501" />

    </SubSchema>
   </Organization>
  </Schema>
 </Service>
</ServicesConfiguration>

Build the module with Apache Maven, and install the module in AM.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for OpenAM 12.x, 13.x and AM (All versions)? in the Knowledge Base.

Authentication modules are registered as services with AM globally, and then set up for use in a particular realm. In this example, you set up the sample authentication module for use in the realm / (Top Level Realm).

Log in to the AM console as an administrator, such as amadmin, and browse to Realms > Top Level Realm > Authentication > Modules. Click Add Module to create an instance of the Sample Authentication Module. Name the module Sample.

Click Create, and then configure the authentication module as appropriate.

Now that the module is configured, log out of the AM console.

Finally, try the module by specifying the Sample module. Browse to the login URL such as https://openam.example.com:8443/openam/XUI/?realm=/&module=Sample#login, and then authenticate with user name demo and password changeit.

After authentication you are redirected to the end user page for the demo user. You can logout of the AM console, and then try to authenticate as the non-existent user test123 to see what the error handling looks like to the user.

AM requires a small amount of configuration before trying the example server-side authentication script. You must create an authentication module of the Scripted type, and then include it in an authentication chain, which can then be used when logging in to AM. You must also ensure the demo user has an associated postal address.

The procedures in this section are:

This section shows how to log in using an authentication chain that contains a Scripted authentication module, which in turn uses the default server-side authentication script.

The default server-side authentication script gets the postal address of a user after they authenticate using a Data Store authentication module, and then makes an HTTP call to an external web service to determine the longitude and latitude of the address. Using these details, a second HTTP call is performed to get the local time at those coordinates. If that time is between two preset limits, authentication is allowed, and the user is given a session and redirected to the profile page.

Your post authentication plugin class implements the AMPostAuthProcessInterface interface, and in particular the following three methods.

public void onLoginSuccess(
  Map requestParamsMap,
  HttpServletRequest request,
  HttpServletResponse response,
  SSOToken token
) throws AuthenticationException

public void onLoginFailure(
  Map requestParamsMap,
  HttpServletRequest request,
  HttpServletResponse response
) throws AuthenticationException

public void onLogout(
  HttpServletRequest request,
  HttpServletResponse response,
  SSOToken token
) throws AuthenticationException

AM calls the onLoginSuccess() and onLoginFailure() methods immediately before informing the user of login success or failure, respectively. AM calls the onLogout() method only when the user actively logs out, not when a user's session times out. See the ForgeRock Access Management Java SDK API Specification for reference.

These methods can perform whatever processing you require. Yet, know that AM calls your methods synchronously as part of the authentication process. Therefore, if your methods take a long time to complete, you will keep users waiting. Minimize the processing done in your post authentication methods.

Post authentication plugins must be stateless: they do not maintain state between login and logout. Store any information that you want to save between login and logout in a session property. AM stores session properties in the CTS token store after login, and retrieves them from the token store as part of the logout process.

The following example post authentication plugin sets a session property during successful login, writing to its debug log if the operation fails.

package com.forgerock.openam.examples;

import java.util.Map;

import com.iplanet.sso.SSOException;
import com.iplanet.sso.SSOToken;

import com.sun.identity.authentication.spi.AMPostAuthProcessInterface;
import com.sun.identity.authentication.spi.AuthenticationException;
import com.sun.identity.shared.debug.Debug;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class SamplePAP implements AMPostAuthProcessInterface {
    private final static String PROP_NAME = "MyProperty";
    private final static String PROP_VALUE = "MyValue";
    private final static String DEBUG_FILE = "SamplePAP";

    protected Debug debug = Debug.getInstance(DEBUG_FILE);

    public void onLoginSuccess(
            Map requestParamsMap,
            HttpServletRequest request,
            HttpServletResponse response,
            SSOToken token
    ) throws AuthenticationException {
        try {
            token.setProperty(PROP_NAME, PROP_VALUE);
        } catch (SSOException e) {
            debug.error("Unable to set property");
        }
    }

    public void onLoginFailure(
            Map requestParamsMap,
            HttpServletRequest request,
            HttpServletResponse response
    ) throws AuthenticationException {
        // Not used
    }

    public void onLogout(
            HttpServletRequest request,
            HttpServletResponse response,
            SSOToken token
    ) throws AuthenticationException {
        // Not used
    }
}

If you have not already done so, download and build the sample code.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for OpenAM 12.x, 13.x and AM (All versions)? in the Knowledge Base.

In the sources, you find the following files:

Once built, copy the .jar to the WEB-INF/lib directory where you deployed AM.

$ cp target/*.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/

Restart AM or the container in which it runs.

You can associate post authentication plugins with realms or services (authentication chains). Where you configure the plugin depends on the scope to which the plugin should apply:

In OpenAM Console, navigate to Realms > Realm Name > Authentication > Settings > Post Authentication Processing. In the Authentication Post Processing Classes list, add the sample plugin class, com.forgerock.openam.examples.SamplePAP, and then click Save.

Alternatively, you can configure sample plugin for the realm by using the ssoadm command.

$ ssoadm set-svc-attrs \
 --adminid amadmin \
 --password-file /tmp/pwd.txt \
 --servicename iPlanetAMAuthService \
 --realm /myRealm \
 --attributevalues iplanet-am-auth-post-login-process-class=
 com.forgerock.openam.examples.SamplePAP
iPlanetAMAuthService under /myRealm was
 modified.

To test the sample post authentication plugin, login successfully to AM in the scope where the plugin is configured. For example, if you configured your plugin for the realm, /myRealm, specify the realm in the login URL.

http://openam.example.com:8080/openam/XUI/?realm=/myRealm#login

Although you will not notice anywhere in the user interface that AM calls your plugin, a web or Java agent or custom client code could retrieve the session property that your plugin added to the user session.

You build custom session quota exhaustion actions into a .jar that you then plug in to AM. You must also add your new action to the Session service configuration, and restart AM in order to be able to configure it for your use.

Your custom session quota exhaustion action implements the com.iplanet.dpro.session.service.QuotaExhaustionAction interface, overriding the action method. The action method performs the action when the session quota is met, and returns true only if the request for a new session should not be granted.

The example in this section simply removes the first session it finds as the session quota exhaustion action.

package org.forgerock.openam.examples.quotaexhaustionaction;

import static org.forgerock.openam.session.SessionConstants.SESSION_DEBUG;
import com.google.inject.Key;
import com.google.inject.name.Names;
import com.iplanet.dpro.session.SessionException;
import com.iplanet.dpro.session.SessionID;
import com.iplanet.dpro.session.service.InternalSession;
import com.iplanet.dpro.session.service.QuotaExhaustionAction;
import com.sun.identity.shared.debug.Debug;
import org.forgerock.guice.core.InjectorHolder;
import org.forgerock.openam.session.Session;
import org.forgerock.openam.session.clientsdk.SessionCache;

import javax.inject.Inject;
import java.util.Map;

/**
 * This is a sample {@link QuotaExhaustionAction} implementation,
 * which randomly kills the first session it finds.
 */
public class SampleQuotaExhaustionAction implements QuotaExhaustionAction {

    private static Debug debug = InjectorHolder.getInstance(Key.get(Debug.class, Names.named(SESSION_DEBUG)));

    private final SessionCache sessionCache;

    public SampleQuotaExhaustionAction() {
        this.sessionCache = InjectorHolder.getInstance(SessionCache.class);
    }

    @Inject
    public SampleQuotaExhaustionAction(SessionCache sessionCache) {
        this.sessionCache = sessionCache;
    }

    /**
     * Check if the session quota for a given user has been exhausted and
     * if so perform the necessary actions. This implementation randomly
     * destroys the first session it finds.
     *
     * @param is               The InternalSession to be activated.
     * @param existingSessions All existing sessions that belong to the same
     *                         uuid (Map:sid->expiration_time).
     * @return true If the session activation request should be rejected,
     *              otherwise false.
     */
    @Override
    public boolean action(
            InternalSession is,
            Map<String, Long> existingSessions) {
        for (Map.Entry<String, Long> entry : existingSessions.entrySet()) {
            try {
                // Get a Session from the cache based on the session ID, and destroy it.
                SessionID sessionId = new SessionID(entry.getKey());
                Session session = sessionCache.getSession(sessionId);
                session.destroySession(sessionId);
                // Only destroy the first session.
                break;
            } catch (SessionException se) {
                if (debug.messageEnabled()) {
                    debug.message("Failed to destroy existing session.", se);
                }
                // In this case, deny the session activation request.
                return true;
            }
        }
        return false;
    }
}

If you have not already done so, download and build the sample code.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for OpenAM 12.x, 13.x and AM (All versions)? in the Knowledge Base.

In the sources, you find the following files:

Once built, copy the .jar to WEB-INF/lib/ where AM is deployed.

$ cp target/*.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/

Using the ssoadm command, update the Session Service configuration:

$ ssoadm \
 set-attr-choicevals \
 --adminid amadmin \
 --password-file /tmp/pwd.txt \
 --servicename iPlanetAMSessionService \
 --schematype Global \
 --attributename iplanet-am-session-constraint-handler \
 --add \
 --choicevalues myKey=\
org.forgerock.openam.examples.quotaexhaustionaction.SampleQuotaExhaustionAction

Choice Values were set.

Extract amSession.properties and if necessary the localized versions of this file from openam-core-5.5.2.jar to WEB-INF/classes/ where AM is deployed. For example, if AM is deployed under /path/to/tomcat/webapps/openam, then you could run the following commands.

$ cd /path/to/tomcat/webapps/openam/WEB-INF/classes/
$ jar -xvf ../lib/openam-core-5.5.2.jar amSession.properties
 inflated: amSession.properties

Add the following line to amSession.properties.

myKey=Randomly Destroy Session

Restart AM or the container in which it runs.

You can now use the new session quota exhaustion action. In the AM console, navigate to Configure > Global Services, click Session, scroll to Resulting behavior if session quota exhausted, and then choose an option.

Before moving to your test and production environments, be sure to add your .jar file and updates to amSession.properties into a custom .war file that you can then deploy. You must still update the Session service configuration in order to use your custom session quota exhaustion action.

List session quota exhaustion actions by using the ssoadm command:

$ ssoadm \
 get-attr-choicevals \
 --adminid amadmin \
 --password-file /tmp/pwd.txt \
 --servicename iPlanetAMSessionService \
 --schematype Global \
 --attributename iplanet-am-session-constraint-handler

I18n Key                  Choice Value
------------------------- ---...-----------------------------------------
choiceDestroyOldSession   org...session.service.DestroyOldestAction
choiceDenyAccess          org...session.service.DenyAccessAction
choiceDestroyNextExpiring org...session.service.DestroyNextExpiringAction
choiceDestroyAll          org...session.service.DestroyAllAction
myKey                     org...examples...SampleQuotaExhaustionAction

Remove a session quota exhaustion action by using the ssoadm command:

$ ssoadm \
 remove-attr-choicevals \
 --adminid amadmin \
 --password-file /tmp/pwd.txt \
 --servicename iPlanetAMSessionService \
 --schematype Global \
 --attributename iplanet-am-session-constraint-handler \
 --choicevalues \
 org.forgerock.openam.examples.quotaexhaustionaction.SampleQuotaExhaustionAction

Choice Values were removed.

The following properties are available under the Global Attributes tab:

The following properties are available under the Core tab:

The following properties are available under the User Profile tab:

The following properties are available under the Account Lockout tab:

The following properties are available under the General tab:

The following properties are available under the Security tab:

The following properties are available under the Post Authentication Processing tab:

ssoadm service name: sunAMAuthADService

ssoadm service name: sunAMAuthAdaptiveService

ssoadm service name: iPlanetAMAuthAnonymousService

ssoadm service name: iPlanetAMAuthCertService