Skip to main content

SAML 2.0

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​

  1. 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.
  2. 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
  1. 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.5.2.jar) is important because Guacamole processes the authentication extensions in alphabetical order. 
      sudo ln -s ../available-extensions/guacamole-auth-sso-1.5.2/saml/guacamole-auth-sso-saml-1.5.2.jar \
        /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-saml-1.5.2.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.
  2. 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.5.2/saml/guacamole-auth-sso-saml-1.5.2.jar
    /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-saml-1.5.2.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.5.2.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.5.2/binary/guacamole-auth-sso-1.5.2.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.5.2/saml/guacamole-auth-sso-saml-1.5.2.jar \
        /home/ec2-user/guaws/guacamole/etc/extensions/guacamole-auth-0-saml-1.5.2.jar
  • Restart Guacamole by executing guawsctl restart guac.

Since version 1.4.0 of the extension, saml-strict mode is enabled by default. This requires the saml-idp-metadata-url parameter that includes the certificate of the signing authority. The saml-idp-metadata-url property can either point at a publicly accessible URL (recommended) or to a file. Place the metadata.xml file in the /home/ec2-user/guaws/guacamole/etc folder and then reference it in the guacamole.properties file with saml-idp-metadata-url: /etc/guacamole/metadata.xml.

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

Common Issues​

I receive a plain "Forbidden" error after the redirect from the Identity Provider

This can occur if your SAML response is long and you are using the AWS WAF and have configured a custom body size limit or are using the (AWSManagedRulesCommonRuleSet)[https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html]. To resolve the issue, first confirm that your WAF actually blocked the request. Then, proceed to raise the limit from its default of 8KB to at least 16KB.