Setup Apache Guacamole OpenLDAP Authentication

In this tutorial, you will learn how to setup Apache Guacamole OpenLDAP authentication. Apache Guacamole is a clientless HTML5 web based remote desktop gateway which provides remote access to servers and desktops through a web browser. By default, Guacamole uses a basic authentication module which basically involves reading usernames and passwords from an XML file.

Apart from using simple XML file for authentication, Apache Guacamole also supports other authentication modules. It provides database-backed authentication modules with the ability to manage connections and users from the web interface, and other authentication modules can be created using the extension API provided along with the Guacamole web application, guacamole-ext.

Configuring Apache Guacamole for OpenLDAP Authentication

Before you can proceed, ensure you have an Apache Guacamole as well as an LDAP servers up and running.

Install and Setup Guacamole Server

Follow the links below to install and setup Guacamole;

Install Apache Guacamole on Debian 10

Install Apache Guacamole on Ubuntu 20.04

Install and Setup OpenLDAP Server

Use these simple guides to install and setup OpenLDAP server

Install and Setup OpenLDAP Server on Ubuntu 20.04

Install and Setup OpenLDAP on CentOS 8

Install Guacamole LDAP extension

Navigate to the Guacamole releases page and the LDAP extension for the version of the Guacamole you are running. For example, if you are running Guacamole 1.3.0, then you can get the LDAP extension on the Guacamole 1.30 page.

Replace the value of the VER variable below with the version of the extension that matches your version of Guacamole.

VER=1.3.0

Therefore, download appropriate version of the LDAP extension.

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

The LDAP authentication extension is packaged as a .tar.gz file containing:

• guacamole-auth-ldap-${VER}.jar: The Guacamole LDAP support extension itself, which must be placed in GUACAMOLE_HOME/extensions.schema/
• LDAP schema files. An .ldif file compatible with OpenLDAP is provided, as well as a .schema file compliant with RFC-2252. The .schema file can be transformed into the .ldif file automatically.

Extract the archive and and copy the guacamole-auth-ldap-${VER}.jar file in Guacamole extensions directory, /etc/guacamole/extensions. If the directory do not already exist, create one.

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

cp guacamole-auth-ldap-${VER}/guacamole-auth-ldap-${VER}.jar /etc/guacamole/extensions/guacamole-auth-ldap.jar

Configure OpenLDAP Server to Provide Guacamole Authentication

Create Guacamole OpenLDAP Schema

Next, in order to allow only specific users that have a specific attribute or that belongs to a specific, say Guacamole group to be able to authenticate with OpenLDAP, you need to update the OpenLDAP database.

The Guacamole LDAP archive provides some schema files which “define an additional object class, guacConfigGroup, which contains all configuration information for a particular connection, and can be associated with arbitrarily-many users and groups. Each connection defined by a guacConfigGroup will be accessible only by users who are members of that group (specified with the member attribute), or who are members of associated groups“.

The Guacamole LDAP schema provides an object class type called guacConfigGroup, described above.

This object class type will then provides attributes such as;

• guacConfigProtocol: defines the connection protocol, for example, RDP, SSH, VNC
• guacConfigGroup: Which defines the connection parameters associated with the specified protocol such as remote hostname, the connection port.

See example below connections details below which illustrates the above further.

        <connection name="CentOS-Server">
            <protocol>ssh</protocol>
            <param name="hostname">192.168.56.156</param>
            <param name="port">22</param>
        </connection>

Therefore, copy the Guacamole LDAP extension schema files to your OpenLDAP server. Replace the username and ldap-server with the username and address of your OpenLDAP server in the command below.

scp -r guacamole-auth-ldap-${VER}/schema username@ldap-server:

For example, to copy these files to the root user account on my LDAP server;

scp -r guacamole-auth-ldap-${VER}/schema [email protected]:

Load the Guacamole LDAP schema details into the OpenLDAP database by running the command below;

ldapadd -Q -Y EXTERNAL -H ldapi:/// -f schema/guacConfigGroup.ldif

If the command runs successfully, you should see such an output;

adding new entry "cn=guacConfigGroup,cn=schema,cn=config"

Create OpenLDAP Groups for Guacamole Authentication

As much as it is possible to now add the attributes to individual OpenLDAP user profile to define how they are allowed to authenticate to Guacamole, it is easier to manage this a group such that, indidual members are added to specific Guacamole groups.

To begin with, these are the users that I currently have in my OpenLDAP database;

ldapsearch -Y EXTERNAL -H ldapi:/// -s one \
-b "ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com" -LLL -Q uid

dn: uid=janedoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com
uid: janedoe

dn: uid=johndoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com
uid: johndoe

dn: uid=koromicha,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com
uid: koromicha

ldapsearch -Y EXTERNAL -H ldapi:/// -s one \
-b "ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com" -LLL -Q dn

dn: cn=janedoe,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com

dn: cn=johndoe,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com

dn: cn=koromicha,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com

So I am gonna create two groups, for SSH and RDP connections.

SSH group configuration;

vim guacamole-ssh-connection.ldif

dn: cn=guacSSH,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com
objectClass: guacConfigGroup
objectClass: groupOfNames
cn: guacSSH
guacConfigProtocol: ssh
guacConfigParameter: hostname=192.168.56.180
guacConfigParameter: port=22
member: uid=koromicha,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com
member: uid=johndoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com

RDP group configuration;

vim guacamole-rdp-connection.ldif

dn: cn=guacRDP,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com
objectClass: guacConfigGroup
objectClass: groupOfNames
cn: guacRDP
guacConfigProtocol: rdp
guacConfigParameter: hostname=192.168.56.122
guacConfigParameter: port=3389
guacConfigParameter: ignore-cert=true
member: uid=janedoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com

Before you can update the database with the above details, ensure that the membeof module is loaded. For more details, you can check our guide on how to create groups in OpenLDAP.

Update the database with Guacamole group configurations above;

ldapadd -Y EXTERNAL -H ldapi:/// -f guacamole-ssh-connection.ldif -Q

Output;

adding new entry "cn=guacSSH,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com"

ldapadd -Y EXTERNAL -H ldapi:/// -f guacamole-rdp-connection.ldif -Q

Output;

adding new entry "cn=guacRDP,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com"

Checking the membership of the groups;

ldapsearch -H ldapi:/// -Y EXTERNAL -LLL -b "dc=ldapmaster,dc=kifarunix-demo,dc=com" uid=* memberOf -Q

dn: uid=johndoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com
memberOf: cn=guacSSH,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com

dn: uid=janedoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com
memberOf: cn=guacRDP,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com

dn: uid=koromicha,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com
memberOf: cn=guacSSH,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com

Configure Guacamole for OpenLDAP Authentication

Next, proceed to configure Guacamole for LDAP authentication.

Edit the /etc/guacamole/guacamole.properties and add the following configuration options to define how to connect to LDAP server for Authentication.

If you check our previous guides on setting up Guacamole, below is the options we had set in this file;

guacd-hostname: localhost
guacd-port:     4822
user-mapping:   /etc/guacamole/user-mapping.xml
auth-provider:  net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider

So for us to enable LDAP authentication, we will add the lines below;

ldap-hostname: ldapmaster.kifarunix-demo.com
ldap-encryption-method: starttls
ldap-search-bind-dn: cn=readonly,ou=system,dc=ldapmaster,dc=kifarunix-demo,dc=com
ldap-search-bind-password: P@ssW0rd
ldap-user-base-dn: dc=ldapmaster,dc=kifarunix-demo,dc=com
ldap-username-attribute: uid
ldap-member-attribute: member
ldap-member-attribute-type: dn
ldap-config-base-dn: ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com
ldap-user-search-filter: (|(memberOf=cn=guacSSH,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com)(memberOf=cn=guacRDP,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com))

Save and exit the file.

Ensure the LDAP server hostname is resolvable if you used a hostname instead of an IP address.

Also note that the ldap options are based on our LDAP server configurations.

Download the TLS certificate from your LDAP server;

openssl s_client -connect ldapmaster.kifarunix-demo.com:389 \
              -starttls ldap \
              -showcerts < /dev/null | \
              openssl x509 -text | \
              sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'

From the command output, copy the certificate from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- and place it in a file;

/etc/ssl/certs/ldapcert.pem

-----BEGIN CERTIFICATE-----
MIIDvzCCAqegAwIBAgIUc8imlOVhEej453dXtvacn7krg1MwDQYJKoZIhvcNAQEL
...
...
Igf9K1e9M0Q+j2XEsTeCYVU/v0Jt0kER0+V/NM0IrDOX+6kRz6DNsZrwcMEf5Yvp
ARWZ
-----END CERTIFICATE-----

Add the certificate to the Java’s trust store;

keytool -importcert -alias ldapmaster.kifarunix-demo.com \
	-file /etc/ssl/certs/ldapcert.pem \
	-keystore /usr/lib/jvm/java-11-openjdk-amd64/lib/security/cacerts \
	-storepass changeit \
	-noprompt

Restart Apache Tomcat;

systemctl restart tomcat9.service

Note, the use of default authentication method of reading users from an XML file is always last in priority relative to any other authentication extensions.

Verify Guacamole OpenLDAP Authentication

Now, we have three users;

• koromicha and johndoe are allowed to SSH to server 192.168.57.3
• janedoe is allowed to RDP to 192.168.56.122

Login as one of the users for SSH on http://server-IP:8080/guacamole.

Upon successful authentication, you should land on the SSH login prompt for remote system;

Similarly, login as an RDP user and you taken directly to remote desktop system login screen upon successful authentication to Guacamole.

And that concludes our guide on how to configure Apache Guacamole for OpenLDAP Authentication.

Reference and Further Reading

Guacamole LDAP Authentication

Other tutorials

Configure Squid Proxy OpenLDAP Authentication on pfSense

How to Configure DokuWiki OpenLDAP Authentication

Configure ownCloud OpenLDAP Authentication

Configure Offline Authentication via OpenLDAP on MacOS X