TOTP - Time base One Time Password¶

TOTP is a time based One Time Password standard. The TOTP authenticator works with TOTP based keyfob devices. Both hardware based and software based.

The TOTP is suitable as a second factor during authentication, and usually less suitable as a standalone single factor, as it relies on the device only, which may not be protected by any passwords or pin codes.

Configuring an Authenticator¶

To configure the TOTP authenticator it needs the following:

A data store for the pre-shared keys or a data-source supporting buckets, for generated keys
An account manager to find the users and devices
The TOTP specific settings such as window size, clock skew, interval and algorithm

Configuration Settings¶

Account manager: Used to search for the devices associated with the account of the authenticated (with the first factor) user.
Bucket data-source: Used to save the used OTPs in order to disallow a code from being used more times successively.
Algorithm: The algorithm that is used to generate the OTP. It is used on authentication and registration. Algorithms supported are SHA1, SHA256, SHA512.
Allow registration during login: Boolean flag that shows or hides the Register button from the templates
Clock Skew: Time in seconds the totp device time is allowed to drift in respect to the server time.
Delay window: A number that indicates how many intervals a OTP can be used after expired.
Digits: The number of digits the OTP consist of.
Interval: The time in seconds the OTP is valid for (affected by delay window).
Device Expiration: If set, indicates when the device expires. This is saved on the device store during registration.
Key Distribution Settings:
- Pre-shared key config:
  Attribute data-source: The repository where the id of the device can be used to find the key to validate the OTP.
- Generated key config:
  Bucket data-source: The data source id where the generated key will be stored.
  
  Issuer: Used by some OTP authenticator apps to help the user identify which OTP to use.
  
  Allow use to set device alias: Boolean Indicates if the set-alias screen will be shown during registration

Note

It is not reccomended to use this authenticator for single-factor authentication. Even though, when used as a single factor it will show a page asking the user for its username, in order to allow registration, a required-authenticator for registration is required. In case one is not configured, the server will respond with HTTP code 500 Internal Error when a user is trying to access the registration endpoint.

Configuring for pre-shared keys¶

The pre-shared keys is a mapping of device id (typically serial number) to the symmetric key. The key should be encoded using base32.

When a request is received for an OTP, the user is looked up using the account manager. Thereafter the device id or serial number is found on the user and used to lookup the actual key using the data source configured for id -> key mappings.

The authenticator also uses the Bucket data sources (since 2.4.0). This is used to store used OTPs so that they can only be used once to authenticate a user.

Important

Make sure the Bucket tables are defined in the data source.

An example configuration for pre-shared keys configuration:

Listing 109 Example configuration for TOTP authenticator¶

<authenticator>
    <id>totp1</id>
    <totp xmlns="https://curity.se/ns/ext-conf/totp">
        <account-manager>
            <id>DefaultAccountManager</id>
        </account-manager>
        <bucket>
            <data-source>DefaultHSQLDB</data-source>
        </bucket>
        <device-type>idsvr-totp</device-type>
        <clock-skew>0</clock-skew>
        <interval>30</interval>
        <digits>6</digits>
        <algorithm>sha1</algorithm>
        <pre-shared-key-config>
            <key-repository>
                <data-source>KeyRepo</data-source>
            </key-repository>
        </pre-shared-key-config>
    </totp>
</authenticator>

The key-repository must be a data-source that allows for attribute lookup. Below, you can find an example of what a JSON data-source should return:

Listing 110 Example response of key repository JSON data-source¶

{
    "clock_skew": 0,
    "interval": 60,
    "delay_window": 1,
    "algorithm": "SHA1",
    "digits": 6,
    "key": "KNCUGUSFKRFUKWJR"
}

Note

Only the key is mandatory to be in the response of the key repository. Any other parameter returned, will override the configuration of the authenticator (for that specific device). For example, if the authenticator has configured a clock_skew of 60 seconds and the response from the lookup in the key repository contains "clock_skew" : 0, the latter will be used when verifying the OTP.

Configuring for generated keys¶

When configured to use generated keys, the authenticator also uses the Bucket data source to save the key for the device. Also, when registering a new device, a QR code is shown to the user (and optionally a page where he/she can enter an alias for the device). The QR code can be scanned with TOTP mobile apps, like Google authenticator, FreeOTP and Yubico Authenticator.

Listing 111 Example configuration for TOTP authenticator with generated keys¶

<authenticator>
    <id>totp1</id>
    <totp xmlns="https://curity.se/ns/ext-conf/totp">
        <account-manager>
            <id>DefaultAccountManager</id>
        </account-manager>
        <bucket>
            <data-source>DefaultHSQLDB</data-source>
        </bucket>
        <device-type>idsvr-totp</device-type>
        <clock-skew>0</clock-skew>
        <interval>30</interval>
        <digits>6</digits>
        <algorithm>sha256</algorithm>
        <generated-shared-key-config>
            <bucket>
                <data-source>KeyRepo</data-source>
            </bucket>
            <issuer>Example.com</issuer>
            <allow-user-to-set-device-alias>true</allow-user-to-set-device-alias>
        </generated-shared-key-config>
    </totp>
</authenticator>

Google Authenticator¶

Google Authenticator mobile app is more restrictive than some implementations. It requires the authenticator to be configured with a 30 seconds interval, SHA1 as algorithm and no clock_skew. The authenticator’s default settings are compliant with Google Authenticator mobile app, just configure the mandatory fields to get started. Keep in mind that a generated-key-config should be configured in this case.

Listing 112 Example configuration for TOTP authenticator to be used with Google Authenticator mobile app¶

<authenticator>
    <id>totp1</id>
    <totp xmlns="https://curity.se/ns/ext-conf/totp">
        <account-manager>
            <id>DefaultAccountManager</id>
        </account-manager>
        <bucket>
            <data-source>DefaultHSQLDB</data-source>
        </bucket>
        <device-type>idsvr-totp</device-type>
        <generated-shared-key-config>
            <bucket>
                <data-source>KeyRepo</data-source>
            </bucket>
            <issuer>Example.com</issuer>
            <allow-user-to-set-device-alias>true</allow-user-to-set-device-alias>
        </generated-shared-key-config>
    </totp>
</authenticator>

Yubico Authenticator¶

Yubico Authenticator mobile app can work with any of the supported algorithms (SHA1, SHA256 or SHA512). The interval is also configurable, and likewise the number of digits. Digits can be 6, 7 or 8.

Listing 113 Example configuration for TOTP authenticator to be used with Yubico Authenticator mobile app¶

<algorithm>SHA256</algorithm>
<digits>7</digits>
<interval>20</interval>

FreeOTP¶

FreeOTP is similar to Yubico open to configuration, but more restrictive on the number of digits (it only accepts 6 or 8). All supported algorithms by this authenticator are also supported by FreeOTP and the interval is also possible to configure.

Listing 114 Example configuration for TOTP authenticator to be used with Yubico Authenticator mobile app¶

<authenticator>
    <id>totp1</id>
    <totp xmlns="https://curity.se/ns/ext-conf/totp">
        <account-manager>
            <id>DefaultAccountManager</id>
        </account-manager>
        <bucket>
            <data-source>DefaultHSQLDB</data-source>
        </bucket>
        <device-type>idsvr-totp</device-type>
        <algorithm>SHA512</algorithm>
        <digits>8</digits>
        <interval>40</interval>
        <generated-shared-key-config>
            <bucket>
                <data-source>KeyRepo</data-source>
            </bucket>
            <issuer>Example.com/issuer>
            <allow-user-to-set-device-alias>true</allow-user-to-set-device-alias>
        </generated-shared-key-config>
    </totp>
</authenticator>