LDAP or LDAPS Authentication

LDAP or LDAPS is an optional primary authentication method available to install and configure with this Apache Guacamole instillation script. This will allow, when correctly configured, signing into Guacamole using AD/LDAP credentials.

The LDAP menu of the script will prompt for all the information required for LDAP to work properly in most cases. Primarily, this is done by using LDAP in conjunction with the MariaDB based authentication detailed in the official documentation here under the heading "Associating LDAP with a database".

Essentially, this leads to a configuration in which LDAP is used to store/verify the credentials but user meta data is stored within the MariaDB database, not on the AD/LDAP server. In other words things like the permissions a user has within Guacamole, what connections they are assigned, etc. are stored in the database not AD/LDAP. This means that AD/LDAP on the server side does not need to be altered for Guacamole to be able to use it for authentication.

It is assumed that the AD/LDAP server is already properly setup and that a user/service account has already been configured with permissions to view/read entities within AD/LDAP as this user will be used by Apache Guacamole to pull in all other users and allow them to sign-in to Guacamole.

LDAP Parameters (gif at the bottom of this page)

The script will prompt for a handful of parameters used to configure AD/LDAP authentication.

The very first prompt will ask "Use LDAPS instead of LDAP...". For now we are going to skip that option and presume the default answer of "no". Further information on using LDAPS can be found under the "Using LDAPS (LDAP over SSL)" heading lower on this page.

These are the prompts, further explained for a standard AD/LDAP configuration:

• "Enter the LDAP port". The default is 389. This is the port AD/LDAP uses to communicate with client machines. Unless you know this port was changed on the AD/LDAP server, leave it at 389.
• "Enter the LDAP server hostname". This is the FQDN of the AD/LDAP server. If, for ex, the server hostname was myserver and the AD/LDAP domain was mydomain.com then this entry should be myserver.mydomain.com
• "Enter the LDAP User-Base-DN". The base of the DN for all Guacamole users. Users need to be somewhere within the subtree of the specified user base DN. If unsure and with a relatively small AD/LDAP domain, you may simply use the domain itself, ex: dc=mydomain,dc=com. Alternatively, something like ex: ou=accounting,dc=mydomain,dc=com if all users needed for Guacamole authentication are within or under the OU of "accounting" for example.
• "Enter the LDAP Search-Bind-DN". This entry specifies the user (service account) created specifically for this purpose in LDAP query type syntax. Hypothetically, if the service account for Guacamole was named srv-guac and that user is in the Organizational Unit (OU) of serviceaccounts under the same domain, then this entry would be cn=srv-guac,ou=serviceaccounts,dc=mydomain,dc=com. Do not put any spaces in the entry.
• "Enter the LDAP Search-Bind-Password". This is the password for the above user. Be aware that this will be stored in plain text in the /etc/guacamole/guacamole.properties file. Anyone with sudo/root and/or permissions to view this file could read the password of the AD/LDAP user created to connect AD/LDAP and Guacamole.
• "Enter the LDAP Username-Attribute". The default is sAMAccountName. Unless you are sure what you are doing, leave this as the default and use it.
• "Enter a custom LDAP user search filter". This can be used to refine the list of users used by Apache Guacamole for authentication. This should be a LDAP query syntax string. I would highly recommend testing any query string prior to attempting to use it with this parameter. The default for this parameter (which is also the default used by Guacamole when the parameter is absent from the config) is (objectClass=*). This is essentially a catch all.

Important Manual Steps

After the script runs, and presuming everything was set properly, you will be able to login using the default Guacamole admin user (from the database) or any AD account (via LDAP) that is within the base OU provided during the prompts from the script.

However, you will need to use the local database account to initially grant at least one AD user admin permissions within Guacamole. After that it is possible (and advisable) to disable, change the password or delete the default admin account and use AD accounts for admin and standard usage going forward. AD accounts granted admin rights can grant other AD users admin rights as well, but no AD account will have admin rights by default, even if they are an admin within AD (remember, only the credentials/authentication are stored in LDAP, everything else is stored in the database).

