Integrate Bitnami's Apache Guacamole Stack with an LDAP Directory for User Authentication

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:

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:

Step 1: Deploy an OpenLDAP service

Tip

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:

    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:

Guacamole login

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: