Apache Guacamole: How To Install and Configure
A few months ago, we had a need for an easy Remote Desktop Protocol gateway (RDP gateway), and we weren’t sure what would be best to use. However, a quick Google search brought up an open source option – Apache Guacamole.
Apache Guacamole is self-described as clientless remote desktop gateway. Guacamole supports the standard protocol most people will use for authentication – SSH and RDP. It also supports VNC and telnet (for all you who like to end up on Shodan). The absolutely awesome aspect of Guacamole is that it can broker authentication between you and a Windows system without requiring any plugins client-side. It’s all done via HTML5! This means that once you get Guacamole installed, you can configure it to point to your Windows (or Linux) systems and you can instantly connect to them through the Guacamole web app.
This was pretty awesome to us, so we tested deploying it in a lab environment, and that’s the point of this post today. We walk you through an easy way to get Guacamole up and running for you to test.
Installing Apache Guacamole
Installing guacamole is pretty simple, and can be done with one command. I personally have tested this on Debian, but I would assume that it’s largely the same with Ubuntu as well. Just run the following apt-get command:apt-get install -y guacamole-tomcat libguac-client-rdp0
The above command will install Apache Guacamole and the modules to allow you to connect to systems over RDP through Guacamole. In the event that you want to add additional protocol support, you could choose to add any of the following modules:
- libguac-client-ssh0
- libguac-client-vnc0
- libguac-client-telnet0
Once everything is installed, all files related to Apache Guacamole are going to reside within /etc/guacamole, and Guacamole should be started and running on port 8080 of your system.
Apache Guacamole Configuration
Now that guacamole is installed, the next step is configuring it to connect to our Windows system. In this case, we have a Windows 10 system located at 172.16.93.141 and our local administrator account is named “LocalAdministrator” and the password is “FortyNorthSecurityLabPass”.
User Account Set Up
In order to connect to this system, we have to build out a user account that allows us to authenticate into Guacamole, and then create a connection for our user account pointed at our Windows 10 system. To accomplish both tasks, we’ll be editing the /etc/guacamole/user-mapping.xml file. In this case, I’ll show the final configuration and walk you through what it means.
Apache Guacamole lets you create user accounts within the user-mapping.xml file by providing a username and password within “authorization” xml tags. The password can either be stored plaintext (shown in the red box above) or as a MD5 hash (shown in the commented section). For ease of testing, this account stores its password plaintext, but in a production environment this should obviously use a more secure method to authenticate users to Guacamole.
For this test server, we are creating the user account “guacadmin” and password “guacadmin”. If you made no other changes, other than just creating the authorization tags, you should be able to log into guacamole itself (although no connections would be available).
Create a Connection
To create a connection, you’ll use the “connection” tag, and name your connection. In this instance, we chose the name “WS1” for our Windows 10 system. Next, you need to specify the protocol, so we are using RDP to connect to our Windows 10 system.
The parameters within the connection define how Guacamole will connect to our Windows 10 system. I’ll expand on these parameters here:
- “Hostname” 172.16.93.141 – This is the IP address of the Windows system we are connecting to
- “Port” 3389 – This instructs Guacamole to connect over RDP to port 3389
- “Username” LocalAdministrator – This specifies that Guacamole should use the user account “LocalAdministrator” to authenticate to our Windows system
- “Password” FortyNorthSecurityLabPass – This also instructs Guacamole to use the password “FortyNorthSecurityLabPass” to authenticate to our Windows system
- “Security” nla – This specifies that our RDP connection will require Network Layer Authentication (NLA). When using NLA, you need to specify the username and password in the parameters for the connection. Other security connection options include tls, rdp, etc.
- “Ignore-Cert” true – This configures Guacamole to allow untrusted certificates that are presented when connecting over RDP. If you do not enable this parameter and the system presents an untrusted certificate, the connection will fail
Once you’ve configured your user-mapping.xml file, you can immediately log into Guacamole (http://<YOURIPADDRESS>:8080/guacamole) and your configuration will take place immediately, no restart required. You should see the following portal asking for you to authenticate, and the account credentials (guacadmin/guacadmin) will provide access.
Since we only provided a single connection, Guacamole will immediately attempt to connect us to our Windows 10 system right after we authenticate . If everything in our configuration is correct, you should be now connected!
Troubleshoot
In the event that there is an issue with your configuration (either Guacamole or Windows side), you will see something similar to the following image.
In this case, my first suggestion would be to check both your ignore-cert and security parameters within you user-mapping.xml file. Outside of that, check the other basics as if you were troubleshooting a normal RDP connection issue.
Ctrl – Alt – Shift will be your best friend when using Guacamole, it will let you copy and paste into the terminal!
At this point, you are ideally connected into your system and can easily do anything you normally would do over RDP through your web browser! If you have any questions at all, feel free to send us a message on Twitter or contact us. Also, don’t forget that we are providing Red Team training with our Intrusion Operations class at BlackHat USA this summer and NolaCon! Come visit us in either Las Vegas or New Orleans!