Apache Guacamole with Azure AD using SAML

This document describes how to enable single sign-on with a SAML 2.0 compliant identity provider.

In this guide, we will use Microsoft Azure Active Directory as the identity provider (IdP). You can use any SAML 2.0 compliant identity provider.

Assuming you already have a Guacamole server setup, this guide will teach you how to enable and configure the SAML plugin/extension.

I have mine setup in a Docker container using the image from https://github.com/oznu/docker-guacamole which includes a PostgreSQL server to make things easy. Unfortunately if you decide to use this image, keep in mind that it doesn’t include the SAML extension. If you want to test this configuration out and install said extension, you’ll need to download it from here https://archive.apache.org/dist/guacamole/1.2.0/binary/guacamole-auth-saml-1.2.0.tar.gz

What I did was launch a shell into my container ‘docker exec -it guacamole bash’, then you will want to download the extension using ‘wget https://archive.apache.org/dist/guacamole/1.2.0/binary/guacamole-auth-saml-1.2.0.tar.gz’ and then extract it using ‘tar zxvf guacamole-auth-saml-1.2.0.tar.gz’

wget https://archive.apache.org/dist/guacamole/1.2.0/binary/guacamole-auth-saml-1.2.0.tar.gz
tar zxvf guacamole-auth-saml-1.2.0.tar.gz

After extracting the files, you’ll want to move the .jar file to the extension directory, you can ignore all the other files and delete them afterwards if you wish.

cp guacamole-auth-saml-1.2.0/guacamole-auth-saml-1.2.0.jar /config/guacamole/extensions/

I will illustrate below how to create the application in Azure, or you can follow this guide. https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal

Now you’ll want to login into your Microsoft Azure Portal at https://portal.azure.com

Once logged in you’ll see this page below.

Navigate to Azure Active Directory, and click Enterprise Applications.

Enterprise Applications

+ New Application

Click New Application.

Create your own application

Create your own application.

Name this anything you want.

The only steps we will be using here will be 1. Assign users and groups, and 2. Setup single sign on.

+ Add user/group

None Selected

Choose users and click Select, then Assign.

Click Single Sign-on, then SAML.

Take note of the Login URL

Login URL will correspond to the saml-idp-url: parameter.

Now this is where things might differ slightly for you, I have my Docker host running the ‘SWAG’ container which includes an NGINX server being used as a reverse-proxy, as well as the LetsEncrypt utilities to provide self-signed SSL/TLS certificates, this is beyond the scope of this guide and there are many other guides out there which can help you set these up.

I have my Guacamole host accessible from https://guacamole.mydomain.example so for these next steps, I will provide that exact URL to the SAML/SSO configuration as shown below.

Click Edit

Edit these values and click save.

Now we are basically finished with the Azure Portal.

Below we will configure Guacamole to communicate with our new Enterprise Application.

Log in to your Guacamole server. If you happen to be using the same container image the default credentials are guacadmin/guacadmin

Click the menu in the top right of your Guacamole page and then Settings.

Click Users, then New User

What you want to do here is create a new user with the username and email matching your Azure AD login “username@domain.tld” and DO NOT set a password.

Edit your permissions accordingly.

Once you are done click SAVE.

Now we can move on to setting up the Guacamole server.

We need to edit the “guacamole.properties” file.

There are a few different ways to go about this but since I have my Guacamole container volumes setup to /home/brandon/.docker/config/guacamole I can access everything I need right from there

i’m using Visual Studio Code to open that file which is in

/home/brandon/.docker/config/guacamole/guacamole/

You will need to provide these parameters:

saml-idp-url

saml-entity-id

saml-callback-url

Remember the link I mentioned earlier to take note of? The LOGIN URL ?

This will be your SAML-IDP-URL value, so paste that there.

Your other two parameters will be your Guacamole URL, mine being shown above.

Once you are done, save your file and restart your Guacamole container.

docker restart guacamole

That’s it. Once you access your Guacamole login page you will be redirected to login with your Microsoft Azure AD credentials, once logged in you will be forwarded to Guacamole.