# OpenAM Administration Guide
2.2. Configuring Authentication Modules

Sidebar | Prev | Up | Next

### 2.2.15. Hints For the OATH Module

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 OpenAM to match their device.

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

ssoadm service name: `iPlanetAMAuthOATHService`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-oath-auth-level`

One Time Password Length (in digits)

  Set the length of the OTP between 6 and 9 digits long. The default value is 6 digits.

  ssoadm attribute: `iplanet-am-auth-oath-password-length`

Minimum Secret Key Length

  The minimal number of characters required to set the Secret Key.

  ssoadm attribute: `iplanet-am-auth-oath-min-secret-key-length`

Secret Key Attribute Name

  The name of the attribute where the key will be stored in the user profile.

  ssoadm attribute: `iplanet-am-auth-oath-secret-key-attribute`

OATH Algorithm to Use

  Select whether to use HOTP or TOTP. You can create an authentication chain to allow for a greater variety of devices. The default value is HOTP.

  ssoadm attribute: `iplanet-am-auth-oath-algorithm`

HOTP Window Size

  The number of requests that the system and the device can be off to resynchronize the password. If a user passes this number of requests before logging into the system, the password will not work. The default value is 100.

  ssoadm attribute: `iplanet-am-auth-oath-hotp-window-size`

Counter Attribute Name

  The name of the HOTP attribute where the counter will be stored in the user profile.

  ssoadm attribute: `iplanet-am-auth-oath-hotp-counter-attribute`

Add Checksum Digit

  Adds a checksum digit at the end of the HOTP password to verify it was entered correctly. The default value is No.

  ssoadm attribute: `iplanet-am-auth-oath-add-checksum`

Truncation Offset

  Advanced feature that is device specific. Any value below 0 or above 15 will turn off the functionality. The default value is -1. If not required by the device, leave at the default setting.

  ssoadm attribute: `iplanet-am-auth-oath-truncation-offset`

TOTP Time Step Interval

  Defines how long the password will appear on the user's device (in seconds). We recommend keeping this number low, for example 30 seconds, because once a user logs out, they will not be able to login again until two full time cycles have passed. The default value is 30 seconds.

  ssoadm attribute: `iplanet-am-auth-oath-size-of-time-step`

TOTP Time Steps

  The number of requests that the system and the device can be off to resynchronize the password. If a user passes this number of requests before logging into the system, the password will not work. The default value is 2.

  ssoadm attribute: `iplanet-am-auth-oath-steps-in-window`

Last Login Time Attribute

  The name of the attribute where both HOTP and TOTP authentication will store information on when a person last logged in.

  ssoadm attribute: `iplanet-am-auth-oath-last-login-time-attribute-name`

If you plan to use Yubikey for your OATH module, you will need to take some time to set it up. Go to the YubiKey website to configure your YubiKey device. If you do not have a YubiKey device, you can purchase them from this page as well.

Select the appropriate instructions, keeping in mind that the cross-platform personalization tool is recommended unless you have specific need for one of the other types. You have the greatest selection of platforms for this choice. Each device will need to be setup before use.