TOTP 2FA

TOTP is an optional 2FA method to help further secure logins to the Guacamole server. Enabling TOTP will require using a tool (usually an app) to generate a one time use numeric code that is required in addition to the username and password to successfully login.

For further details on TOTP specific to Apache Guacamole see TOTP two-factor authentication For further details on what TOTP is in general see the Time-based One-time Password algorithm Wikipedia page.

Requirements

For TOTP to work within Apache Guacamole, installed via this script, there are a few requirements to meet:

1. The TOTP option must be selected via the script.
2. The TOTP parameters must be correctly set.
3. A compatible TOTP app, program, physical device is needed outside of Guacamole.
4. A user must have, in Guacamole, permissions to change their own password. (more on this below)

With TOTP installed and configured on the server, it is currently enabled on a per user basis in Guacamole. Any user with the permission "change own password" will be presented with the TOTP enrollment screen on first login. Once enrolled they will be presented the TOTP code entry screen after logging in with their primary credentials. If a user does not have "change own password" permissions, they will simply not be shown the TOTP enrollment screen and will not be required to use TOTP 2FA.

This permission is not set by default for users in Guacmaole and needs to be set manually one-by-one (or via scripting which is beyond the scope of this document or my install script). There is currently an issue filed and a pull request to allow users to be automatically added to the JDBC module upon successful login from another module which could resolve the matter but is unlikely to be included in recent future releases of Guacamole (unlikely to be in 1.1.0, maybe 1.2.0 or later).

https://issues.apache.org/jira/browse/GUACAMOLE-708

https://github.com/apache/guacamole-client/pull/389

Configuration

The script will prompt for a few pieces of information to configure TOTP on the server side. In most cases the default values are what should be used.

The prompts are:

1. TOTP issuer | The human-readable name of the entity issuing user accounts. If not specified, "Apache Guacamole" will be used by default.
2. Number of digits to use | The number of digits which should be included in each generated TOTP code. Legal values are 6, 7, or 8. By default, 6-digit codes are generated.
3. Period in seconds a code is valid | The duration that each generated code should remain valid, in seconds. By default, each code remains valid for 30 seconds.
4. TOTP mode | The hash algorithm that should be used to generate TOTP codes. Legal values are "sha1", "sha256", and "sha512". By default, "sha1" is used.

Number 1 is not important and is really only for the user to help identify things.

Numbers 2-4 depend on what TOTP app is being used and what it supports. Most only support 6 digits, 30 seconds and SHA1. If you use an app that supports other configurations you can match the setting applied using this Guacamole install script to the settings supported by your TOTP app.

TOTP Apps

There are many different TOTP 2FA apps, programs and keys available. I do not endorse any and only provide this list for reference. I highly recommend researching the matter and picking the best option for your needs. Many password managers also support generating TOTP codes, but implementing this is beyond the scope of this page and I will not cover using a password manager for this purpose.

Popular TOTP 2FA options:

• Authy
• Google Authenticator
• Microsoft Authenticator
• FreeOTP
• Yubikey