Guacamole Integration with Active Directory, OTP, and Duo 2FA

Welcome to this tutorial on Guacamole integration with Active Directory, OTP, and Duo 2FA. Authentication plays a significant role in ensuring the security and integrity of digital systems, applications, and sensitive information is retained. It is therefore important to ensure that users’ authentication is configured correctly.

Guacamole can be integrated with LDAP/AD, OpenID connect, CAS, TOTP, Duo etc just to provide advanced user authentication and security.

Active Directory provides a central database from which users, groups, computers, and other network components can be accessed. This can be so vital for Guacamole since we do not need to create users and passwords for authentication.

OTP, One-Time Password, is a valid password for one transaction or login session. They are generated by algorithms based on time or events.

Duo 2FA Authentication is an authentication method where a user is required to provide two identification forms to be validated. It combines one thing the users know such as a PIN or password with an extra device such as a phone or hardware token. Duo is a popular 2FA solution that offers a wide range of authentication methods such as biometrics, OTPs, push notifications and phone calls

Join me in this guide as we learn how to use Active Directory, OTP, and Duo 2FA authentication on Guacamole.

Getting Started

For this guide, you need to have Guacamole installed. This can be achieved using the guides below:

• How to Install Guacamole Remote Desktop

Once installed and running, proceed and configure the desired authentication method below. But ensure the below directories exist:

sudo mkdir -p /etc/guacamole/{extensions,lib}

1. Configure Active Directory/LDAP authentication on Guacamole

Guacamole supports Active Directory/LDAP authentication using a plugin available on the main project site. This makes it possible to authenticate using users stored in AD/LDAP. This makes it easier for existing users to log in to Guacamole.

Before you proceed, you need to have AD/LDAP installed and configured. This can be achieved using any of the below guides:

• Active Directory
  • Setup Active Directory Domain Services on Windows Server
• LDAP
  • Install and Configure OpenLDAP Server

Once set up, proceed and download the AD/LDAP extension from the Official page. You can also pull the extension using the commands:

Export the version:

export VER=1.5.3

Download the archive:

wget https://dlcdn.apache.org/guacamole/$VER/binary/guacamole-auth-ldap-$VER.tar.gz

Extract the archive:

tar -xzf guacamole-auth-ldap-$VER.tar.gz

Create the extensions directory for Guacamole if it doesn’t exist and copy the .jar file into it:

sudo cp ~/guacamole-auth-ldap-$VER/guacamole-auth-ldap-$VER.jar /etc/guacamole/extensions

Now modify the Guacamole properties

sudo vim /etc/guacamole/guacamole.properties

Here, provide your AD/LDAP properties as shown:

##LDAP SETTINGS
ldap-hostname:          WIN-PLMH2KF0VT2.computingforgeeks.com
ldap-port:              389
ldap-encryption-method: none

ldap-user-base-dn:       DC=computingforgeeks,DC=com
ldap-username-attribute: sAMAccountName

#DN (Distinguished Name) of the user to bind as when authenticating users that are attempting to log in
ldap-search-bind-dn:       CN=Administrator,CN=Users,DC=computingforgeeks,DC=com
#The password to provide to the LDAP server when binding as ldap-search-bind-dn to authenticate other users
ldap-search-bind-password: Passw0rd!

#ldap-user-search-filter: (&(objectClass=user)(memberOf:1.2.840.113556.1.4.1941:GuacamoleUsers,CN=Users,DC=computingforgeeks,DC=com))

In the above command, I have used a user Administrator with their password for my bind user to the AD. You can use any other user in your system for authentication.

Save the changes and restart Tomcat:

sudo systemctl restart tomcat*

Now you can access the Guacamole site using any user on your AD/LDAP. For example on my AD, I have the following user:

On the Guacamole site, let’s test authentication using the user:

If all goes well, you should access Guacamole as shown:

2. Configure OTP Authentication on Guacamole

Guacamole supports OTP, a One-Time Password as a second authentication method on top of any existing method. Before we use OTP, we need to enable the database authentication extension.

a. Enable Database authentication for Guacamole

For that reason, install MariaDB/MySQL using any of the below guides:

• How to Install MariaDB
• How to Install MySQL

Once installed, access the shell:

mysql -u root -p

Create a database and user:

create database guacd;
create user guacd_admin@localhost identified by 'Passw0rd!';

Next, grant the required permissions to the user:

grant SELECT,UPDATE,INSERT,DELETE on guacd.* to guacd_admin@localhost;

Save the changes and exit:

flush privileges;
quit

Next, you need to install the JDBC auth database extension for Guacamole:

export VER=1.5.3
wget https://downloads.apache.org/guacamole/$VER/binary/guacamole-auth-jdbc-$VER.tar.gz

Extract the archive and copy it to the extensions directory:

tar -xf guacamole-auth-jdbc-$VER.tar.gz
sudo mv guacamole-auth-jdbc-$VER/mysql/guacamole-auth-jdbc-mysql-$VER.jar /etc/guacamole/extensions/

