Configure TOTP Two-Factor Authentication on Apache Guacamole

1
468

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.

Create RDP and SSH Connections to W...
Create RDP and SSH Connections to Windows and Linux Machines Using Guacamole

Configure TOTP Two-Factor Authentication on Apache Guacamole

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).

Configure Guacamole MySQL Database Authentication

  • Grant all the Users that Requires the use of TOTP Authentication ability to change their own passwords

From the User management interface;

Configure TOTP Two-Factor Authentication on Apache Guacamole

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

Configure TOTP Two-Factor Authentication on Apache Guacamole

Install Guacamole TOTP authentication extension

Guacamole doesn’t install with TOTP authentication extension by default. Thus, in order to configure TOTP Two-Factor Authentication on Apache Guacamole, 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 TOTP Two-Factor Authentication on Apache Guacamole

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

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;

Configure TOTP Two-Factor Authentication on Apache Guacamole

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

configure guacamole user totp

And there you go. You have learnt how to configure TOTP two-factor authentication on Apache Guacamole.

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

1 COMMENT

  1. Hi,
    After I configure the TOTP as the step above, I can’t see the CONFIGURE TOTP column on my guacamole website.

    How do I debug it?

    Thank you

LEAVE A REPLY

Please enter your comment!
Please enter your name here