Integrate Bitnami's Apache Guacamole Stack with an LDAP Directory for User Authentication
Apache Guacamole is a powerful and flexible solution for remote computing. It enables users to remotely access desktop environments over VNC or RDP using a standard Web browser. It is free and open source, and is available under the Apache License.
The easiest way to get started with Apache Guacamole is with Bitnami. Bitnami provides a one-click install solution for Apache Guacamole, allowing you to deploy it as a virtual machine or run your own Apache Guacamole server in the cloud.
For medium or large enterprises, though, deploying Apache Guacamole is only part of the puzzle; they also need to find a way for enterprise users to easily connect to, and start using, it. Apache Guacamole can easily be integrated with existing LDAP directories, making it quick and easy for IT teams to leverage existing Single Sign-On (SSO) infrastructure and quickly roll it out to enterprise users.
This guide explains the process of integrating the Bitnami Apache Guacamole stack with an existing LDAP directory and allow users to log in and begin using it with their LDAP user credentials.
Assumptions and prerequisites
This guide makes the following assumptions:
- You have deployed the Bitnami Apache Guacamole stack on a cloud server and have administrator credentials for it. Learn about deploying Bitnami applications and obtaining credentials.
- You have an LDAP directory service that is accessible by the Bitnami Apache Guacamole deployment.
If an LDAP directory service is not available, Step 1 of this guide walks you through the process of deploying an OpenLDAP service on Kubernetes with a few sample user accounts. However, in this case, the guide assumes that:
- You have a multi-node Kubernetes cluster running with the kubectl command line (kubectl CLI) installed.
Step 1: Deploy an OpenLDAP service
If you already have an LDAP directory service, you can skip to Step 2.
As a first step, you must have an LDAP directory server available to handle incoming authentication requests from Apache Guacamole. An easy way to do this is to deploy Bitnami's OpenLDAP container image on a Kubernetes cluster and make it available using a public IP address. Follow the steps below:
Make sure that you can connect to the Kubernetes cluster by executing the command below:
Create a file named deployment.yaml with the content below:
apiVersion: apps/v1 kind: Deployment metadata: name: openldap labels: app.kubernetes.io/name: openldap spec: selector: matchLabels: app.kubernetes.io/name: openldap replicas: 1 template: metadata: labels: app.kubernetes.io/name: openldap spec: containers: - name: openldap image: docker.io/bitnami/openldap:latest imagePullPolicy: "Always" env: - name: LDAP_ADMIN_USERNAME value: "admin" - name: LDAP_ADMIN_PASSWORD valueFrom: secretKeyRef: key: adminpassword name: openldap - name: LDAP_USERS valueFrom: secretKeyRef: key: users name: openldap - name: LDAP_PASSWORDS valueFrom: secretKeyRef: key: passwords name: openldap ports: - name: tcp-ldap containerPort: 1389
This Kubernetes manifest deploys OpenLDAP on the cluster and configures it with an administrator account named admin and corresponding password adminpassword. For added security, modify these easy-to-guess values in your own deployment. Notice also that the OpenLDAP directory is initialized with a list of users and passwords from the openldap secret; you will create this secret shortly.
Create a file named svc.yaml with the following parameters:
apiVersion: v1 kind: Service metadata: name: openldap labels: app.kubernetes.io/name: openldap spec: type: LoadBalancer ports: - name: tcp-ldap port: 1389 targetPort: tcp-ldap selector: app.kubernetes.io/name: openldapWarning
Using a LoadBalancer service type will assign a public static IP address for the OpenLDAP deployment. Depending on your cloud provider's policies, you may incur additional charges for this IP address.
Create the openldap secret. This secret contains some example OpenLDAP user accounts and credentials:
kubectl create secret generic openldap --from-literal=adminpassword=adminpassword --from-literal=users=user01,user02 --from-literal=passwords=password01,password02
Deploy the container and service on the Kubernetes cluster:
kubectl create -f deployment.yaml kubectl create -f svc.yaml
Wait for the deployment to complete. Obtain and note the public IP address for the OpenLDAP service:
kubectl get svc | grep openldap
The OpenLDAP service is now available on port 1389 and ready to be used as the authentication method for Apache Guacamole.
Step 2: Add the LDAP extension to Apache Guacamole
Adding LDAP support to Apache Guacamole is as simple as downloading and configuring an additional extension. Follow these steps:
Navigate to the Apache Guacamole releases page and select the version corresponding to your Bitnami Apache Guacamole stack. At the time of writing, this is v1.3.0.
On the version detail page, locate and copy the link to the LDAP authentication extension. Typically, this extension is named guacamole-auth-ldap-X.Y.Z.tar.gz, where X.Y.Z is a version number placeholder.
Log in to the Bitnami Apache Guacamole host over SSH.
At the server console, download the LDAP authentication extension using the example commands below. Remember to replace the example download link shown below with the correct link for your version.
cd /tmp wget "http://apache.org/dyn/closer.cgi?action=download&filename=guacamole/1.3.0/binary/guacamole-auth-ldap-1.3.0.tar.gz" -O ldap.tar.gz
Extract the contents of the downloaded archive and move the LDAP extension JAR file to the Apache Guacamole extensions directory. Remember to replace the path and filename with the correct one for your version.
tar -xzvf ldap.tar.gz sudo mv guacamole-auth-ldap-1.3.0/guacamole-auth-ldap-1.3.0.jar /opt/bitnami/guacamole/extensions/
Step 3: Configure Apache Guacamole for LDAP authentication
The next step is to update the Apache Guacamole configuration with the details for the LDAP authentication server. Follow these steps:
Log in to the Bitnami Apache Guacamole host over SSH (if you're not already logged in).
Edit the /opt/bitnami/guacamole/guacamole.properties file:
sudo vi /opt/bitnami/guacamole/guacamole.properties
Add the lines below to it:
ldap-hostname: LDAP-SERVER-IP-ADDRESS ldap-port: 1389 ldap-user-base-dn: ou=users,dc=example,dc=org ldap-username-attribute: cn ldap-search-bind-dn: cn=admin,dc=example,dc=org ldap-search-bind-password: adminpassword ldap-encryption-method: none
Replace the LDAP-SERVER-IP-ADDRESS placeholder with the IP address of your LDAP server. If required, update the LDAP server port number and administrator password. The values shown are those configured for the Bitnami OpenLDAP container image in Step 1.
Restart Apache Tomcat and Apache Guacamole:
sudo /opt/bitnami/ctlscript.sh restart tomcat sudo nami restart com.bitnami.guacamole-server
NOTE: The steps above are sufficient to enable LDAP authentication with Apache Guacamole. However, if you wish to additionally store Apache Guacamole connection data in the LDAP directory, it is necessary to update your LDAP directory schema to support this additional data. These optional changes are described in the Apache Guacamole documentation.
Step 4: Test the integration
At this point, the integration is ready to be tested. To do so, navigate to the Apache Guacamole dashboard and attempt to log in with valid user credentials from the LDAP directory. If the integration is successful, you should be logged in and presented with the Apache Guacamole dashboard, as shown below:
NOTE: If you completed Step 1, use one of the example usernames and credentials configured in that step, such as user01 and password01.
To learn more about the topics discussed in this guide, use the links below: