Guacamole provides support for TOTP as a second authentication factor, verifying the identities of enrolled users using authentication codes generated with the TOTP standard. To make use of TOTP support, a database authentication mechanism will need be configured, as well, such as MySQL or PostgreSQL. Only once authentication has succeeded through another installed method will TOTP be used to verify the identity of the user, and a database is specifically required for storage of the key that Guacamole and the user's authentication device will use to generate authentication codes.

Installing TOTP support for Guacamole

Glyptodon Enterprise packages Guacamole’s TOTP support within the glyptodon-guacamole-auth-totp package:

$ sudo yum install glyptodon-guacamole-auth-totp

The Guacamole-side installation of TOTP support within Glyptodon Enterprise consists solely of the glyptodon-guacamole-auth-totp package. Nothing else needs to be installed except for Guacamole itself and some other means of authentication. If Guacamole has not yet been installed and confirmed to work with a database authentication method, that should be done first before attempting to set up TOTP.

Unlike most other extensions, no additional configuration information is typically needed for the TOTP support to work. All configurable values have defaults which are accepted by widely used TOTP implementations like Google Authenticator. You will only need to specify additional configuration information if your authentication devices differ from these defaults:

Issuer name"Apache Guacamole"
Code length6 digits
Validity period30 seconds
Hash algorithmSHA-1

If the above are acceptable, then no configuration changes need to be made and you should proceed to the "Completing installation" section below. If any of the above need to be changed, you will need to edit /etc/guacamole/ to specify the appropriate values. These properties are documented separately in detail:

Completing installation

Guacamole will generally only load new extensions and reread during the startup process. To apply the configuration changes, Guacamole (and thus Tomcat) must be restarted:

$ sudo systemctl restart tomcat

After TOTP support has been installed and Tomcat has been restarted, users will automatically be enrolled in TOTP if each of the following is true:

  1. The user exists within the database, whichever database that may be (MySQL / MariaDBPostgreSQL, or SQL Server).
  2. The user has permission to edit their account (permission to change their own password).

Users that do not exist in the database or that lack permission to edit their account will still be able to log in, but will not be enrolled with TOTP.

If it is critical that absolutely all users use TOTP,  you should make sure to grant your users permission to change their database passwords. If you are using a database alongside LDAP or Active Directory, you should be sure to set the corresponding property within /etc/guacamole/ to enforce existence of database accounts for all logins. Each supported database has its own variant of this property:

DatabaseProperty name
MySQL / MariaDBmysql-user-required
SQL Serversqlserver-user-required

This is particularly important if the database's concept of identity may differ from your LDAP server's concept of identity. For example, usernames within PostgreSQL are case-sensitive, but usernames within Active Directory typically are not.