MFA: Open AuTHentication (OATH)

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

Differences Among Authentication Modules That Support HOTP

Note

AM provides two authentication modules that support OATH:

The ForgeRock Authenticator (OATH) authentication module, which is optimized for use with the ForgeRock Authenticator app and provides device profile encryption.
The OATH authentication module, which is a raw OATH implementation requiring more configuration for users and the AM administrator.

We recommend using the ForgeRock Authenticator (OATH) authentication module when possible.

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:

The ForgeRock Authenticator (OATH) and OATH authentication modules accept one-time passwords generated by the end user's device, while the HOTP authentication module generates passwords and sends them to users by e-mail or SMS.
All three of the authentication modules support HOTP passwords. The ForgeRock Authenticator (OATH) and OATH authentication modules also support TOTP passwords.
The ForgeRock Authenticator (OATH) and OATH authentication modules require users to register their devices, and store the device registration details in the user profile. The HOTP authentication module requires the presence of mobile phone numbers and/or e-mail addresses in user profiles.
The ForgeRock Authenticator (OATH) authentication module can encrypt stored device registration details.

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

Comparing the ForgeRock Authenticator (OATH) to the HOTP Authentication Module

Requirement	Available With the ForgeRock Authenticator (OATH) Authentication Module?	Available With the HOTP Authentication Module?
End users can authenticate using a HOTP password		
AM can generate a HOTP password and send it to end users in a text message or an e-mail		
End users can register a mobile phone with AM, and an authenticator app on the phone can generate a HOTP or TOTP password that AM accepts as proof of authentication		
End users can authenticate with a TOTP password		
End users can opt out of providing a one-time password		
End users can authenticate using XUI		

One-Time Password Authentication Using Trees

This section describes how to create and configure trees for one-time password authentication.

Create a Tree for One-Time Password Authentication

To create an example authentication tree that uses OATH authentication, perform the following steps:

In the AM console, select the realm that will contain the authentication tree.
Select Authentication > Trees, and then click +Create Tree.
Type a name for your tree in the New Tree page; for example, myAuthTree, and click Create.
The authentication tree designer page is displayed with default Start, Failure, and Success nodes.
For information about using the authentication tree designer, see Create an Authentication Tree.
Add the following nodes to the designer area:
Connect the nodes as shown:
Type 'OATH' to filter the list of nodes in the Components panel box:
Drag an OATH Token Verifier node and an OATH Registration node onto the designer area.
For both OATH nodes, set the OATH Algorithm property to TOTP, and connect to the existing nodes as follows:
The value for OATH Algorithm must be the same for both nodes. For this example, select TOTP to generate a new OTP at a specified time step interval.
Save your changes.
Note that the tree you have created is a simple example for the purposes of demonstrating a basic OATH authentication journey. In a production environment, you could include additional nodes, such as:
"MFA Registration Options Node"
Provides options for users to register a multi-factor authentication device, get the authenticator app, or skip the registration process.
"Opt-out Multi-Factor Authentication Node"
Sets an attribute in the user’s profile which lets them skip multi-factor authentication.
"Recovery Code Display Node"
Lets a user to view recovery codes to use in case they have lost or damaged their registered authenticator device.
"Retry Limit Decision Node"
Lets a journey loop a specified number of times, for example, to allow a user to retry entering their OATH token.
For information about how to configure these nodes, see "Authentication Nodes Configuration Reference".
Test your authentication tree as follows:
1. Log out of AM, and then navigate to a URL similar to the following: https://openam.example.com:8443/openam/XUI/?realm=alpha&service= myAuthTree#login
  A login screen appears, prompting you to enter your user ID and password.
2. Log in using the user name and password. For example, enter demo, and the password Ch4ng31t.
3. On successful login, if the screen displays a QR code, you will need to register your device.
  To register the device with the ForgeRock Authenticator, follow the instructions as described in Register the ForgeRock Authenticator for MFA.
4. Follow the procedure described in "Perform Authentication Using a One-Time Password" to verify that you can authenticate using the ForgeRock Authenticator app.

Perform Authentication Using a One-Time Password

This example task assumes the following prerequisites:

