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 className=ubilogin.method.provider.spi.DirectoryTOTPMethod title=Acme Authenticator configuration=totpAlgorithm HmacSHA1 configuration=totpKeySize 20 configuration=totpT0 0 configuration=totpTimeStep 30000 configuration=totpDigits 6 configuration=totpWindowBefore 1 configuration=totpWindowAfter 0

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
className=ubilogin.method.provider.spi.DirectoryTOTPMethod
title=Acme Authenticator
configuration=totpAlgorithm HmacSHA1
configuration=totpKeySize 20
configuration=totpT0 0
configuration=totpTimeStep 30000
configuration=totpDigits 6
configuration=totpWindowBefore 1
configuration=totpWindowAfter 0

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

For other directories like SQL directory or external LDAP directory you need to use the TOTP API for managing the secrets.

When using Active Directory, you must ensure that the directory.schema=Active Directory. Setting directory.schema=Generic will not work.

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.

Browser not supported