Introduction

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

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:

  kubectl cluster-info
  

• 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: openldap
  

  Warning

  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.

Useful links

To learn more about the topics discussed in this guide, use the links below:

• Bitnami Apache Guacamole stack documentation
• Bitnami OpenLDAP container image documentation
• Apache Guacamole LDAP documentation
• Bitnami applications FAQ
• Bitnami documentation for Kubernetes deployments on different cloud platforms
• Apache Guacamole