Apache Guacamole supports the use of TOTP as a second authentication factor.
Enable Database-Based Authentication
Guacamole must be configured to use database-based authentication (e.g., MySQL/MariaDB).
Refer to our guide on configuring Guacamole MySQL Database Authentication.
Grant Users Permission to Change Passwords
Ensure that users who require TOTP authentication have permission to change their own passwords.
From the user management interface:
Guacamole does not include the TOTP authentication extension by default. Follow these steps to install it:
Download the TOTP Authentication Extension
Visit the releases page and download the TOTP authentication extension matching your Guacamole version. For example:
VER=1.5.5
wget https://dlcdn.apache.org/guacamole/${VER}/binary/guacamole-auth-totp-${VER}.tar.gz
Extract and Move the Extension
Extract the .jar file and move it to the GUACAMOLE_HOME/extensions directory (e.g., /etc/guacamole/extensions/):
tar -zxf guacamole-auth-totp-${VER}.tar.gz guacamole-auth-totp-${VER}/guacamole-auth-totp-${VER}.jar
mv guacamole-auth-totp-${VER}/guacamole-auth-totp-${VER}.jar /etc/guacamole/extensions/
TOTP works out-of-the-box with default settings. You can customize these configurations in the guacamole.properties file:
totp-issuer: The name of the entity issuing user accounts (default: Apache Guacamole).totp-digits: The number of digits in each TOTP code (default: 6; valid values: 6, 7, 8).totp-period: Code validity duration in seconds (default: 30).totp-mode: Hash algorithm used to generate codes (default: sha1; valid values: sha1, sha256, sha512).I would highly reccomend using SHA512, because it is the most secure.
Note: Ensure that your MFA app supports any custom configurations you apply. If you encounter "verification failed" errors, double-check your settings and app compatibility.
Restart the Tomcat Service
Restart the server to apply the changes:
systemctl restart tomcat9
Login and Enroll
Subsequent Logins
As an admin, you can manage TOTP settings for users:
Congratulations! You have successfully configured Apache Guacamole TOTP Two-Factor Authentication.