TOTP Authentication Method
Introduction
This documentation describes the requirements and tasks for enabling and configuring Time-based One-time Password (TOTP) authentication method in an Ubisecure SSO. The result of the configuration described in this page is a working TOTP authentication method.
TOTP method can be used for integrating SSO with Google Authenticator or other RFC-6238 compliant authenticators as the second factor step-up method for password authentication. It's recommended that TOTP is not used as the only step-up method, because the authenticator application may get lost or damaged, in which case it may be impossible to recover the lost key. Therefore it's recommended that OTP list or SMS OTP could be used as a backup method.
Before Using
System requirements
- Ubisecure SSO 8.6 (found in IDS 2020.2 release) or later
Configuring the TOTP Authentication Method
Management UI
In the SSO Management UI and navigate to the "Global Method Settings".
Create a new authentication method:
- Add Title e.g: Acme Authenticator
- Add name e.g: acme.totp.1
- Choose Method Type: SPI TOTP
|
|---|
In the Directory selection choose the Directory Service where user accounts are stored. TOTP method supports all directory types including SQL directories.
Open the entry "SPI TOTP" and modify the necessary parameters in Main tab.
- Select the Global Method Settings in Ubisecure Management after logging in as administrator
- Select the SPI TOTP authentication method
- Set Status enabled
Then, select the tab "SPI TOTP" to configure the TOTP specific settings.
|
|---|
Management API
The same configuration as above can be created using the Management API. You need to do two separate calls to configure the method and link it to a directory.
/sso-api/method/acme.totp.1
| Method | Description | Example payload |
|---|---|---|
| PUT | Create or update TOTP method. If configuration values are left out the defaults from below will be used. | methodType=SPI TOTP |
/sso-api/directory/Ubilogin%20Directory/$link/method/acme.totp.1
| Method | Description | Example payload |
|---|---|---|
| PUT | Link a directory to the authentication method | No actual payload as the parameters Ubilogin Directory and acme.totp.1 are URL encoded in path variables. |
Configuration explanations
TOTP Validation Configuration
Modifying TOTP Validation Configuration parameters immediately affects validation of codes for all users of the authentication method.
TOTP Past Window
Number time steps in the past with valid codes. Can be a number between 0 and 9. Default is 1.
API key: totpWindowBefore
TOTP Future Window
Number time steps in the future with valid codes. Can be a number between 0 and 9. Default is 0.
API key: totpWindowAfter
TOTP Key Generation Configuration
Modifying TOTP Key Generation Configuration parameters have no effect on users already having keys associated with their accounts - only newly generated keys are affected.
Exact values needed depend on the requirements of the TOTP Authenticator.
TOTP Length
The length of TOTP codes in digits. Can be a number between 4 and 8. Default is 6.
API key: totpDigits
TOTP Algorithm
The algorithm in which the TOTP algorithm is based on. Can be either HmacSHA1, HmacSHA256 or HmacSHA512. Default is HmacSHA1.
API key: totpAlgorithm
T0
The Unix time in milliseconds to start counting time steps. Default is 0.
API key: totpT0
Time Step
The duration of one time step in milliseconds. Default is 30000.
API key: totpTimeStep
Key Size
The length of generated keys in bytes. Can be a number between 10 and 99. Default is 20.
API key: totpKeySize
After Configuring the TOTP Method
Configuring TOTP Authentication Method for Web Applications
After installing and configuring TOTP authentication method for the Ubisecure SSO, please refer to SSO Management Guide for enabling an authentication method for users and applications.
Managing TOTP Secrets for Ubilogin Directory Users
There are two ways managing TOTP secrets for Ubilogin Directory Users.
- Ubilogin Management UI
- TOTP API
Managing secrets with Ubilogin Management UI
The TOTP specific user information is stored in the built-in Ubisecure Directory regardless of the directory. However TOTP secrets can be managed from Management UI for Ubilogin Directory users only.
In order to activate TOTP authentication method for an Ubilogin Directory user, you must first:
- Add the TOTP authentication method to the Site of the User
- Enable the TOTP authentication method for the User
After that you can open the TOTP authentication method configuration window for the User, which is shown below.
|
|---|
| Manage TOTP authentication method for a Ubilogin Directory user |
In TOTP authentication method configuration window for the User you can either:
- Generate a new TOTP secret by clicking the "Reset" button
- Set a new secret by entering a Base32 encoded secret in the "Set secret (base32 encoded" field and clicking "OK"
If you choose to generate a new secret, SSO performs the generation and result is a secret with the key size specified for the method. The secret is returned as a downloadable text file.
If you choose set the secret yourself, the secret needs to be in Base32 encoded form and it's length in bytes must be at least 10 and at most 99.
Compatibility of TOTP secrets for SQL Directory users created in SSO before 8.8
The TOTP secrets that have been created for SQL Directory users in SSO older than 8.8 cannot be read in SSO 8.8 and newer, unless the compatibility flag LegacyUserCredentialsTable is set for the authentication method.
The compatibility flag LegacyUserCredentialsTable has only effect for SPI TOTP authentication method with SQL Directory Service. With any other Directory Service type the SPI TOTP authentication method doesn't require this compatibility flag, nor has it any effect.