TN 6022: Guacamole Integration

Adding an Apache Guacamole broker to enhance Remote client connections

Overview

Sassafras KeyServer Platform 7.7 and later in the LabSight and AllSight product tiers offer integration with Apache Guacamole. Using a broker server you can have fully web based remote connections that are cross platform consistent and have enhanced capabilities from traditional direct VNC and RDP connections. This article details how you can integrate your Sassafras Server with your Guacamole server.

Files required for this can be found in Integrations/Guacamole of full disk image:

remote-broker-7.7.x.x.war

sassafras.json

Prerequisites

The setup of the linux server to host the broker and the below requirements thereof are outside of Sassafras Software assistance as they are 3rd party software. We offer the below guidance based on experience. Sassafras Software will assist with troubleshooting our integration. In installation dependency order, we have the following requirements:

Java (8/1.8 or later)

Tomcat 9 (as of KeyServer 7.7.1.0 Tomcat 10 is not compatible)

Guacamole Server (guacd) 1.2.0 or later

In many cases you will need to compile Guacamole from source as repos may not have the required version, or the repo version may not have been compiled with the needed libraries for our integration. Note that Guacamole has several of it's own dependancies for compiling. In addition, you want to make sure several "optional" packages are in fact present so you have RDP, VNC, and SSL support.

Tomcat will be installed somewhere like /usr/local/tomcat9 or /var/lib/tomcat9.
Create if needed: /etc/guacamole

Click here to see an example of installing Guacamole on Ubuntu 20.

These steps assume Tomcat is already installed and include all our needed libraries for the integration. Like steps on other distros should also work but the specific commands (e.g. yum instead of apt) may be needed.

sudo apt install libpng-dev
sudo apt install libjpeg-dev
sudo apt install libvncserver-dev
sudo apt install freerdp2-dev
sudo apt install cairo-5c
sudo apt install libcairo-5c-dev
sudo apt install libcairo2-dev
sudo apt install libuuid1
sudo apt install libossp-uuid-dev
sudo apt install libwebsockets-dev
sudo apt install libssh2-1-dev
sudo apt install libpango1.0-dev

wget https://downloads.apache.org/guacamole/1.3.0/source/guacamole-server-1.3.0.tar.gz
tar -xvf guacamole-server-1.3.0.tar.gz
cd guacamole-server-1.3.0
./configure --with-init-dir=/etc/init.d --with-systemd-dir=/etc/systemd/system --with-websockets --with-ssh
sudo make install
sudo systemctl start guacd
sudo systemctl enable guacd

See also for example steps 1 and 2 of this blog post (we provide no guarantees about third party information, this is just an example).

Configuration

Guacamole Server

Copy the sassafras.json file into /etc/guacamole. Edit the file to contain the URL of the KeyServer in the server and uri values.

{
	"server": "https://keyserver.sample.net",
	"uri": "https://keyserver.sample.net",
	"websockets":false,
	"guacdhost":"localhost",
	"guacdport":4822,
	"configs":[
	]
}

The server parameter is what Java will use to talk to the KeyServer. Note that you can only use https:// if the server has a proper, trusted SSL certificate, otherwise use http://. The uri parameter is what is used for the UI (Back to Maps) button, so this can be customized with a frame-core for example, or even point to a specific Floorplan. Also include the port if it’s not the default (80 or 443 by protocol).

Note the configs parameter may not be there by default, and is not needed unless you use scopes (see below).

Copy the war file into tomcat’s web apps directory and remove the version string for ease of upgrade in the future. For example:

   cp remote-broker-7.7.0.1.war /usr/local/tomcat9/webapps/remote-broker.war

By removing the version string you can easily upgrade the war file in future releases by replacing the old one without needing to reconfigure the Sassafras Server side. Improvements have been made several times throughout the 7.7.x release versions, so you should always update the war file when updating KeyServer. To check the version that is currently in place, look at the contents of remote-broker/META-INF/maven/com.sassafras.guacafras/remote-broker/pom.properties.

