Guest Mode

Providing access to connections without authentication

Overview

In certain scenarios, it may be necessary to provide controlled and restricted internet access to users, such as students in an educational environment. This guide demonstrates how to achieve this using Keeper Connection Manager (KCM) with "Guest Mode" and remote browser isolation.

In this example implementation, we will configure web browsing access for users, limiting it to a predefined set of approved websites for students. Users will be presented with a custom "home page" that allows them to choose from these approved websites. This approach is particularly valuable in environments where full internet access is not permitted, such as classrooms or exam settings.

Example Site: https://guest-mode-demo.com

Guest Mode demo for Students

Using Keeper Connection Manager for this purpose offers significant advantages over traditional methods like firewall-based restrictions. These include:

• Session Monitoring: All browsing sessions can be fully recorded for auditing and accountability.

• Ease of Access: Users can connect seamlessly without requiring additional software on their devices.

• Device Agnostic: The version or type of browser on the user's device does not impact functionality.

• Enhanced Security: The device is shielded from data exfiltration, malicious sites, and potential manipulation through the use of isolated browsing sessions.

This guide provides step-by-step instructions for setting up this controlled browsing environment on a dedicated KCM instance, tailored to meet the needs of educational institutions and similar use cases.

Prerequisites

To set up Guest Mode, this guide assumes the following:

• You have installed KCM on an instance using the Auto Docker Install method as documented

• You have assigned a DNS name, set up SSL with Let's Encrypt or another method

• You're able to login to Keeper Connection Manager as guacadmin

In this example, we'll be setting up the demo site https://guest-mode-demo.com.

Activating Guest Mode

To activate the Guest Mode feature, follow the below steps.

• Build the Guest Mode Extension

• Configure Default Connection

• Modify Docker Compose

• Upload Extension Jar

• Update the Containers

Build the Guest Mode Extension

The guest mode source code for KCM is published at the below Github page:

GitHub - Keeper-Security/kcm-auth-guest: Authentication extension for demo KCM deployments.GitHub

Download the .zip or clone the Git repository to your workstation (or server).

Ensure you have a recent version of Java 17 installed:

$ java -version

openjdk version "17.0.13" 2024-10-15 LTS
OpenJDK Runtime Environment Corretto-17.......
OpenJDK 64-Bit Server VM Corretto-17......

If you don't have Java installed, we recommend using Amazon Corretto and following their installation instructions on your environment.

On the terminal, navigate to the repo location and build with Maven. If you don't have Maven installed, use this command (on a mac):

brew install maven

From the repo folder, build the Jar file:

mvn clean package

The resulting jar file will be published to the local folder structure:

[INFO] Building jar: /Path/to/kcm-auth-guest-main/target/kcm-auth-guest-1.5.2-2.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  22.350 s
[INFO] Finished at: 2025-01-19T07:58:48-08:00
[INFO] ------------------------------------------------------------------------

Save the package kcm-auth-guest-1.5.2-2.jar for the next steps.

Configure Default Connection

Login to Keeper Connection Manager as the "guacadmin" user, or any other admin user account.

Under Settings > Connections, create a Remote Browser Isolation connection.

Set up the Hostname with the URL of the landing page. In this case, we'll set it to https://lurey.com/demo.html. This page contains some basic HTML with links into the various allowed sites.

If session recording is desired, fill out the Recording Path with the value of ${HISTORY_PATH}/${HISTORY_UUID} and save the connection details.

Save the connection.

Next, create a Group called "guests" which is assigned to the connection.

Create "guests" group

In the Connections section, assign the group to the desired connection.

Assign the Demo Home Page to the "guests" group

Modify Docker Compose

Add the following changes to the guacamole section of your Docker Compose file located in /etc/kcm-setup/docker-compose.yml.

• Add ADDITIONAL_GUACAMOLE_PROPERTIES to the guacamole environment section.

• Change XX.XX.XX.XX to an IP address which will be considered "admin" and will be excluded from guest mode. This is used when changes are needed on the KCM configuration.

• Add the volume mount for the KCM Auth Guest plugin, built in the first step.

    guacamole:
        ...
        environment:
            ADDITIONAL_GUACAMOLE_PROPERTIES: "kcm-non-guest-networks:XX.XX.XX.XX"
        volumes:
            - "/etc/kcm-setup/kcm-auth-guest-1.5.2-2.jar:/etc/guacamole/extensions/kcm-auth-guest-1.5.2-2.jar:ro"

Note:

kcm-non-guest-networks represents a comma-separated list of all IP addresses and/or subnets (CIDR notation) that should not be considered guest users. If omitted, absolutely all users will be considered guest users.

If you don't want "guests" to be the default group name, this can be customized by adding another guacamole property called kcm-guest-group. If omitted, the default group name guests will be used.

Upload Extension Jar

Transfer the extension jar file kcm-auth-guest-1.5.2-2.jar built in step 1 above to the server in the folder /etc/kcm-setup/.

Update the Containers

To update the containers with this new configuration and extension:

sudo ./kcm-setup.run stop
sudo ./kcm-setup.run upgrade
sudo ./kcm-setup.run start

The service will start and begin serving the assigned connection to guest users.

Guest Mode also supports multiple connections assigned to the "guests" group. If multiple connections are assigned to the group, the user will be provided with a selection.

Optional: Start KCM on Reboot

This may not be necessary based on your Docker Compose file structure and Docker restart parameters. Adding the script below to a file called /etc/systemd/system/kcm.service will ensure that the service starts up on reboot.

[Unit]
Description=Keeper Connection Manager Service
After=network.target

[Service]
Type=oneshot
ExecStart=/bin/bash -c 'sudo /home/ec2-user/kcm-setup.run start'
WorkingDirectory=/home/ec2-user
RemainAfterExit=yes
User=ec2-user

[Install]
WantedBy=multi-user.target

Activate the service

sudo systemctl daemon-reload
sudo systemctl enable kcm
sudo systemctl start kcm
sudo systemctl status kcm