Guacamole Single Sign-On using AWS SSO

This document describes how to enable single sign-on with AWS SSO, a 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.
Logon to your AWS SSO account and create a new application (https://console.aws.amazon.com/singlesignon/home#/applications)
Choose "Add a custom SAML 2.0 application"
Under Application properties enter the following values:
- Application start URL The fully qualified domain name (FQDN) to your instance, e.g. https://ec2-3-87-158-211.compute-1.amazonaws.com/
- Relay state leave empty
- Session duration 1 hour (can be increased if necessary)
Under Application metadata, choose to manually enter the data
- Application ACS 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
- Application SAML audience 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)
- 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.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

# Download the "AWS SSO SAML metadata" file and place it in /home/ec2-user/guaws/guacamole/etc
saml-idp-metadata-url: file:///etc/guacamole/saml-metadata.xml

# 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

Update the Attribute mappings in the AWS SSO application configuration.
- If you are using the AWS SSO directory, set the Subject attribute to ${user:email} and select emailAddress as format.
- If you are using AWS Managed Microsoft AD, set the Subject attribute to ${dir:email} and select emailAddress as format.
- You MUST add at least one additional attribute, for example Attribute Name with value ${user:preferredUsername} and unspecified format.
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: |
    <?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ...>
      <!-- more XML -->
    </md:EntityDescriptor>
  owner: root:root
  permissions: '0644'
  path: /home/ec2-user/guaws/guacamole/etc/saml-metadata.xml
- content: |
      saml-idp-metadata-url: file:///etc/guacamole/saml-metadata.xml
      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/.

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