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.

OpenAM 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 OpenAM 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 OpenAM. 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 OpenAM:

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

To receive push notifications when authenticating, end users must register an Android or iOS device with OpenAM. The registered device can then be used as an additional factor when authenticating to OpenAM. OpenAM 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 OpenAM.

Overview of Push Authentication

The following steps occur when OpenAM 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".

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

1.8.1.6. Session Cookies

OpenAM 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 size of this cookie's value is relatively small—approximately 100 bytes—and contains a reference to the stateful session in the CTS token store and several other pieces of information. For stateless sessions, the iPlanetDirectoryPro cookie is considerably larger—approximately 2000 bytes or more—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

The preceding diagram illustrates the difference between stateful and stateless session cookie values. Note that the diagram is not to scale. The iPlanetDirectoryPro cookie for a stateless session is more than ten times larger than for a stateful session.

The size of the stateless session cookie increases when you customize OpenAM 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.8.1.6.1. Stateless Session Cookie Security

When using stateless session cookies, you should configure OpenAM 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

OpenAM sets the iPlanetDirectoryPro cookie in the user's browser as proof of previous authentication whenever single sign-on is desired. OpenAM verifies that the cookie is authentic by validating a signature configured in the Session Service. OpenAM 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 OpenAM 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 OpenAM session. Encryption also ensures that end users are unable to access the information in their OpenAM session.

As shown in "About Authentication Levels", authentication modules are configured with an authentication level. This configuration sets the level of security associated with the module, Stronger forms of authentication are assigned higher authentication levels. (Or lower authentication level numbers if the deployment defines stronger authentication with lower authentication level numbers.) Upon successful authentication, a user's session includes information about the authentication level achieved.

Authorization policies can require a particular authentication level for access to sensitive resources (or at most or at least a specified authentication level). When a user who is already authenticated in the realm tries to access a sensitive resource with a valid session that does not have the requisite authentication level, OpenAM denies access to the resource. However, OpenAM also returns advices with the authorization decision. The advices indicate the need for the required authentication level. The policy agent or policy enforcement point can then send the user back to OpenAM 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, OpenAM redirects the user's browser to the success URL from the last successful authentication.

OpenAM policy agents generally handle session upgrade without additional configuration, as policy agents are built to handle OpenAM's advices. If you build your own policy enforcement point (PEP), however, 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".

OpenAM's support for session upgrades requires stateful sessions. Be sure that OpenAM is configured for stateful sessions—the default configuration—before attempting to upgrade OpenAM sessions.

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.

OpenAM 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, OpenAM takes the appropriate action.

See "Implementing Session Quotas" for instructions.

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

OpenAM uses HTTP cookies to track user sessions. If you are unfamiliar with HTTP cookies, see "About HTTP Cookies" for more information.

The following diagram illustrates how OpenAM assigns and tracks cookies:

SSO With Policy Agent

A client points their browser to a protected resource application. An agent on 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 OpenAM for authentication (AuthN). The client is then sent to OpenAM for 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:

1.9.1.2. Cross-Domain SSO

When you have multiple domains in a single organization, CDSSO lets your OpenAM servers in one domain work with policy agents from other domains.

Cross-domain single sign-on provides a safe mechanism for managing access across multiple, different domains that you control. CDSSO lets OpenAM authenticate users redirected by policy agents in other DNS domains.

CDSSO is an OpenAM-specific capability. For single sign-on across multiple organizations or when integrating with other access management software, use OpenAM's federation capabilities.

CDSSO requires stateful OpenAM sessions. Be sure that OpenAM is configured for stateful sessions—the default configuration—before attempting to use CDSSO.

Single sign-on depends on cookies to store session information. Yet for security reasons, browsers do not let a web site in one domain to get access to a cookie from another domain. With CDSSO, the policy agents work around this by negotiating with OpenAM to allow access.

The Java EE policy agent allows CDSSO by using a mechanism to write the SSO token from OpenAM authentication to a cookie with the domain of the host where the agent runs. The following sequence diagram illustrates this mechanism.

