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. Leave the password field empty. 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://go.microsoft.com/fwLink/?LinkID=717349
- As Entity ID you may use the fully qualified domain name to your Guacamole instance
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.3.0.jar) is important because Guacamole processes the authentication extensions in alphabetical order.
```
sudo ln -s ../available-extensions/guacamole-auth-saml-1.3.0/guacamole-auth-saml-1.3.0.jar \
  /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-saml-1.3.0.jar
```
- Open /home/ec2-user/guaws/guacamole/etc/guacamole.properties and add these properties
```
# Available as "Login URL" from the Azure Active Directory Console
saml-idp-url: https://login.microsoftonline.com/020ae7ff-ffff-aaaa-0000-03bb2fe66189/saml2

# 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/
```
- 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-saml-1.3.0/guacamole-auth-saml-1.3.0.jar
    /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-saml-1.3.0.jar
write_files:
- content: |
      saml-idp-url: https://login.microsoftonline.com/020ae7ff-ffff-aaaa-0000-03bb2fe66189/saml2
      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.3.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/.

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