Cookbook - Apache Guacamole - Setup Guide

This guide assumes you have followed Steps 1-3 in the main Cookbook - Apache Guacamole guide and have the Service Domain Name and SAML Metadata URL ready.

In this setup guide, we’ll upgrade your Guacamole deployment so your end-users can authenticate via SAML.

1. Download and extract the SAML Extension

SAML Authentication is not included by default with the official Apache Guacamole docker image; we’ll need to download the SAML Authentication separately and set it up on our system.

Begin by creating a folder on your desktop to store all of our Guacamole configuration files as well as extensions for Apache Guacamole:

$ mkdir -p /opt/guacamole/extensions
$ cd /opt/guacamole/extensions

Next, download the SAML Authentication extension from the official Guacamole Releases Page: https://guacamole.apache.org/releases/1.2.0/. Place and decompress the downloaded extension into the guacamole/extensions folder:

$ pwd
/opt/guacamole/extensions
$ wget -O guacamole-auth-saml-1.2.0.tar.gz "http://apache.org/dyn/closer.cgi?action=download&filename=guacamole/1.2.0/binary/guacamole-auth-saml-1.2.0.tar.gz"
$ tar xvzf guacamole-auth-saml-1.2.0.tar.gz
$ cp guacamole-auth-saml-1.2.0/guacamole-auth-saml-1.2.0.jar ./

2. Set up IDP Settings for SAML Authentication

In order for us to deploy guacamole with SAML Authentication, we need to enter the SAML IDP settings, specifically the SAML Metadata URL.

Place these in the guacamole.properties file which will tell Guacamole how to use the SAML Authentication extension/

$ pwd
/opt/guacamole
$ cat guacamole.properties
saml-callback-url: https://< SERVICE_DOMAIN_NAME >/guacamole 
saml-debug: true
saml-entity-id: http://< BACKEND_IP>:<BACKEND_PORT>/guacamole
saml-idp-metadata-url: < METADATA_URL FROM STEP 5 >
saml-group-attribute: eduPersonAffiliation
mysql-auto-create-accounts: true

3. Deploy Guacamole Web Application with SAML Authentication

With our setup completed, we can start the guacamole web application server:

$ pwd
/opt/guacamole
$ docker run --name guac-client --link guacd-server:guacd -d -p 8080:8080 -v $(pwd):/etc/guacamole -e GUACAMOLE_HOME=/etc/guacamole -e MYSQL_HOSTNAME=127.0.0.1 -e MYSQL_DATABASE=guacamole -e MYSQL_USER=guacadmin -e MYSQL_PASSWORD=ROOT_PASSWORD guacamole/guacamole

Note that you need to pass in the password for the guacadmin user in the MySQL Database for SAML authentication to work.


Your Guacamole deployment is configured for SAML!



Last modified: Sep 23, 2021