Configure TOTP Two-Factor Authentication on Apache Guacamole

In this tutorial, you will learn how to configure TOTP two-factor authentication on Apache Guacamole. Time-based One-time Password, TOTP, is a kind of multi-factor authentication which adds an extra layer of authentication on top of the usual username/password based authentications. This improves the security of your accounts.

Configure Apache Guacamole TOTP Two-Factor Authentication

Apache Guacamole supports the use of TOTP as a second authentication factor.

You can check out various installation guides on our page.

In order to be able to use Guacamole TOTP authentication;

• Enable Database Based Authentication on Guacamole (We used MySQL/MariaDB in our setup).
• Grant all the Users that Requires the use of TOTP Authentication ability to change their own passwords

You can check our previous guide on how to configure Guacamole MySQL Database Authentication

From the User management interface;

Click the user and update the permissions, to at least be able to change their own password.

Install Guacamole TOTP authentication extension

Guacamole doesn’t install with TOTP authentication extension by default. Therefore, you need to download and install the extension.

From the releases page, download TOTP authentication that matches the version of your installed Guacamole server.

wget https://dlcdn.apache.org/guacamole/1.4.0/binary/guacamole-auth-totp-1.4.0.tar.gz

Extract the extension and move it to GUACAMOLE_HOME/extensions, which in our setup is /etc/guacamole/extensions/.

tar -zxf guacamole-auth-totp-1.4.0.tar.gz guacamole-auth-totp-1.4.0/guacamole-auth-totp-1.4.0.jar

mv guacamole-auth-totp-1.4.0/guacamole-auth-totp-1.4.0.jar /etc/guacamole/extensions/

Configure Apache Guacamole TOTP Two-Factor Authentication

TOTP works out-of-the-box by default. Some of the configs used with TOTP include;

• totp-issuer: defines the human-readable name of the entity issuing user accounts. If not specified, “Apache Guacamole” will be used by default.
• totp-digits: 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.
• totp-period: The duration that each generated code should remain valid, in seconds. By default, each code remains valid for 30 seconds.
• 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.

If you want, you can update the values in the guacamole.properties configuration file. We go with the defaults in this setup.

Before you update the settings, ensure that the MFA app you are using supports the options for the above configs;

If you happen to change any setting and you get the verification failed upon entering the code, review the setting and ensure that the authentication app supports the setting.

Verifying TOTP Two-Factor Authentication on Apache Guacamole

Restart your Serverlet;

systemctl restart tomcat9

Login to Guacamole web interface as any user;

Upon successful login, you will be welcomed by such an interface.

Guacamole TOTP Authentication Enrollment

To complete the enrollment process, scan the barcode with the two-factor authentication app on your phone or device.

I am using Duo Mobile, for example;

Once you have scanned the barcode, enter the 6 digit authentication code click Continue to login to Guacamole dashboard.

On re-login, you are always prompted to enter the code;

As Admin, you can reset the user’s TOTP secret as well as confirm or disable TOTP login. Such user settings;

And there you go. You have learnt how to configure Apache Guacamole TOTP 2FA authentication.

Read more on the documentation page.

Other Tutorials

Guacamole: How to fix RDP server closed/refused connection: Security negotiation failed (wrong security type?)

Setup Apache Guacamole OpenLDAP Authentication