Skip to content

Installation of XoT-WebAccess component

1. Overview

The XoT-WebAccess is a solution enabling users to connect to protected devices using only their browser.

2. Prerequisites

2.1 Operating system and software

Web Client requires an XMS to function, so before installing the Web Client, make sure that an XMS is available and configure Keycloak according to the upcoming instructions.

A relatively fresh installation of Debian/Ubuntu Server with the latest security patches, e.g., Debian 12 or Ubuntu 24.04 LTS. On top of that, the following is required:

  • Node.js (version 22 or later)
  • Docker CE
  • OpenSSL

Note that Node.js will execute from a Systemd service using a webclient system user without a home directory, so Node.js must be installed globally on the system. A solution like Node Version Manager (nvm) will not work out of the box as it installs Node.js inside your user’s home directory, and a solution like Nodesource is advised.

2.2 Firewall

Two ports need to be exposed: 443 (HTTPS) and 80 (HTTP). In case Let's Encrypt certificates are not required, then port 80 can remain closed.

2.3 DNS & Email

A resolvable subdomain that will host the XoT-WebClient. Usually advised to look like webclient.${XMS-FQDN} for consistency, but since it is configurable (under etc/webclient/webclient.conf), it can be anything.

3. Installation

3.1 Xertified Package Repository

If the Xertified repository is not already set up on the server, it should be configured according to instructions found here

When the repo is configured, all that remains is to install the webclient package like: sudo apt install webclient

3.2 Configuration

The main configuration file is /etc/webclient/webclient.conf

  • WEBCLIENT_FQDN: Should be set to the appropriate DNS subdomain where the web client is accessible.
  • DESKTOP_CONTAINER, GUACAMOLE_APP_CONTAINER, GUACD_CONTAINER: Container images that are used
  • SESSION_TIMEOUT_MINUTES: Timeout for idle sessions in minutes, default 10 minutes. The session is terminated afterwards.
  • SESSION_COOKIE_SECRET1, SESSION_COOKIE_SECRET2: Secrets used to sign the backend's session cookies. Use strong random values.
  • XMS: Base URL for XMS
  • ISSUER: Issuer URL of the XMS Keycloak authorization instance
  • JWK_URL: JSON Web Key URL used to verify the tokens signed by the authorization server (XMS Keycloak).
  • REDIRECT_URI: URL where XMS Keycloak will redirect the users after a successful authentication
  • USER_CLIENT_ID: The client ID for user-level OIDC/OAUTH2 authentication
  • USER_CLIENT_SECRET: Secret for USER_CLIENT_ID
  • BACKEND_CLIENT_ID: The client ID for backend OIDC/OAUTH2 authentication.
  • BACKEND_CLIENT_SECRET: Secret for BACKEND_CLIENT_ID

3.3 Keycloak configuration

Two clients need to be added to Keycloak. One is used for logging in users that are accessing the XoT-WebClient, and one is used by XoT-WebClient itself to get access to the XMS API.

To add the clients, login to the Keycloak admin page for the XMS, and chose the xms realm. Then go to the clients page. Creation of the two clients are described in the following two subsections.

3.3.1 XoT-WebClient user client

To create the "user client", follow the steps below

  • Click the blue "Create Client" button on the clients page.
  • Leave Client type set to "OpenID Connect". Pick an appropriate Client ID, for example "webclient-user". Click Next.
  • On the Capability config page, enable Client authentication. Then unselect Direct Access Grants so that Standard flow is the only active authentication flow. Click Next.
  • On Login settings, add an entry to Valid redirect URIs. The entry should look like "https:///api/auth/callback", where webclient-hostname is the FQDN of the XoT-WebClient server. Then click Save.
  • In the Web Client configuration file, USER_CLIENT_ID corresponds to the "Client ID" chosen above, and USER_CLIENT_SECRET corresponds to the Client Secret found under the Credentials tab when looking at the client created above.

3.3.2 XoT-WebClient backend client

To create the "backend client", follow the steps below:

  • Click the blue "Create Client" button on the clients page.
  • Leave Client type set to "OpenID Connect".
  • Set Client ID to "webclient-backend". This exact name is currently required since XMS will check for this identical name. Click Next.
  • On the Capability config page, enable Client authentication. Then unselect both Standard flow and Direct Access Grants, and instead select Service accounts roles, so that is the only active authentication flow. Click Next.
  • On Login settings, leave the text fields empty. Click Save. In the Web Client configuration file, BACKEND_CLIENT_ID corresponds to the "Client ID" chosen above, and BACKEND_CLIENT_SECRET corresponds to the Client Secret found under the Credentials tab when looking at the client created above.

3.4 Download Docker images

Log in to the Xertified container registry (xertified.azurecr.io) and download the required Docker images. The Docker images needed are:

  • xertified.azurecr.io/webclient/xot-webclient-debian-12:1.0.7
  • xertified.azurecr.io/webclient/guacd:1.5.5
  • xertified.azurecr.io/webclient/guacamole-app:1.0.2

4. Start/stop Web Access Service

First step is to enable the service, so that it gets restarted after reboots: sudo systemctl enable webclient.service

4.1 Starting Traefik proxy

Afterwards, the Traefik proxy and load balancer need to be started. Switch to /usr/share/webclient/traefik/ and execute:

sudo /usr/share/webclient/traefik/run-traefik.sh --webclient-fqdn WEBACCESS-FQDN --email VALID_EMAIL_ACCOUNT

But if valid certificates are already available on the system and configured in the webclient.conf file, then it can be started like:

sudo /usr/share/webclient/traefik/run-traefik.sh --webclient-fqdn WEBACCESS-FQDN --no-letsencrypt

Further configuration options are available by just executing:

sudo /usr/share/webclient/traefik/run-traefik.sh

4.2 Starting XoT-WebClient

When Traefik is up and running successfully, then the XoT-WebClient service can finally be started:

sudo systemctl start webclient.service

If all has gone well, the status command should respond and report that all is good. sudo systemctl status webclient.service E.g:

  Loaded: loaded (/usr/lib/systemd/system/webclient.service; enabled; preset: enabled)
 Active: active (running) since Thu 2025-02-27 10:04:26 UTC; 2 weeks 1 day ago
Main PID: 776 (start.sh)
  Tasks: 12 (limit: 9440)
 Memory: 119.1M (peak: 120.5M)
    CPU: 37.845s
 CGroup: /system.slice/webclient.service
         ├─776 /bin/bash /usr/share/webclient/start.sh
         └─790 node /usr/share/webclient/app/index.js

5. Upgrading

When newer components are released into the container registry, either to introduce newer functionality or address issues, the process is as follows:

  • Pull the newer images, eg docker pull xertified.azurecr.io/webclient/guacamole-app:1.0.2
  • Update the configuration file '/etc/webclient/webclient.conf' with the correct image tag
  • Restart the service: sudo systemctl restart webclient.service