One-Time Password (OTP) Authentication#
This document explains how to use the Gluu Server's included OTP interception script to implement a two-step, two-factor authentication (2FA) process with username / password as the first step, and any OTP app as the second step.
To support SMS OTP, follow the SMS OTP documentation.
- A Gluu Server (installation instructions)
- HOTP / TOTP authentication script (included in the default Gluu Server distribution)
- A device with an OTP mobile app installed, like one of the apps listed below
Recommended OTP apps#
The OTP authentication script has the following properties:
|issuer||Issuer of the OTP service||Gluu Inc|
|label||The name of the application||Gluu OTP|
|otp_conf_file||Location of the OTP configuration file||
|otp_type||Type of OTP in use||totp or hotp|
|qr_options||Size of the QR code that is used for device enrollment|
|registration_uri||Registration endpoint of the IDP||
Follow the steps below to enable Super Gluu authentication:
- In oxTrust, navigate to
Person Authentication Scripts
- Find the OTP script
- Enable the script by checking the box
- Scroll to the bottom of the page and click
Now OTP is an available authentication mechanism for your Gluu Server. This means that, using OpenID Connect
acr_values, applications can now request OTP authentication for users.
Make OTP the Default#
If OTP should be the default authentication mechanism, follow these instructions:
Default Authentication Methodtab
In the Default Authentication Method window you will see two options:
oxTrust acrsets the authentication mechanism for accessing the oxTrust dashboard GUI (only managers should have acccess to oxTrust)
Default acrsets the default authentication mechanism for accessing all applications that leverage your Gluu Server for authentication (unless otherwise specified)
If OTP should be the default authentication mechanism for all access, change both fields to OTP.
OTP Login Pages#
The Gluu Server includes two default login pages for OTP:
An enrollment page that is displayed the first time a user is prompted for OTP authentication;
A login page that is displayed for all subsequent OTP authentications.
Using OTP Apps#
OTP device enrollment happens during the first authentication attempt. The initial enrollment page displays a QR code that needs to be scanned with the OTP app.
All subsequent authentications will require the user to retreive and enter an OTP from the application.
A user's OTP device(s) can be removed by a Gluu administrator either via the oxTrust UI in
Manage People, or in LDAP under the user entry. In LDAP, navigate to appliances and search for an attribute
oxExternalUid. Remove the values of this attribute. Upon the next OTP login attempt, the user will be prompted to enroll a new device.
Notes on TOTP usage#
OTP custom script works in one of two modes: TOTP (time-based) or HOTP (even-based). When using time-based flavor of OTP, mobile applications generate codes based on the current time of the device, this code is validated by the server using its own time. As consequene, significant time lags can provoke authentication failures.
It's out of admins control have users devices in a consistent time, but they can maintain server system time accurately. For this you can follow any of the different approaches for linux time synchronization over the network, the most common being ntp.
Self-service account security#
To offer end-users a portal where they can manage their own account security preferences, including two-factor authentication credentials like OTP apps, check out our new app, Gluu Casa.