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.

Setup Apache Guacamole OpenLDAP Authentication

Before you can proceed to setup Apache Guacamole OpenLDAP authentication, 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.

Therefore, download appropriate version of the LDAP extension.


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

  • guacamole-auth-ldap-1.3.0.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-1.3.0.jar file in Guacamole extensions directory, /etc/guacamole/extensions. If the directory do not already exist, create one.

tar xzf guacamole-auth-ldap-1.3.0.tar.gz
cp guacamole-auth-ldap-1.3.0/guacamole-auth-ldap-1.3.0.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">
            <param name="hostname"></param>
            <param name="port">22</param>

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-1.3.0/schema [email protected]:

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

scp -r guacamole-auth-ldap-1.3.0/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=
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=
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


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


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/ 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

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

ldap-encryption-method: starttls
ldap-search-bind-dn: cn=readonly,ou=system,dc=ldapmaster,dc=kifarunix-demo,dc=com
ldap-search-bind-password: [email protected]
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 -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;


Add the certificate to the Java’s trust store;

keytool -importcert -alias -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
  • janedoe is allowed to RDP to

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

Setup Apache Guacamole OpenLDAP Authentication

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

Setup Apache Guacamole OpenLDAP Authentication

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

Setup Apache Guacamole OpenLDAP Authentication
Setup Apache Guacamole OpenLDAP Authentication

And that concludes our guide on how to setup Apache Guacamole 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


Please enter your comment!
Please enter your name here