To make an initial AD user an "admin", login using the default Guacamole user credentials (provided when the script completes) and do the following:

1. Go to "Settings". Click your user name at the top right of the screen, then "Settings" from the drop down.
2. Click the "Users" tab at the top of the screen.
3. Click the "New User" button towards the top left of the screen.
4. Fill in the username. This should be identical to the user name in AD.
5. Under the "Permissions" header, check off every box.
6. Click the "Save" button at the bottom of the page.

This AD account can now be used to administer Guacamole. If you login to Guacamole as this user now, the "Users" list from step 2 above will display the full list of AD users available based on the parameters entered during the script. You can grant other users admin abilities by simply selecting them from the user list (no need to create a new user, that's a 1 time process).

Using LDAPS (LDAP over SSL)

When using LDAP authentication as a primary authentication type its possible to also configure Apache Guacamole to use LDAPS (LDAP over SSL) for increased security. This requires that the AD/LDAP server is configured for this role and has a valid certificate for this purpose.

The article here describes configuring Windows Server 2012 R2 (as well as 2008, 2012, 2016 and 2019) to utilize LDAPS for clients. I am assuming in this documentation if you are going to use LDAPS that you know how to configure it server side and already have LDAPS functional in your domain. Alternate directions for setting up a Linux based AD DC can be found at Rico Sharp's blog post: Up and running with Apache Guacamole on CentOS 7. I was able to complete the steps on a Debian 10.1 machine and via brief testing establish it worked. The guide uses the Samba generated SSL cert for LDAPS, though I imagine its possible to use a self-signed/self-generated cert or a valid cert from other sources though that's beyond the scope of this documentation

The first step to preparing Apache Guacamole to work with LDAPS is to export the LDAPS certificate from the server and copy/download it to the Guacamole server prior to running the script.

I recommend the steps provided in the link above, which I will assume in my directions. The certificate should be exported as a .cer file using the "Base-64 encoded X.509 (.CER)" as the format to export (.pem may work under certain circumstances). Make note of the certificate file name and location on the Guacamole server to which the cert was downloaded/copied to.

After running the Apache Guacamole install script, the prompts to configure LDAPS are:

• "Use LDAPS instead of LDAP". Type "y" or "yes" to elect to use LDAPS.
• "Enter the LDAP port". The default LDAPS port is 636. Use this as the port unless you are certain the port was set on the AD/LDAP server to another port.
• "Enter a valid filename of the .cer certificate file". This is the file name only of the certificate generated from the AD/LDAP server and previously copied to the Guacamole server we have run the script on. It should be something like filename.cer with "filename" being replaced by the actual name of the certificate file but ending with the .cer extension.
• "Enter the full path of the dir containing the .cer certificate file". This should be the full path to the certificate file excluding the certificate filename. For example: /home/username/. This entry must end with a /.
• "Set the password for the CACert Java Keystore". This prompt changes the default password for the keystore that will contain our LDAPS cert. I highly recommend not using or leaving it as the default password.

The rest of the prompts are the same as using the standard LDAP option, detailed above under the heading "LDAP Parameters" on this page.

Note: If the filename and/or path given are not correct the script will prompt again for it. Be sure prior to running the script that you know the correct file name and full path.

LDAP Resources

Most issues with the LDAP authentication for Guacamole are configuration issues that come from typos or incorrect syntax/entries. Below are some tools I found helpful for working these out.

• ADExplorer. This tool connects to AD/LDAP from a Windows machine and provides the ability to view the AD/LDAP tree. It also has the ability to create and test LDAP queries providing the exact LDAP query string. It can be used to confirm paths to users, OU's, etc. It can help create and confirm query strings.
• ldp.exe which is part of RSAT from Microsoft. This is a windows tool to test connecting to AD/LDAP. More specifically, it has the option to specify the port and if SSL should be used (LDAPS). Good for verifying the server name, port and if LDAPS is working.