Java EE Policy Agent Mechanism for CDSSO

Whereas the Java EE policy agent has an endpoint specifically to handle the cookie domain translation, the web policy agent handles the request directly as shown in the following sequence diagram.

Web Policy Agent Mechanism for CDSSO

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

OpenAM connects to Active Directory over Lightweight Directory Access Protocol (LDAP). OpenAM 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 OpenAM 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, OpenAM has users authenticate first using the LDAP module providing a user ID and password combination. Upon success, OpenAM 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 OpenAM finishes authentication processing without requiring further credentials. Otherwise, the Adaptive Risk module evaluates the score to be above the risk threshold, and returns failure. OpenAM 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, OpenAM performs the save as post-authentication processing, only after the entire authentication chain returns success. You must set up OpenAM 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 OpenAM 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 OpenAM 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 OpenAM 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, OpenAM 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 OpenAM 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 OpenAM scripting supports both the JavaScript (default) and Groovy languages, only server-side scripts can be writtern 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 OpenAM, 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 OpenAM, 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 OpenAM, 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 OpenAM, 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 OpenAM 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".

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

For detailed information about this module's configuration properties, see "LDAP 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 OpenAM 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. OpenAM 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 OpenAM 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 OpenAM. 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 OpenAM, 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 OAuth 2.0/OpenID Connect authentication module lets OpenAM 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, OpenAM 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 "OAuth 2.0/OpenID Connect Authentication Module Properties".

The OpenID Connect id_token bearer module lets OpenAM 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 OpenAM 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 OpenAM user.

You configure the OpenID Connect id_token bearer module to specify how OpenAM 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 OpenAM user profile.

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 OpenAM. The Persistent Cookie module encrypts a JSON Web Token (JWT) using a public key from the OpenAM 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 OpenAM instances.

When the Persistent Cookie module enforces the client IP address, and OpenAM 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 OpenAM 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 OpenAM 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 OpenAM authenticate a user who has already authenticated with an entity that can vouch for the user to OpenAM, so that OpenAM creates a session for the user. This module is useful in virtual federation, where an existing entity instructs the local OpenAM 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 OpenAM 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 OpenAM 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 OpenAM configuration data. This makes it easy to update a script on one OpenAM 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 OpenAM 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 Windows Desktop SSO module uses Kerberos authentication. The user presents a Kerberos token to OpenAM 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 OpenAM 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 OpenAM authenticate against a Microsoft Windows NT server.

This module requires that you install a Samba client in a bin directory under the OpenAM 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.

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

To use social authentication as part of a ForgeRock Identity Platform full stack 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 OpenAM 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. OpenAM 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 OpenAM using a recovery code instead of performing multi-factor authentication.

Unless the OpenAM 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. ^[1] 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 OpenAM.

The decision to opt out of using one-time passwords in OpenAM 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 OpenAM and then lose it, you must authenticate to OpenAM 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 OpenAM 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 OpenAM rejects the passwords as unauthorized, it is likely that your device has become out of sync with OpenAM.

When a registered device becomes out of sync with OpenAM, you must authenticate to OpenAM 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 OpenAM 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 OpenAM 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.

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

An administrator or a user can perform an HTTP POST to the /users/user/devices/2fa/oath?_action=reset endpoint to reset the user's device profile.

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 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}

Session blacklisting uses the Core Token Service's token store during the logout process. For more information about deploying the Core Token Service, see "Implementing the Core Token Service" in the Installation Guide.

Also, ensure the trust store used by OpenAM has the necessary certificates installed:

The same certificates must be stored on all servers participating in an OpenAM site.

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

To verify that OpenAM 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 OpenAM, see "Setting Up Keys and Keystores" in the Setup and Maintenance Guide.

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

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

You can configure HttpOnly using the administration console:

In general, problems with SSO relate to some sort of mismatch of domain names. For example, a cookie that is configured on a third-level domain, such as sso.example.net will not work with an application on a similar domain, such as app.example.net. Even if the Session ID is valid, the application will not receive the SSO Token. The request is then redirected to OpenAM. The client gets what appears as a SSO Token in the diagram, which is actually a valid SSO tracking cookie that redirects immediately, and the cycle continues. Other issues that may lead to similar problems are shown here:

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, OpenAM 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.

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

OpenAM 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

OpenAM 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 OpenAM 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 OpenAM authentication module must extend the com.sun.identity.authentication.spi.AMLoginModule abstract class, and must implement the methods shown below.

See the OpenAM Java SDK API Specification for reference.

// OpenAM calls the init() method once when the module is created.
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()

OpenAM 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();
    }
}

OpenAM requires that all authentication modules be configured by means of an OpenAM 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 OpenAM.

Authentication modules are registered as services with OpenAM 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.

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

OpenAM calls the onLoginSuccess() and onLoginFailure() methods immediately before informing the user of login success or failure, respectively. OpenAM calls the onLogout() method only when the user actively logs out, not when a user's session times out.

See the OpenAM Java SDK API Specification for reference.

These methods can perform whatever processing you require. Yet, know that OpenAM 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. OpenAM 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
    }
}

The sample post authentication plugin source is available online. Get a local clone so that you can try the sample on your system. In the sources you find the following files.

Build the module using Apache Maven.

$ cd /path/to/openam-post-auth-sample
$ mvn install
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building openam-post-auth-sample 1.0.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------

...

[INFO]
[INFO] --- maven-jar-plugin:2.3.1:jar (default-jar) @ openam-post-auth-sample --
[INFO] Building jar: .../target/openam-post-auth-sample-1.0.0-SNAPSHOT.jar

...

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 6.727s
[INFO] Finished at: Mon Nov 25 17:07:23 CET 2013
[INFO] Final Memory: 20M/227M
[INFO] ------------------------------------------------------------------------

Copy the .jar to the WEB-INF/lib directory where you deployed OpenAM.

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

Restart OpenAM 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 OpenAM 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 OpenAM calls your plugin, a policy 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 OpenAM. You must also add your new action to the Session service configuration, and restart OpenAM 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;
    }
}

The sample plugin source is available online. Get a local clone so that you can try the sample on your system. In the sources you find the following files.

Build the module using Apache Maven.

$ cd /path/to/openam-examples-quotaexhaustionaction
$ mvn install
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building OpenAM Example Quota Exhaustion Action 1.0.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------

...

[INFO]
[INFO] --- maven-jar-plugin:2.3.1:jar (default-jar) @ quotaexhaustionaction ---
[INFO] Building jar: .../target/quotaexhaustionaction-1.0.0-SNAPSHOT.jar

...

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Copy the .jar to WEB-INF/lib/ where OpenAM 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-14.0.0.jar to WEB-INF/classes/ where OpenAM is deployed. For example, if OpenAM 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-14.0.0.jar amSession.properties
 inflated: amSession.properties

Add the following line to amSession.properties.

myKey=Randomly Destroy Session

Restart OpenAM 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

ssoadm service name: sunAMAuthDataStoreService

ssoadm service name: iPlanetAMAuthDeviceIdMatchService

ssoadm service name: iPlanetAMAuthDeviceIdSaveService

ssoadm service name: sunAMAuthFederationService

amster service name: iPlanetAMAuthAmsterService

ssoadm service name: iPlanetAMAuthAuthenticatorOATHService

ssoadm service name: iPlanetAMAuthAuthenticatorPushService

ssoadm service name: iPlanetAMAuthAuthenticatorPushRegistrationService

ssoadm service name: sunAMAuthHOTPService

ssoadm service name: iPlanetAMAuthHTTPBasicService

ssoadm service name: sunAMAuthJDBCService

ssoadm service name: iPlanetAMAuthLDAPService

ssoadm service name: sunAMAuthMSISDNService