The authentication tree is set up as described in "Create a Tree for One-Time Password Authentication".
You have successfully logged in with valid credentials.
You have registered your device for ForgeRock Authenticator (OATH) authentication.

Follow these steps to complete one-time password (OTP) authentication:

On your registered device, open the ForgeRock Authenticator app, and then tap the OTP section for the account matching the user ID. For example:
Note the OTP that is displayed on the screen. This is automatically refreshed at an interval defined in the "OATH Token Verifier Node". If the animated timer indicates the OTP is close to expiry, wait until a new OTP is generated.
On the ForgeRock Authenticator (OATH) page in AM, enter the OTP that the authenticator app generated on your phone, and then click Submit:
AM displays the user's profile page.

One-Time Password Authentication Using Chains

This section covers one-time password authentication.

Create a Chain for One-Time Password Authentication

The procedure assumes the following:

Users will provide user IDs and passwords as the first step of multi-factor authentication.
An existing Data Store authentication module will collect and verify user IDs and passwords.
All authentication modules in the chain will use the Requisite flag setting. See "Authentication Modules and Chains" for details about authentication module flag settings.
Users can opt out of one-time password authentication.
The ForgeRock Authenticator (OATH) Service is configured.
This service specifies the attribute in which to store information about the registered OATH device, and whether to encrypt that information. It also specifies the attribute used to indicate if a user has opted out of one-time passwords.
For detailed information about the available properties, see "ForgeRock Authenticator (OATH) Service".

To create a multi-factor authentication chain that uses the ForgeRock Authenticator (OATH) module, perform the following steps:

In the AM console, select the realm that will contain the authentication chain.
You can allow users to opt out of using OATH-based one-time passwords as follows:
1. Select Authentication > Settings > General.
2. Make sure that the Two Factor Authentication Mandatory is not enabled.
  See General for details about this configuration setting.
For information about how letting users skip multi-factor authentication impacts the behavior of authentication chains, see "Letting Users Opt Out of One-Time Password Authentication (OATH)".
Create a ForgeRock Authenticator (OATH) authentication module as follows:
1. Select Authentication > Modules, and then click Add Module.
  The New Module page appears.
2. Fill in fields in the New Module page as follows:
  - Name: Specify a module name of your choosing.
  - Type: Select ForgeRock Authenticator (OATH).
3. Click Create.
  A page that lets you configure the authentication module appears.
4. Configure the ForgeRock Authenticator authentication module to meet your organization's requirements.
  For more information about the authentication module's configuration settings, see "ForgeRock Authenticator (OATH) Authentication Module".
Create the authentication chain as follows:
1. Select Authentication > Chains, and then click Add Chain.
  The Add Chain page appears.
2. Specify a name of your choosing, for example myOATHAuthChain, and then click Create.
  A page appears with the Edit Chain tab selected.
3. Click Add a Module. Fill in fields in the New Module dialog box as follows:
  - Select Module: Select the existing Data Store module to use in this chain.
  - Select Criteria: Select a flag setting for the module in the authentication chain. For this example, specify the Requisite flag.
    See "Authentication Modules and Chains" for information about authentication module flag settings.
4. Click OK.
  A graphic showing an authentication chain with a single Data Store module appears on the page.
5. Add the ForgeRock Authenticator (OATH) authentication module to the authentication chain as follows:
  1. Click Add a Module.
    The New Module dialog box appears.
  2. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (OATH) authentication module that you just created. For this example, specify the Requisite flag.
  3. Click OK.
    The graphic showing your authentication chain now includes the Data Store and ForgeRock Authenticator (OATH) authentication module.
6. Save your changes.
Test your authentication chain as follows:
1. Log out of AM, and then navigate to a URL similar to the following: https://openam.example.com:8443/openam/XUI/?realm=/&service=myOATHAuthChain#login
  A login screen prompting you to enter your user ID and password appears.
2. Follow the procedure described in "To Perform Authentication using a One-Time Password" to verify that you can use the ForgeRock Authenticator app to perform multi-factor authentication. If the chain is correctly configured, authentication is successful and AM displays the user profile page.

To Perform Authentication using a One-Time Password

