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.
This image ships with version 0.9.14 of the popular open-source HTML5 RDP and SSH client 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 AWS APIs. Your servers are organized by security groups which makes it easy to find the right instance and control access. Connections are logged to CloudWatch logs which provides easy access for audits.
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.
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.
Simply follow this link to launch the stack.
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 operating system, use SSH and the username ec2-user.
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 /.
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.
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.
extensions folder. 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
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/
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.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.
ec2-user and change to the directory /home/ec2-user/guaws.extensions folder. ln -s ../available-extensions/guacamole-auth-duo-0.9.14/guacamole-auth-duo-0.9.14.jar `pwd`/guacamole/etc/extensions
guacadmin (user names in Guacamole must match the user names in Duo)
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=
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.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.
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.
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 5 concurrent connections is m4.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.
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.
v1.3.0
guacamole.properties file possible.v1.2.1
v1.2.0
v1.1.2
v1.1.0
v1.0.0