Apache Guacamole 1.6.0 Keycloak

Option A: AWS Marketplace console

• Open the SecureAnyCloud Hardened WireGuard VPN & VPN, Proxy and Remote Access AMIs listing on AWS Marketplace. Choose View purchase options, then Subscribe. One subscription covers every version in the listing.
• When the subscription is active, choose Launch your software.
• Choose One-click launch from AWS Marketplace, or Launch from EC2 Console for the full launch wizard. In Version, choose Apache Guacamole 1.6.0 + Keycloak on Ubuntu 24.04, then choose your Region.
• Pick an instance type and your key pair. m5.large is recommended. The software charge is $0.04 per vCPU per hour.
• Set the security group to allow SSH (22) from your own address and HTTPS (443) from the ranges your users connect from. Nothing else is needed.
• Choose your VPC and a public subnet (or attach an Elastic IP later). Leave the metadata defaults, because the image already requires IMDSv2. Then choose Launch.

Option B: AWS CLI

Run this command on your own workstation. Replace the AMI ID with the one shown for your Region on the Marketplace launch page. Replace the VPC, subnet, key pair and CIDR ranges with your own:

SG=$(aws ec2 create-security-group --group-name guacamole-keycloak \
  --description "Apache Guacamole + Keycloak" --vpc-id vpc-0123456789abcdef0 \
  --query GroupId --output text)
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 22 --cidr <your-mgmt-cidr>
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 443 --cidr <your-client-cidr>
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name my-key-pair \
  --security-group-ids "$SG" \
  --subnet-id subnet-0123456789abcdef0 \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=guacamole-keycloak}]'

You do not need --metadata-options, because the AMI already requires IMDSv2.

Connect as ubuntu with the key pair you chose:

ssh -i ~/.ssh/my-key-pair.pem ubuntu@<public-ip>

First boot takes two to three minutes. It creates the database, starts Keycloak for the first time, creates the realm, client and users, and then proves that a sign-in works end to end. The details are in /root/guacamole-keycloak-credentials.txt, which only root can read. This command prints everything except the two password lines:

sudo grep -vE '^(SSO_ADMIN_PASSWORD|KEYCLOAK_ADMIN_PASSWORD)=' /root/guacamole-keycloak-credentials.txt

# Apache Guacamole 1.6.0 + Keycloak 26.8.1 - generated on first boot by guacamole-keycloak-firstboot.service.
# Every value below is unique to this instance; nothing was baked into the image. GUACAMOLE_URL=https://44.203.97.41/ KEYCLOAK_ADMIN_URL=https://44.203.97.41/auth/admin/
# Sign in to Guacamole with this identity (Guacamole hands you to Keycloak; Keycloak checks the password). SSO_ADMIN_USER=sac-admin
# The Keycloak administration console (master realm): users, login policy, MFA, identity providers. KEYCLOAK_ADMIN_USER=sac
# The certificate is self-signed and unique to this instance (browsers warn on the first visit). TLS_CERT_SHA256=68:77:20:0E:F3:3A:61:58:5C:AA:BA:C0:E8:A0:5E:22:2C:A3:3C:CA:60:AA:AE:20:F4:B5:A6:68:03:FB:CA:7F
# New DNS name or Elastic IP:
sudo guacamole-keycloak-set-host <name-or-ip>
# Self-test:
sudo guacamole-keycloak-selftest
# Guide: https://secureanycloud.com/stacks/apache-guacamole-1-6-0-keycloak/

There are two identities:

• sac-admin (SSO_ADMIN_USER) signs in to Guacamole. It lives in the Keycloak realm SecureAnyCloud and is a Guacamole administrator.
• SecureAnyCloud (KEYCLOAK_ADMIN_USER) signs in to the Keycloak administration console (master realm), where you manage users, policies and identity providers.

Print a password only when you need it, for example sudo sed -n 's/^SSO_ADMIN_PASSWORD=//p' /root/guacamole-keycloak-credentials.txt.

All five services and the first-boot unit are active. Only SSH and HTTPS listen on a public address:

systemctl is-active postgresql@16-main.service keycloak.service guacd.service tomcat.service nginx.service guacamole-keycloak-firstboot.service /usr/local/sbin/guacd -v cat /opt/keycloak/version.txt
sudo ss -Htln | awk '{print $4}' | sort -u

active active active active active active Guacamole proxy daemon (guacd) version 1.6.0 Keycloak - Version 26.8.1 0.0.0.0:22 0.0.0.0:443 127.0.0.1:4822 127.0.0.1:5432 127.0.0.53%lo:53 127.0.0.54:53 [::]:22 [::]:443 [::ffff:127.0.0.1]:8080 [::ffff:127.0.0.1]:8081

127.0.0.53 and 127.0.0.54 are Ubuntu's local DNS resolver.

The self-test checks that every service is active and that guacd loads its RDP, VNC and SSH plugins. It then performs the whole single sign-on round trip through nginx exactly as a browser does. Guacamole sends the sign-in to Keycloak, a wrong password is refused, the SSO user's password is accepted, and Guacamole opens a session for sac-admin. The self-test also proves that Keycloak refuses admin/admin and that no guacadmin account exists. It prints no password:

sudo guacamole-keycloak-selftest

services: postgresql@16-main, keycloak, guacd, tomcat and nginx are active guacd plugins: rdp(88 params, VERSION_1_5_0) vnc(49 params, VERSION_1_5_0) ssh(42 params, VERSION_1_5_0) single sign-on: Guacamole -> Keycloak realm 'sac' -> per-instance password -> Guacamole session (wrong password refused) defaults: Keycloak admin/admin refused; the guacadmin account does not exist SELFTEST_OK

Open GUACAMOLE_URL from Step 2 (for example https://44.203.97.41/). The certificate is self-signed, so the browser warns you on the first visit. Compare the fingerprint it shows with TLS_CERT_SHA256 and continue. Step 10 replaces the certificate with your own. Guacamole sends you straight to the Keycloak sign-in page of the realm.

Sign in as sac-admin with SSO_ADMIN_PASSWORD. Keycloak returns you to Guacamole, signed in. The home page lists your connections, which is empty until you add one.

Open the user menu (top right), choose Settings, then Connections and New Connection. Give the connection a name and choose the protocol. Fill in the target's Hostname and Port under Parameters > Network (3389 for RDP, 5900 for VNC, 22 for SSH). If you want Guacamole to sign in for the user, also fill in the credentials under Authentication. Choose Save, and the connection appears on the home page.

This image's guacd supports RDP, VNC and SSH. The form also lists Telnet and Kubernetes, which this build does not include (Telnet is unencrypted). The target must be reachable from the instance. On the target, allow RDP, VNC or SSH from the Guacamole instance's security group, not from the internet.

Settings > Users shows every Guacamole identity. A user who signs in through Keycloak for the first time gets an account here automatically, with no connections until you grant them.

Users sign in with Keycloak, so you create them there. Open KEYCLOAK_ADMIN_URL (for example https://44.203.97.41/auth/admin/) and sign in as SecureAnyCloud with KEYCLOAK_ADMIN_PASSWORD. Switch to the Apache Guacamole realm (SecureAnyCloud) with Manage realms. Open Users, choose Add user, then set a password on the user's Credentials tab. The realm requires passwords of at least 12 characters that differ from the user name.

When the new user first signs in to Guacamole, Guacamole creates their account with no permissions. As sac-admin, open Settings > Users, select the user and tick the connections (or connection groups) they may use. To make someone a Guacamole administrator, grant Administer system on the same page.

Keycloak is also where you add multi-factor authentication. In the realm SecureAnyCloud, open Authentication and set OTP Form to Required in the browser flow, or give users the Configure OTP required action. You can also connect your corporate directory (User federation: LDAP or Active Directory) or another identity provider (Identity providers: SAML or OpenID Connect).

Guacamole loads the brute-force extension next to the PostgreSQL and OpenID Connect extensions. Its settings are in guacamole.properties: 5 failed logins from one address ban that address for 300 seconds. Keycloak's own brute-force detection is on for the master and SecureAnyCloud realms (Realm settings > Security defenses):

sudo ls /etc/guacamole/extensions
sudo grep -E '^(extension-priority|ban-)' /etc/guacamole/guacamole.properties

guacamole-auth-ban-1.6.0.jar guacamole-auth-jdbc-postgresql-1.6.0.jar guacamole-auth-sso-openid-1.6.0.jar extension-priority: openid ban-max-invalid-attempts: 5 ban-address-duration: 300

nginx passes the real client address and Tomcat trusts it from 127.0.0.1 only. The ban therefore applies to the attacker's address, not to everyone behind the proxy.

Sign-in redirects, the Keycloak issuer, the certificate and nginx all name one host. First boot uses the instance's public IPv4 address. If you stop and start the instance without an Elastic IP, the public address changes, and sign-in stops working until you run the helper again. The login message warns you when this happens. With no argument, guacamole-keycloak-set-host reads the current address from the instance metadata:

sudo guacamole-keycloak-set-host | tail -3

Host changed from 44.203.97.41 to 44.203.97.41: Guacamole https://44.203.97.41/ Keycloak admin https://44.203.97.41/auth/admin/ Certificate SHA-256: 35:97:DE:E8:01:55:42:BE:16:00:54:81:14:1A:D5:B1:85:2C:48:F8:46:36:FE:D1:55:1F:56:5C:E7:6B:00:4B SET_HOST_OK

To use your own name, point a DNS record at the instance and pass the name. Attach an Elastic IP first so the address never changes. For example: sudo guacamole-keycloak-set-host guac.example.com.

The helper updates the Keycloak client, Keycloak's hostname, Guacamole's OpenID Connect settings, nginx and the URLs in the credentials file. It issues a new self-signed certificate for that name, restarts the services and proves sign-in again. If nginx or Keycloak rejects the change, the helper restores the previous settings. It signs in to Keycloak with KEYCLOAK_ADMIN_USER and KEYCLOAK_ADMIN_PASSWORD from the credentials file, so if you change that password, update the file too.

After Step 9 sets the name, copy your certificate (full chain) and key over the self-signed pair and reload nginx:

sudo install -m 0644 fullchain.pem /etc/nginx/tls/server.crt
sudo install -m 0600 privkey.pem /etc/nginx/tls/server.key
sudo nginx -t && sudo systemctl reload nginx

Running guacamole-keycloak-set-host again later issues a new self-signed certificate, so copy your certificate back afterwards. Alternatively, put an Application Load Balancer with an AWS Certificate Manager certificate in front of port 443, and keep the self-signed certificate between the load balancer and the instance.

Every service of the stack carries an IPAddressDeny rule for the metadata addresses. A connection someone configures in Guacamole, a Keycloak identity-provider URL or anything else a user can influence therefore cannot reach the instance's credentials:

for u in postgresql@16-main keycloak guacd tomcat nginx; do printf '%-20s %s\n' "$u" "$(systemctl show -p IPAddressDeny --value "$u.service")"; done

postgresql@16-main 168.63.129.16/32 fd00:ec2::254/128 169.254.169.254/32 keycloak 168.63.129.16/32 fd00:ec2::254/128 169.254.169.254/32 guacd 168.63.129.16/32 fd00:ec2::254/128 169.254.169.254/32 tomcat 168.63.129.16/32 fd00:ec2::254/128 169.254.169.254/32 nginx 168.63.129.16/32 fd00:ec2::254/128 169.254.169.254/32

Every service is gated on /var/lib/sac/data/guacamole-keycloak.ready, which first boot writes only after this instance's database, configuration and certificate exist. Only root and the one service that needs them can read the files that hold secrets:

systemctl cat keycloak.service nginx.service | grep '^ConditionPathExists='
sudo stat -c '%a %U:%G %n' /root/guacamole-keycloak-credentials.txt /etc/guacamole/guacamole.properties /etc/keycloak/keycloak.env /etc/nginx/tls/server.key

ConditionPathExists=/var/lib/sac/data/guacamole-keycloak.ready ConditionPathExists=/var/lib/sac/data/guacamole-keycloak.ready 600 root:root /root/guacamole-keycloak-credentials.txt 640 root:tomcat /etc/guacamole/guacamole.properties 640 root:keycloak /etc/keycloak/keycloak.env 600 root:root /etc/nginx/tls/server.key