This example uses the authentication chain as created in "One-Time Password Authentication Using Chains".

Because the first module in the authentication chain is a Data Store module, AM presents you with a page for entering your user ID and password. After you provide those credentials, AM verifies them. If your credentials are valid, AM proceeds to the ForgeRock Authenticator (OATH) authentication module.

On the ForgeRock Authenticator (OATH) screen, follow these steps to complete one-time password authentication:

On your registered device, open the ForgeRock Authenticator app, and then tap the account matching the user ID you entered earlier. The registered authentication methods for that account are displayed:
In the One-time Password section, click the refresh icon. A one-time password is displayed:
On the ForgeRock Authenticator (OATH) page in AM, enter the one-time password that the authenticator app generated on your phone, and then click Submit:
AM will display the user's profile page.

Letting Users Opt Out of One-Time Password Authentication (OATH)

Letting users opt out of providing one-time passwords when they perform multi-factor authentication is an important implementation decision. The Two Factor Authentication Mandatory setting under Realms > Realm Name > Authentication > Settings > General configures whether users can opt out.

When the Two Factor Authentication Mandatory setting is enabled, users must provide a one-time password every time they authenticate to a chain that includes a ForgeRock Authenticator (OATH) authentication module. When the setting is disabled, the user can optionally skip one-time passwords.

By default, AM lets users opt out of providing one-time passwords. Users authenticating with one-time passwords for the first time are prompted with a screen that lets them opt out of providing one-time passwords.

With the Two Factor Authentication Mandatory setting enabled, the user experience differs from the default behavior. AM does not provide an option to skip multi-factor authentication during the initial attempt at multi-factor authentication:

When configuring an authentication chain that implements one-time passwords, you need to be aware that a user's decision to opt out affects the authentication process. When a user who has opted out of providing one-time passwords authenticates to a chain that includes a ForgeRock Authenticator (OATH) authentication module, that module always passes authentication.

Consider the example authentication chain in "One-Time Password Authentication Using Chains". The first authentication module is a Data Store module and the second authentication module is a ForgeRock Authenticator (OATH) module. Both authentication modules have the Requisite flag setting.

A user who has opted out of providing one-time passwords might experience the following sequence of events when authenticating to the chain:

The Data Store authentication module prompts the user to provide a user ID and password.
The user provides a valid user ID and password.
Data Store authentication passes, and authentication proceeds to the next module in the chain—the ForgeRock Authenticator (OATH) module.
The ForgeRock Authenticator (OATH) authentication module determines that the user has opted out of providing one-time passwords.
ForgeRock Authenticator (OATH) authentication passes. Because it is the last authentication module in the chain, AM considers authentication to have completed successfully.

Contrast the preceding sequence of events to the experience of a user who has not opted out of providing one-time passwords, or who is required to provide one-time passwords, while authenticating to the same chain:

The Data Store authentication module prompts the user to provide a user ID and password.
The user provides a valid user ID and password.
Data Store authentication passes, and authentication proceeds to the next module in the chain—the ForgeRock Authenticator (OATH) module.
The ForgeRock Authenticator (OATH) authentication module determines that the user has not opted out of providing one-time passwords, and prompts the user for a one-time password.
The user obtains a one-time password from the authenticator app on their mobile phone.
If the one-time password is valid, ForgeRock Authenticator (OATH) authentication passes. Because it is the last authentication module in the chain, AM considers authentication to have completed successfully. However, if the one-time password is not valid, ForgeRock Authenticator (OATH) authentication fails, and AM considers authentication to have failed.

Opting Out of One-Time Password Authentication (OATH)

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:

When users are prompted to register their mobile devices during their initial login from a new device.
Every time users are prompted by the ForgeRock Authenticator (OATH) authentication module to enter one-time passwords.

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:

To Opt out or Opt in to Using One-Time Passwords

Log in to AM.
Select Dashboard from the top navigation bar.
In the Authentication Devices section of the Dashboard page, click the context menu button for the chosen device, and then click Settings:
Enable or disable the multi-factor authentication option:
Click Save.

^[3]For information about making the usage of one-time passwords mandatory in AM, see "Letting Users Opt Out of One-Time Password Authentication (OATH)".