Restart Tomcat as needed to apply changes to the json and ensure the war file is unpacked by Guacamole and initialized. You will see a folder named remote-broker created in the webapps folder the first time this happens.

Scope Options

If needed, you can set up “common” passwords on a per-protocol, per-map, or per-computer basis by editing the sassafras.json file. These options are added to the configs section of the above file format. Simply add stanzas per the below example between the brackets. The value for each configuration stanza's “scope” can be one of:

vnc://computerid
computerid
vnc://connectionaddress
connectionaddress
vnc://mapname
mapname
vnc://

This specifies to use a specific protocol, or be independant of protocol, or replace “vnc” with “rdp” as needed. That is, you can scope to a specific id/address/map but not protocol, or to a protocol only (global), or to a specific protocol for a specific id/address/map depending on the syntax used.

The configurations will be checked in the order written in the json file, first match wins.

So for example if all the vnc computers in “Lab A” had a common name/pass, you’d have:

	"configs":[
	  {
		"scope": "vnc://@Lab A",
		"username": "bob",
		"password": "secret"
	  }
	]

Or if all the rdp computers had a common name/pass, you could use "rdp://Lab A” instead. Or if all the computers, regardless of vnc/rdp had the same name/pass, you’d just use “Lab A” for the scope.

Note that each scope will be a separate stanza from other scopes, do not merge them. There must be a comma after the } if there is another stanza after it.

Sassafras Server

Once the Guacamole server is set up, you need to change the Remote Settings as needed on your Floorplans in the Sassafras Web UI. For example, set Mac to VNC Broker and Windows to RDP Broker, along with setting the Broker Server address and optionally using the Pass Full Credentials option if your users are authenticating to the Sassafras Web UI using Active Directory or LDAP.

The URL for the Broker will be something like:

   https://guac.host.name:8443/remote-broker/

If the broker address is correct, you will see our war file login form, NOT the default Guacamole login. The latter accesses their web UI which we do not use. The former is the credentials to be passed to the remote workstation. Note the trailing slash is required by Tomcat or the page will not load properly.

Right		Wrong

Tomcat Footnote

Note this assumes the default Tomcat port is being used, which is configurable if you like. It also assumes you followed the above information to rename the war file so it is easily upgraded. Also note the default Guacamole front end url pathing is not used here, so all you likely need to change from the example is your Sassafras Server address.

While you can use http, we recommend you use https which by default on Tomcat is port 8443. If you change that, change the above accordingly. HTTPS requires putting an SSL certificate in Tomcat.

While the Tomcat SSL process is outside our software, we offer these steps based on experience.

Create a keystore. You will be prompted for details that will be used for the CSR (Certificate Signing Request) in the next step. Use the normal answers needed for your CA (Certificate Authority, e.g. Comodo or GoDaddy). You will also set a keystore password. Note this will be in plain text in the Tomcat config file later so use an appropriate password given that fact. Replace "mydomain" with the server name/FQDN Tomcat is using.
```
keytool -genkey -alias mydomain -keyalg RSA -keystore yourkeystore.jks  -keysize 2048
```

Create the CSR. Submit it to your CA to get the cert.

keytool -certreq -alias mydomain -keystore keystore.jks -file mydomain.csr

Optional: Import the root and intermediate certs. Obtain these crt files from your CA. This is not needed and should be skipped when using a PKCS file for the server cert which contains the full certificate chain.
```
keytool -import -trustcacerts -alias root -file RootCA.crt -keystore yourkeystore.jks
keytool -import -trustcacerts -alias interm -file IntermediateCA.crt -keystore yourkeystore.jks
```

Import the certificate. Use the PKCS#7 PEM encoded file when possible (Comodo).

keytool -import -trustcacerts -alias mydomain -file mydomain.crt -keystore yourkeystore.jks

Move the jks file to a desired location and ensure Tomcat can read it.

Edit the Tomcat server.xml (usually in conf folder) to enable port 443 and point it to your keystore. By default it should look something like this:

<Connector port=”443″ protocol=”HTTP/1.1″
SSLEnabled=”true”
scheme=”https” secure=”true” clientAuth=”false”
sslProtocol=”TLS” keystoreFile=”/your_path/yourkeystore.jks”
keystorePass=”password_for_your_key_store” />

Permissions

The account used to sign into your Sassafras Web UI must have a new privilege on the computers you try to remote to. Computer Privileges -> Connect Remotely (via KeyReporter). This can be in a role the account holds, or you can use the Remote Connection Role for ease of adding this to existing accounts. You can also add that role to the KeyReporter Guest or Community if you want this to be open, or add it to your default account in a fully authenticated configuration.

Note if you're using Active Directory as your authentication you must be using Secure Authentication not NTLM or Kerberos for the credentials to pass. For clarity, passing credentials will not work if you use one of the new SSO authentication options (Azure, Google, Okta).

Tools

Once you are connected to the remote machine, there is a toolbar that will drop down if you mouse to the top of the screen.

The Sassafras Software logo will return you to our Web UI.

The arrow buttons change the way screen size is handled. The "in" arrows are scale mode (default for VNC), which means whatever the remote resolution is set to we will fit it to the browser window. The "out" arrows are auto mode (default for RDP), which means the remote resolution will increase or decrease with the browser window. Either way we fit to the window, but scale could result in very tiny resolution, while auto will look more natural but is limited by your local screen size. Note that VNC (usually) does not respect auto mode.

The clipboard box is for sending and retrieving text from the remote clipboard. If you paste in text, it will be available on the remote system for paste. If you copy text on the remote system, it will be available in the box to re-copy and paste locally.

Troubleshooting

There are a few common (and several unique) issues we have seen with customers setting up this integration. First and foremost, re-check the above information. Ensure you are using the required versions of Tomcat and Gaucamole. Also ensure you are using the latest KeyServer version and associated WAR file. Make sure you are using the proper urls in all locations, and the proper file syntax in the json file.

If you receive a 512 error again check the above. This was last seen when a site used a pre 1.2 version of guacd. It can also be caused by a typo in the json file (a missing quote did this at one site) or by pointing the json to http instead of https when you are forcing https in the Sassafras Web Service Settings. Another site had this due to Tomcat running under an account that did not have proper file system access.

If you receive a 515 or 516 error check your network configuration. This tends to mean remote access is not enabled or reachable on the workstation, or the workstation can not reply to the Guac server. Remember in this scenario the workstation is the server and the guac server is the client when talking communication protocols.

If you receive a 519 error check your network configuration and associated settings. This is most commonly seen when trying to use computer name in the Remote settings, but the name is not in DNS so the computer can not be found. Also make sure the server running Guacamole has access to DNS resolution.

See also the Guacamole documentation on these error codes.

There have been instances of "token" related errors. One cause is the system time/zone between servers being out of sync causing the token to not be valid. Another instance was permission based for which the customer found this correction:

sudo groupadd guacd
sudo useradd -r guacd -m -s /usr/sbin/nologin -g guacd -c guacd
edit: /etc/systemd/system/guacd.service
change the user line to: User=guacd

If you see a white screen and nothing more, it is likely you are experiencing an syntax issue with your domain authentication. Try logging in to our Web UI with user@domain syntax instead of domain\user syntax. It is also possible there are special characters in your division or computer identifiers that are unexpected or corruption in your station IDs. Contact us for assistance troubleshooting that issue.

Remember that VNC to MacOS systems is not as simply as RDP to Windows. Screen Sharing must be enabled on the workstation. Access to Screen Sharing dictates the account you must use in the broker authentication screen, NOT the normal OS login used at the workstation. The OS login comes after the SS login. There are methods to enable domain authentication for example in Screen Sharing, but that is outside of our support. Refer also to the above Scope settings to use a generic SS account in the json configuration if desired.

As always please contact support if you need assistance.