Configuration

The Authentication TOTP Module has a few configuration options that allow you to adjust its behaviour to fit your deployment. All these configuration options should be set inside the [authentication_totp] section of configuration file.

algorithm

The name of the hash algorithm to use. This, as defined in RFC 6238, can be one of sha1, sha256 or sha512.

Warning

Changing this value from the default may cause problems with some OTP client programs which may not support alternative values.

The default value is: sha1

application_secrets_dir

This is the directory that contains the application_secrets_file.

The default value is: [database] path

application_secrets_file

This is the name of the file that contains secrets used to encrypt and decrypt the TOTP keys when they are stored and retrieved from the database. The file should contain lines of the form tag: secret. It is recommended to either incremental counters (1, 2, …) or ISO dates (2020-05-04, 2020-07-21, …) as the tag. Take care to ensure the secrets have sufficient entropy.

Note

If this file does not exist it will be created automatically by trytond. Take care to ensure the contents of this file is kept secure.

See also

The Passlib AppWallet documentation contains further information.

The default value is: application.secrets

digits

The number of digits in the generated and/or accepted tokens. Must be between 6 and 10 inclusive.

Warning

Changing this value from the default may cause problems with some OTP client programs which may not support alternative values.

Warning

Due to a limitation of the HOTP algorithm the 10th digit can only contain values 0 to 2, and so offers very little extra security.

The default value is: 6

issuer

The issuer is a name that is included in the QR codes used with authenticator apps. It helps the Users know which TOTP key is for which service. It is formatted before it is used, and can include the name of the user’s main Company.

Note

The Authentication TOTP Module can be activated without the Company Module module being activated. In this case the {company} part of the issuer is left blank.

The default value is: {company} Tryton

key_length

This configuration option allows you to change the length of the keys that are generated when a new TOTP secret is required.

Note

The RFC 4226 (which is what TOTP RFC 6238 is based on) suggests that keys should be at least 128 bits long, and recommends using 160 bit keys.

The default value is: 160

period

How often, in seconds, the generated token changes.

Warning

Changing this value from the default may cause problems with some OTP client programs which may not support alternative values.

The default value is: 30

skew

The number of seconds to adjust the time by before checking whether the TOTP code matches. Negative skew is used to account for the client clock running behind the server clock. Positive skew indicates the client clock is running ahead of the server clock.

Tip

For most use cases this setting should be left at 0. It is normally best to account for clock skew and transmission delays by using the window parameter.

The default value is: 0

window

The number of seconds forwards and backwards in time to search when checking whether the TOTP code matches. This can be used to account for transmission delays and small amounts of skew in the client’s clock.

Note

The default value is normally more than enough to account for transmission delays and user TOTP code entry times, if client and server clocks are both using a reliable time source such as NTP.

The default value is: The period value