Apache Guacamole with LDAP and 2FA TOTP authentication

I have been looking for a solution to access my lab from outside of my network securely. I have been meaning to use Apache Guacamole for some time and never really gotten a chance to play around with it until now. I was in a time crunch and need to test a new network design for my work’s new multi-tenant backbone network. I could Wireguard to my homelab from work via my mobile device, but it is not ideal to use my mobile device to run what I was trying to do. So, I was forced to deploy Apache Guacamole from oznu/guacamole, so that I can access my homelab from work. Since the Linuxserver folks already have a template for the NGINX server block, I thought might as well use the Linuxserver.io Letsencrypt Docker container to work with EVE-NG and do some homelabbing.

If you are using Unraid, see Figure 1 for the screenshot of my Docker container. By the way, the container I was using was from oznu/guacamole repository and this is not available in the Unraid CA. You would need to pull this from the Docker Hub.

If you are using OpenMediaVault, Figure 2 through 4 are the screenshots of the oznu/guacamole settings.

If you are using docker-compose, this is the docker-compose.yml template. Just adjust the values based on your environment.

version: "2"
services:
  guacamole:
    image: oznu/guacamole
    container_name: guacamole
    environment:
      - EXTENSIONS=auth-ldap,auth-totp
    volumes:
      - </path/to/appdata/config>:/config
    ports:
      - 8080:8080
    network:
      - proxynet

  letsencrypt:
    image: linuxserver/letsencrypt
    container_name: letsencrypt
    cap_add:
      - NET_ADMIN
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - URL=yourdomain.url
      - SUBDOMAINS=www,
      - VALIDATION=http
      - DNSPLUGIN=cloudflare #optional
      - DUCKDNSTOKEN=<token> #optional
      - EMAIL=<e-mail>
      - DHLEVEL=4096
      - ONLY_SUBDOMAINS=false #optional
      - EXTRA_DOMAINS=<extradomains> #optional
      - STAGING=false #optional
    volumes:
      - </path/to/appdata/config>:/config
    ports:
      - 443:443
      - 80:80 #optional
    network:
      - proxynet
    restart: unless-stopped

networks:
  proxynet:
    driver: "bridge"

Regarding the PUID and PGID, check this post.

Navigate to the /config/guacamole, in my system (Unraid), it is located in /mnt/cache/appdata/oznu_guac/guacamole. From here, you will see the file guacamole.properties. We will need to edit this file to enable LDAP and TOTP.

postgresql-hostname: localhost
postgresql-port: 5432
postgresql-database: guacamole_db
postgresql-username: guacamole
postgresql-password: null

ldap-hostname: 192.168.7.40 ## Your LDAP server IP address or hostname
ldap-port: 389 ## default
ldap-encryption-method: none ## Default
ldap-max-search-results: 1000 ## default
ldap-search-bind-dn: uid=apache_guacamole,cn=users,dc=domain,dc=local ## Adjust based on your bind dn
ldap-search-bind-password: $3cr3t_P@5sw0rd ## Use a better password for your bind
ldap-user-base-dn: dc=bgdhome,dc=intranet ## Adjust based on your base dn
ldap-username-attribute: uid ## default
ldap-user-search-filter: (objectClass=*) ## default

totp-issuer: apache_guacamole
totp-digits: 6
totp-period: 30
totp-mode: sha512 

There are three blocks of snippets above. The first block is the default postgresql database. This is the local account database. Assuming that you already have an LDAP server running, the second block is the LDAP authentication installation parameters. This block is what connects the Apache Guacamole to the LDAP server for user authentication. The third block is the TOTP. This will enable 2FA authentication after the username and password authentication. You can use Google Authenticator or something similar. I use Bitwarden.

After modifying the file guacamole.properties, you would need to restart the guacamole container.

docker-compose restart guacamole

By default, when the LDAP user logon using your the LDAP credential, Guacamole allow the user to login. However, the LDAP user won’t be able to do anything other than logging out. What we want to do here is to use the LDAP credential and a 2FA authentication and use the Guacamole to VNC, RDP and SSH in to target devices. Unfortunately, Apache Guacamole does not support just LDAP and 2FA together, as far as I know. 2FA only works with the local Guacamole account. However, we can utilize the local postgresql database to allow us to accomplish our goal.

As long as we create a local user, via the Guacamole web UI Settings, that has the same username as our LDAP user, Guacamole will allow the LDAP user to login using the user’s LDAP credentials. Also, since the user exists within the local database, Guacamole will prompt the LDAP user to enter 2FA. The only downside to this is it is not scalable because we have to create a local user for each LDAP user who needs to access the Guacamole.

Back to creating the local user within the Guacamole. To allow the LDAP users to access the dashboard, make sure during the local account creation, mark the Create new connections box as shown in Figure 5. Otherwise, the user won’t be able to get to the Guacamole Home or the dashboard.

Hope you’ll find this useful. Cheers!