corporate

Guacamole Bastion Host

Guacamole is a browser based remote access tool that provides easy access to hosts in your VPC. Both Windows desktops (RDP) and Linux terminals (SSH) are supported. No client software needs to be installed, a HTML5 capable web browser is all you need. This also enables administrators in corporate environments behind restrictive proxies to access remote servers on AWS.

connection

This product ships with version 0.9.14 of the popular open-source HTML5 RDP and SSH client Apache Guacamole (http://guacamole.apache.org/) and GuAWS, an agent that queries your AWS environment to automatically discover running instances. GuAWS is continously scanning your VPC for new instances using the AWS API. Your servers are organized by security groups which makes it easy to find the right instance and manage access. Additionally, connections opened by users are logged to CloudWatch logs.

A user management system provides fine grained access control to individual groups or instances. More details can be found at http://guacamole.apache.org/doc/gug/using-guacamole.html. Single sign-on and Multi-Factor authentication can be enabled through external identity provider such as Duo or Auth0. Detailed instructions can be found in the Authentication section.

Setup Instructions

The instance must be launched with an IAM instance profile to retrieve running instances from the AWS API and to push the audit log to CloudWatch Logs. You can also choose to run this AMI without the instance profile applied. In that case the automatic discovery of instances and audit log will not be available.

Make sure that the Guacamole EC2 instance has network connectivity to the target systems. This means that the Guacamole instance must be attached to a security group that allows outgoing traffic on ports 22 and 3389. The instances you want to connect to must have a matching incoming rule in their security group. The easiest way to achieve this is by putting all instances, including the Guacamole instance, in the “default” security group of the VPC.

Create Instance Profile using CloudFormation

Simply follow this link to launch the stack.

Launch Stack

Create Instance Profile manually

  1. Go to https://console.aws.amazon.com/iam/home#roles$new
  2. Choose EC2 under services that will use this role
  3. Select the EC2ReadOnlyAccess and the AWSLambdaBasicExecutionRole policies and click Next
  4. Provide a role name such as "GuAWS" and click on Create Role
  5. When launching the instance pick the role in step 3. Configure Instance

Accessing the Application

The instance should be fully booted within 5 minutes after launch. Access the application via a browser at https://[public_dns]/. Please ignore the certificate warning and proceed to the website (in Chrome, click on Advanced and then proceed to ...). The default user is guacadmin, the default password is the instance ID.

To connect to the underlying operating system of the EC2 instance connect via SSH with the username ec2-user.

Security

This service will listen for HTTP and HTTPS traffic on port 80 and 443, respectively. Any attempt to connect via port 80 will upgrade the connection to HTTPS. The HTTPS connection is protected with a self-signed certificate.

Best practice is to put an Application Load Balancer (ALB) in front of this instance which allows you to put a properly signed certificate in place. The health check must be configured with protocol HTTPS, port 443 and path /. Please have a look at the Guacamole Cluster which provisions all of these components through a CloudFormation template.

Alternatively, the SSL certificate on the server can be replaced as well. The certificate and private key are stored at /home/ec2-user/guaws/nginx/ssl/. Run sudo service guaws restart to restart the web server.

Enable Authentication Extensions

Auth0 Integration

Auth0 provides single sign-on across applications with two-factor authentication and federation to enterprise identity providers such as Microsoft Active Directory.

Integration with Auth0 is implemented through the auth-openid extension. This integration works also with other OpenID Connect compatible identity providers.

  1. Before you start with the integration, make sure that users in Auth0 and Guacamole share the same username. Auth0 uses the email address as username by default. The users in Guacamole have be be named accordingly.
  2. Create a new client (https://manage.auth0.com/#/clients/create) and choose Regular Web Application
  3. In the Settings tab, add the Public Hostname of the EC2 instance to the Allowed Callback URLs (e.g. https://ec2-00-00-00-00.compute-1.amazonaws.com/).
  4. Set the JWT Expiration (seconds) to 3600. Auth0
  5. Enable the OpenID Connect extension by linking the extension into the extensions folder. Execute the following command from /home/ec2-user/guaws. The destination file name (guacamole-auth-0-openid-0.9.14.jar) is important because Guacamole processes the authentication extensions in alphabetical order.
     ln -s ../available-extensions/guacamole-auth-openid-0.9.14/guacamole-auth-openid-0.9.14.jar `pwd`/guacamole/etc/extensions/guacamole-auth-0-openid-0.9.14.jar

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

     # Replace mytenant.auth0.com with your tenant domain
 openid-authorization-endpoint=https://mytenant.auth0.com/authorize
 openid-jwks-endpoint=https://mytenant.auth0.com/.well-known/jwks.json

 # The issuer to expect for all received ID tokens.
 openid-issuer=https://mytenant.auth0.com/

 # Include your client ID which can be found in the Settings tab
 openid-client-id=

 # Replace with the Public Hostname of the EC2 instance
 openid-redirect-uri=https://ec2-00-00-00-00.compute-1.amazonaws.com/
  7. Restart Guacamole by executing docker-compose -f /home/ec2-user/guaws/docker-compose.yml restart guac. If Guacamole does not come back after the restart command or if signing in fails, review the log files by executing docker-compose -f /home/ec2-user/guaws/docker-compose.yml logs -f guac.
  8. Visit the public hostname of your EC2 instance and you will be redirected to Auth0 for authentication.

Duo Two-Factor Authentication

Duo’s Trusted Access platform verifies the identity of your users with two-factor authentication and security health of their devices before they connect to the apps you want them to access.

The Duo authentication extension allows users to be additionally verified against the Duo service before the authentication process is allowed to succeed.

  1. Sign in to the EC2 instance as user ec2-user and change to the directory /home/ec2-user/guaws.
  2. Enable the Duo extension by linking the extension into the extensions folder.
     ln -s ../available-extensions/guacamole-auth-duo-0.9.14/guacamole-auth-duo-0.9.14.jar `pwd`/guacamole/etc/extensions
  3. Sign up for Duo and sign in as the account administrator at https://admin.duosecurity.com/login
  4. Create and enroll a new user guacadmin (user names in Guacamole must match the user names in Duo) Enroll
  5. Add a new application of type "Web SDK" and click on "Protect this Application" Application

  6. Configure Duo by adding the following lines to /home/ec2-user/guaws/guacamole/etc/guacamole.properties

     # the following three configuration keys are provided by Duo
 duo-api-hostname=api-xxxxxxxx.duosecurity.com
 duo-integration-key=
 duo-secret-key=

 # a random key that is used by Guacamole to secure the session. Must be at least 40 characters long.
 duo-application-key=
  7. Restart Guacamole by executing docker-compose -f /home/ec2-user/guaws/docker-compose.yml restart guac. If Guacamole does not come back after the restart command, review the log files by executing docker-compose -f /home/ec2-user/guaws/docker-compose.yml logs guac.
  8. After signing in to Guacamole you will be redirected to Duo where you will have to complete the two-factor challenge to seccessfully sign in.

Screen Recording

Sessions can be recorded graphically. Screen recording needs to be enabled in the connection settings. The recording path needs to be set to /opt/guacamole/recordings. Recordings will be written in a proprietary format that needs to be encoded before it can be played back. Use the guacenc utility to encode the raw stream into a m4v video file.

We recommend that you attach an additional EBS volume to the guacamole if you are using session recording extensively. The raw session recording can become quite large and you will eventually run out of disk space on the root volume which might impact the availability of the service. Mount the additional EBS volume under /opt/guacamole and create a folder recordings with ownership set to ec2-user.

Patching

The server can be patched manually by accessing the server via SSH. Execute sudo yum update -y to upgrade the operating system. Reboot the instance.

We will also be publishing new AMIs after critical security vulnerabilities have been published. As a subscriber to the AMI you will be notified immediately.

Audit Log

The application will write an Audit Log of users who have signed in and opened connections to AWS CloudWatch Logs (if the instance profile was provided). The audit log contains information about the session start date, end date, instance id, IP and protocol of the session.

audit log

Performance

For best performance make sure that your environment supports the WebSockets protocol. Some HTTP proxies do not allow WebSockets connections. The service will then fall back to regular HTTP communication which works reasonable well but is not as efficient.

Guacamole is a Java based application. Memory consumption is therefore always a concern. If the application becomes unresponsive or if you experience 502 Bad Gateway error message, stop the instance and upgrade to a larger instance type. The recommended instance type for small teams with 15 concurrent connections is m5.large. T2 instances should only be used for testing. If the instance is heavily utilized, you might run out of CPU credits on the T2 instance types. The application will become unresponsive and you will need to reboot or upgrade to larger instance type.

Support

For paid support, email sales@netcubed.de for further information. Free support is provided via support@netcubed.de.

For free support, we do not provide a guaranteed response time. However, we do our best to respond to questions within 24 hours Monday through Friday.

Changes

v1.4.0

v1.3.0

v1.2.1

v1.2.0

v1.1.2

v1.1.0

v1.0.0

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