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/guacamole.properties to specify the appropriate values. These properties are documented separately in detail:

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

You will not have a standalone "guacamole" service if you have not deployed Guacamole automatically with the "glyptodon-guacamole-standalone" package. This will be the case if:

  • You have chosen to manually deploy Guacamole under your own install of Apache Tomcat or JBoss, rather than use the provided version of Tomcat.
  • You are maintaining a deployment of Glyptodon Enterprise that was originally installed before the 2.5 release (2021-09-16).

You will instead need to manually restart your install of Tomcat:

$ sudo systemctl restart tomcat

After TOTP support has been installed and Guacamole has been restarted, only users that exist within the database will automatically be enrolled in TOTP. Valid users that exist only outside the database will be able to log in, but will not be automatically enrolled with TOTP.

If you are using a database alongside LDAP or Active Directory and want to require all users to use TOTP, you should be sure to set the corresponding property within /etc/guacamole/guacamole.properties 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
PostgreSQLpostgresql-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.