OATH OTP authentication

Airlock IAM supports authentication with software- and hardware-based OATH OTP one-time codes. OATH is a standard supported by many mobile apps and hardware tokens. There are two types of OTP generation algorithms:

  • Time-based (TOTP) according to RFC6238
  • Event-based (HOTP) according to RFC6238

It can be used with many freely available smartphone apps.

Known-to-work mobile apps

The following mobile apps are known to work with Airlock IAM. The mobile apps have been tested with Airlock IAM but are not continuously tested with every release.

  • Google Authenticator
  • Microsoft Authenticator
  • FreeOTP
  • Duo Mobile
  • HDE OTP

Airlock and Ergon are not responsible for the apps' security or proper functioning.

Supported features in IAM

  • time-based OTP (TOTP) and event-based OTP (HOTP)
  • auto-adjustment of time- or event-offset
  • configurable window size
  • generation of QR codes to transport the seed to the mobile app (enrollment)
  • store seeds encrypted

For more information about all configuration options, please consult the Config Editor documentation of the OATH OTP Settings plugin.

Limitations

  • The following limitations apply when using OATH OTP in Airlock IAM:
  • only one OATH OTP seed (or account) per user
  • no enrollment self-service
  • no import or export of externally stored seeds (e.g. for hardware devices)
  • no smartphone app
  • in multi-instance setups (e.g. active-active setups with load balancing), it is essential to externalize the session state. Otherwise, the detection of a replay attack, i.e., using the same OTP on multiple instances, may fail.

Airlock 2FA also offers OTP-based authentication plus much more features. See Airlock 2FA as the second factor with IAM.

Token management and enrollment of apps

To enroll an OTP app on a smartphone, the seed (shared secret) of a user's OTP token needs to be transported from IAM to the app. 

The seed (shared secret) can be displayed in the IAM Adminapp either as QR-code or in various other formats (HEX, base-64):

Adminapp - menu Users, tab OATH OTP

Access control hint

The seed (shared secret) shown in the Adminapp is very sensitive information. It requires specific access rights in the Adminapp's access controller configuration.

To display the seed or QR-code in the Adminapp (or access them using the Adminapp REST API ) the access rights must be set up as shown in the following example.

56468039.png

OATH OTP QR-code letters

The IAM task OATH OTP Letter Task generates letters (usually PDFs) containing the QR-code needed to enroll a mobile app. The letter can be ordered in the Adminapp (or using the Adminapp REST API).

When providing texts for OATH OTP QR-code letter templates, make sure the end-user understands, that the QR-code is a sensitive piece of information that can be used to enroll multiple apps.

Having access to the QR-code letter is equivalent to having the ability to enroll the token on any smartphone. The letter should either be safely stored or destroyed after usage.