We now need to import the database schemas:

cd guacamole-auth-jdbc-*/mysql/schema
cat *.sql | sudo mysql -u root -p guacd

Provide your MySQL root password to import the schemas. We also need to install the MySQL Connector/J

VER=8.1.0
wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j-$VER.tar.gz

Extract the file and copy it to the /etc/guacamole/lib/ directory:

tar -xf mysql-connector-j-*.tar.gz
sudo cp mysql-connector-j-$VER/mysql-connector-j-$VER.jar /etc/guacamole/lib/

Next, enable authentication by making the below definitions in the guacamole.properties file:

sudo vim /etc/guacamole/guacamole.properties

Add and modify the below lines. Ensure the correct database credentials are provided.

###MySQL properties
mysql-hostname: localhost
mysql-database: guacd
mysql-username: guacd_admin
mysql-password: Passw0rd!

Save the file and restart Tomcat:

sudo systemctl restart tomcat* guacd

Access Guacamole using the default creds:

Username: guacadmin
Password: guacadmin

Sample:

Once authenticated, create a new user and make them the admin user.

The user will be available as shown:

b. Configure TOTP for Guacamole

Now we can proceed and configure OTP for Guacamole. Begin by downloading the extension.

Export the version:

export VER=1.5.3

Now download the TOTP extension:

wget https://downloads.apache.org/guacamole/$VER/binary/guacamole-auth-totp-$VER.tar.gz

Extract the extension and copy it to the /etc/guacamole/extensions/ directory

tar -zxf guacamole-auth-totp-$VER.tar.gz
sudo cp guacamole-auth-totp-$VER/guacamole-auth-totp-$VER.jar /etc/guacamole/extensions/

Now you need to configure TOTP for Guacamole

sudo vim /etc/guacamole/guacamole.properties

In the file, add the below lines:

##OTP SETTINGS
##entity issuing user accounts, default "Apache Guacamole"
#totp-issuer:  Apache Guacamole

#The number of digits which should be included in each generated TOTP code.
totp-digits: 8

#The duration that each generated code should remain valid, in seconds
totp-period: 30

#The hash algorithm that should be used to generate TOTP codes. Legal values are “sha1”, “sha256”, and “sha512”. By default, “sha1” is used.
#totp-mode: sha1

Once the settings have been made, save the file and restart Tomcat and GUACD.

sudo systemctl restart tomcat* guacd

Now validate if OTP is working, by login in using the user created.

Once authenticated, you will land on this page, use a mobile phone to scan this and obtain the code.

If all is okay and the code has been provided, you should be authenticated as shown:

3. Configure Duo 2FA Authentication on Guacamole

You can also use Duo as a second-layer authentication for Guacamole. This extension allows users to verify themselves using the DUO service before being allowed.

To use it, you need to download the extension. First, export the version:

export VER=1.5.3

Download the extension with the command:

wget https://downloads.apache.org/guacamole/$VER/binary/guacamole-auth-duo-$VER.tar.gz 

Extract the archive and copy it to the extensions directory:

tar -zxf guacamole-auth-duo-$VER.tar.gz
sudo cp guacamole-auth-duo-$VER/guacamole-auth-duo-$VER.jar /etc/guacamole/extensions/

The next thing we need to do is log in to your Duo account and add a new Web SDK application in the Applications tab.

The app will be added as shown:

Scroll down and rename the application with a friendly name:

Save the changes then proceed and update Guacamole to use the DUO 2FA.

sudo vim /etc/guacamole/guacamole.properties

In the file, you need to add several variables obtained from the Web SDK app created:

##DUO 2FA
#The hostname of the Duo API endpoint to be used to verify user identities
duo-api-hostname: api-XXXXXXXX.duosecurity.com

#The integration key/client ID provided for Guacamole by Duo.
duo-integration-key: must-be-EXACTLY-20-characters

#The secret key provided for Guacamole by Duo
duo-secret-key: must-be-EXACTLY-20-characters

#An arbitrary, random key which you manually generated for Guacamole
duo-application-key: a-random-key-here

Make sure the details are provided correctly, to obtain the random key, you can use:

$ pwgen 40 1
ienohdiePhuj1veiqueiVie3aila4pahpiesegho

Once the changes have been saved, restart Tomcat and GUACD:

sudo systemctl restart tomcat* guacd

Now access Guacamole and see if Duo 2FA is working as desired:

Begin by setting up DUO for the first time:

For my case, I will add a Tablet or phone with the DUO app installed.

You will be required to scan and add the device, once added, you can proceed to log in.

Now you can send a push to your added device:

If all is okay, you should be authenticated.

Verdict

Today, we have learned the Guacamole integration with Active Directory, OTP, and Duo 2FA. This can be vital if you are running Guacamole in a production environment with many users and security required. I hope this was significant to you.

See more:

• Configure SSH Two factor (2FA) Authentication on CentOS 8 / RHEL 8
• How To Setup SSH and MySQL Bastion Server using Warpgate
• Run Teleport in Docker Container using Docker Compose