Single Sign-On using SAML 2.0 on the Guacamole Bastion Host

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.

Step by Step Instructions

Before you start with the integration, make sure that users in your IdP and Guacamole share the same username and your user has administrative permission. By default, Guacamole will use the name attribute of the SAML assertion to identify the local user. The users in Guacamole have be be named accordingly (i.e. same email address).
- Log into Guacamole as administrator, by default that's the guacadmin user and the instance ID as password.
- Create a new user, as username use the email address of your user in your IdP. Set a random password. The password is be required until SSO is activated. Grant Administer system permissions and click Save.
Follow the instructions of your IdP to create a new SAML 2.0 application. For Azure Active Directory, follow the instructions at https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal
- Identifier (Entity ID) The fully qualified domain name (FQDN) to your instance, e.g. https://ec2-3-87-158-211.compute-1.amazonaws.com/ (must match the saml-entity-id in the guacamole.properties file)
- Reply URL (Assertion Consumer Service URL) The fully qualified domain name (FQDN) to your instance including the callback path https://ec2-3-87-158-211.compute-1.amazonaws.com/api/ext/saml/callback

Connect to the EC2 instance running Guacamole via SSH (user is ec2-user).

Enable the SAML extension by linking the extension into the extensions folder. The destination file name (guacamole-auth-0-saml-1.4.0.jar) is important because Guacamole processes the authentication extensions in alphabetical order.
```
sudo ln -s ../available-extensions/guacamole-auth-sso-1.4.0/saml/guacamole-auth-sso-saml-1.4.0.jar \
  /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-saml-1.4.0.jar
```

Open /home/ec2-user/guaws/guacamole/etc/guacamole.properties and add these properties

# Available as "App Federation Metadata Url" from the Azure Active Directory Console
saml-idp-metadata-url: https://login.microsoftonline.com/xxxYYYxxx/federationmetadata/2007-06/federationmetadata.xml?appid=xxxYYYxxx

# The Entity ID you assigned to this application
saml-entity-id: https://ec2-3-87-158-211.compute-1.amazonaws.com/

# The redirect URL
saml-callback-url: https://ec2-3-87-158-211.compute-1.amazonaws.com/

# Set this to false if the SAML authentication is working correctly
saml-debug: true

Restart Guacamole by executing guawsctl restart guac. If Guacamole does not come back after the restart command or if signing in fails, review the log files by executing guawsctl logs -f guac.

Visit the public hostname of your EC2 instance and you will be redirected to your IdP for authentication.

Configuration Options

Please refer to https://guacamole.apache.org/doc/gug/saml-auth.html for additional configuration options that might be required by your IdP.

Automating Deployment

The configuration of the authentication extension for SAML can be fully automated. This allows the deployment through CloudFormation or Terraform templates and cluster configurations. When launching the instance, provide the following UserData script. This will enable the SAML authentication extension and write the configuration file. Since the IP address and hostname of the instance are not known at the time of the launch (required for the saml-callback-url parameter), we recommend to attach an Elastic IP to the instance, create a DNS record that will point at the newly launched instance or attach the instance to an Application Load Balancer.

#cloud-config
runcmd:
  - >
    ln -s ../available-extensions/guacamole-auth-sso-1.4.0/saml/guacamole-auth-sso-saml-1.4.0.jar
    /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-saml-1.4.0.jar
write_files:
- content: |
      saml-idp-metadata-url: https://login.microsoftonline.com/xxxYYYxxx/federationmetadata/2007-06/federationmetadata.xml?appid=xxxYYYxxx
      saml-entity-id: https://ec2-3-87-158-211.compute-1.amazonaws.com/
      saml-callback-url: https://ec2-3-87-158-211.compute-1.amazonaws.com/
  owner: root:root
  permissions: '0644'
  path: /home/ec2-user/guaws/guacamole/etc/guacamole.properties

Debugging Issues

I'm not being redirected to the IdP for authentication

Please check the Guacamole logs for any errors. Run guawsctl logs -f guac to dump the logs to your terminal session. Shortly after restarting the service (guawsctl restart guac) you should see the following line:

guac_1   | 14:46:40.448 [localhost-startStop-1] INFO  o.a.g.extension.ExtensionModule - Extension "SAML Authentication Extension" loaded.
guac_1   | 14:46:41.715 [localhost-startStop-1] INFO  o.a.g.extension.ExtensionModule - Extension "MySQL Authentication" loaded.
guac_1   | 14:46:41.720 [localhost-startStop-1] INFO  o.a.g.extension.ExtensionModule - Extension "Adhoc Guacamole Connections" loaded.

Make sure that the "SAML Authentication Extension" is loaded before the "MySQL Authentication" extension. If the order is different, make sure that the extension JAR file in /home/ec2-user/guaws/guacamole/etc/extensions/ is called guacamole-auth-0-saml-1.4.0.jar Mind the -auth-0- part which ensures that the extension is loaded before any other auth extension).

If you don't see the "SAML Authentication Extension" at all, make sure the link in /home/ec2-user/guaws/guacamole/etc/extensions/ resolves properly to the actual JAR file in /home/ec2-user/guaws/guacamole/etc/available-extensions/.

To see more details on the SAML flow, make sure to enable saml-debug in the guacamole.properties file and restart the guac service guawsctl restart guac.

Upgrading the SAML Extension

The SAML extension can be updated to a newer version independently of the Guacamole version.

Log into the EC2 instance as ec2-user.

Run the following commands to download and extract the latest version of the extension:

cd /home/ec2-user/guaws/guacamole/etc/available-extensions
curl -sLo guacamole-auth-sso.tar.gz https://apache.org/dyn/closer.lua/guacamole/1.4.0/binary/guacamole-auth-sso-1.4.0.tar.gz?action=download
tar xf guacamole-auth-sso.tar.gz

Update the symbolic link in /home/ec2-user/guaws/guacamole/etc/extensions/ to point to the new version.

# remove any previous version of the plugin
rm /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-saml-*
ln -s ../available-extensions/guacamole-auth-sso-1.4.0/saml/guacamole-auth-sso-saml-1.4.0.jar \
    /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-saml-1.4.0.jar

Restart Guacamole by executing guawsctl restart guac.

Since version 1.4.0 of the extension, saml-strict mode is enabled by default. That requires that you must provide a saml-idp-metadata-url that includes the certificate of the signing authority. The saml-idp-metadata-url property can either point at a publicly accessible URL or to a file on the instance (using the file:// protocol, see SAML with AWS SSO for an example).

Please review the guides for setting up SAML authentication in case the login fails after the upgrade.

Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation.