This document describes how to enable single sign-on with a SAML 2.0 compliant IDP. We will provide the required steps to deploy Azure AD SAML toolkit for Apache Guacamole user authentication within a NetFoundry Network. The example is with Apache Guacamole bastion host solution.
Apache Guacamole is a browser based remote access tool that provides easy access to hosts in all your VPCs, across accounts and regions. Access to Windows desktops (RDP), Linux terminals (SSH) and Kubernetes Pods is supported. No client software needed, a modern browser is all you need. This also enables administrators in corporate environments behind restrictive proxies to access remote servers in Data Centers & most public cloud providers like AWS, Azure & GCP.
Step by Step Instructions
1. Before you start with the integration, make sure that users in your Azure AD(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 (e.g...same email address).
-
- Log into Guacamole as administrator, by default that's the
guacadminuser 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. Hint: clone guacadmin user for full admin permissions.
- Log into Guacamole as administrator, by default that's the
2. Configure the Azure AD for application authentication. Microsoft guide here. Once logged into the console, navigate to the Azure Active Directory context. Then select Enterprise applications and New application.
3. Search for Azure AD SAML Toolkit, select it and hit create.
4. Once it is installed to the platform, select Azure AD SAML toolkit where you are brought to the configuration context. At this point you will want to assign users to be authenticated by Azure AD and set up single sign on functionality for the Guacamole application.
Azure AD Toolkit Configuration pane
Assign Users
Basic SAML configuration Step 2 in Azure. We will use the FQDN provided by AWS in this example as the public URL. We will be using this URL for NetFoundry AppWAN definition only. The overlay network connection will be private. The Entity ID is the consumption URL for users. The Reply url will be the same. The login or sign on URL will be https://login.microsoftonline.com. Hit Edit and create values for your instance and hit save.
5. Configure SAML authentication for your Apache Guacamole instance. Some deployments may or may not have the SAML module installed. The documentation to install SAML module is provided here.
In the root directory of the Guacamole installation, e.g. /home/bitnami/stack/guacamole, edit guacamole.properties file to include Azure AD properties.
NOTE: For the login URL, use the App Federation Metadata URL taken from the SAML signing certificate menu in Azure portal.
guacd-hostname: 127.0.0.1
guacd-port: 4822
postgresql-hostname: 127.0.0.1
postgresql-port: 5432
postgresql-database: bitnami_guacamole
postgresql-username: bn_guacamole
postgresql-password: 55581d1c249fb28a55b5ff2a29a3278cdf547bd93589f273831753f1ef137f17
#login URL
saml-idp-url: https://login.microsoftonline.com/62d7b151-0da3-4658-aac6-7dda640c90de/saml2/
#Entity ID
saml-entity-id: http://ec2-15-222-2-79.ca-central-1.compute.amazonaws.com
#Redirect URL
saml-callback-url: https://ec2-15-222-2-79.ca-central-1.compute.amazonaws.com
6. Reboot server.
7. This guide assume a NetFoundry network has been implemented and endpoint software is deployed on Guacamole server and remote endpoints requiring access. Build a Advanced network service for the Guacamole server which includes ports 22, 80 & 443 and include this service within desired AppWAN. With this configuration, you will be able to remove all inbound ports rules from your firewall and securely manage the server itself and gain access to all of the servers within it's configuration.
