Keeper Connection Manager is packaged and installed in your environment. As such, backups should be taken in order to recover the environment if required.

Server Backup Instructions

• We recommend performing daily snapshots of your Keeper Connection Manager instances.

• In most installations, a database running locally includes the connection and user data. When backing up the instance, ensure that the database is included.

• When using the Advanced Linux Install method, ensure that the /etc/guacamole/ folder is included in the snapshot.

Database Snapshots

• Please use the database platform's backup features, for example mysqladmin on MySQL backed installs.

Starting with Keeper Connection Manager version 2.19, customers are required to obtain a license key from Keeper in order to continue the use of the application.

Obtaining a License Key

To obtain a license key, please contact Keeper Support directly at: https://www.keepersecurity.com/support.html

Upon request, Keeper Security staff will generate and send a copy of your license key.

Installation

To install your license key, you must provide the license as the sole contents of /etc/guacamole/kcm.license, which must be readable by the guacamole group.

cat "license_key_supplied_by_keeper" > /etc/guacamole/kcm.license
chmod 640 /etc/guacamole/kcm.license
chown root:guacamole /etc/guacamole/kcm.license

After adding the license key, restarting the service may be necessary.

sudo systemctl restart guacamole guacd

Overview

Keeper Connection Manager can be configured to authenticate users with any SAML 2.0 compatible identity provider. Users can be forced to login with SAML, or you can make SAML an optional login link from the home screen.

Instructions for popular Identity Providers is below.

What is Keeper Connection Manager?

Keeper Connection Manager ("KCM") is an agentless remote desktop gateway that provides IT Admins and DevOps with secure easy access to RDP, SSH, database and K8s endpoints through a web browser.

Benefits of the platform:

• Agentless

• Lightning Fast and Responsive

• Simple Access Controls

• Deployment options for cloud, on-prem and air-gapped environments

Features include:

• Support for RDP, SSH, VNC, K8s remote access protocols

• Support for MySQL, PostgreSQL, SQL Server database protocols

• Session Recording

• Privileged Session Management

• Multi-User Session Sharing

• Role-Based Access Controls

• Two-Factor Authentication

• SSO, OpenID Connect, Active Directory, LDAP Integration

• Custom Branding

Video Overview

System Diagram

The system architecture diagram is below.

Apache Guacamole

Keeper Connection Manager is the commercially-supported solution produced by the original creators of Apache Guacamole, the open source platform used by millions of people for accessing remote desktops. Keeper Connection Manager is built on top of the Guacamole gateway, with expanded capabilities, advanced integrations and ongoing feature development. Glyptodon was Acquired by Keeper Security in December 2021.

Getting Started

Ready to get started with Keeper Connection Manager? Proceed to the .

If multiple authentication methods are installed, Guacamole will poll each method as it attempts to authenticate users, and will retrieve connection data from each method once a user has successfully authenticated. This behavior is designed to allow authentication methods to work together, and can be leveraged to authenticate Guacamole users against LDAP while storing the connection data for those users within MySQL, PostgreSQL, or SQL Server.

Guacamole's definition of identity

When reading data from multiple authentication methods, Guacamole compares the unique identifiers of users (usernames) and groups to determine identity. This means that user accounts from different authentication systems will be automatically combined by Guacamole upon successful authentication as long as those user accounts have the same username, and group memberships will take effect across authentication systems so long as the unique names of those groups match.

If both LDAP and a database authentication method have been configured, Guacamole will automatically attempt to authenticate against both systems whenever a user attempts to log in. The LDAP account will be considered equivalent to the database user if the username is identical, and that user will have access to any data associated with them via the database, as well as any visible objects within the LDAP directory. If that user has permission to query their group memberships within LDAP, and Guacamole has been configured to query groups within LDAP, then the user's group membership will also be retrieved upon authentication, and the user will have access to any data associated with those groups via the database.

Administering LDAP users within Guacamole

Rather than having to manually look up users or groups within the LDAP directory, and then manually create those same users and groups within Guacamole, it is possible to set up administrative user accounts which can already see and manage available LDAP objects. This streamlines the administrative process, reducing the number of users which must be manually created to one.

To see LDAP objects within Guacamole’s administrative interface, one of the following tasks must be performed:

1. An administrative user within the Guacamole database, such as the default “guacadmin” user, must be manually created within LDAP with the same username and with sufficient privileges to query all Guacamole users and groups defined within LDAP.

2. An administrative user must be manually created within Guacamole having the same username as an LDAP user with sufficient privileges to query all Guacamole users and groups defined within LDAP.

Because a Guacamole user created as defined above would have access to LDAP users and groups, database users and groups, and database connections, all of this data will be unified within the same administrative interface within Guacamole. The user will be able to grant LDAP users and groups access to connections within the database to just as they would if only the database were in use.

Supported KCM Versions:

• Glyptodon 1.x - Full support for 2 years after any major release

• Glyptodon 2.x - Full support for 2 years after any major release

• Keeper Connection Manager 2.x - Full support for 2 years after any major release

Minimum system specs for production deployment:

Table with host recommendations:

For anything over 200 concurrent sessions, we have several options, and it may be best to talk through this with our sales engineering team to find the right solution based on your needs and connection types.

Disk space requirements

A single session recording can vary based on the content being shown. This is affected by the type of connection. GUIs typically have higher recording sizes versus CLI connections like SSH, which can be quite small.

Network throughput for concurrent connections

Network throughput also varies based on activity, type of session and connection settings. From actual examples, we've found that for a system running about 100 concurrent sessions, network traffic varies between 9Mbit/s and 15Mbit/s for all 100 connections. Each connection would be on average 1/100th of the 15Mbit value.

In the same above scenario with 100 connections, we would expect about 15gb total traffic per hour on the network adaptor. Comparing inbound and outbound traffic, just over 90% of the traffic is outbound from the server to the clients.

Preparing for Installation

Since you'll be accessing Keeper Connection Manager using a browser, we need to establish where to find it.

You'll need the following:

1. A designated machine (usually a Linux VM) 2. A fully-qualified domain name (FQDN) 3. Your DNS record set to point your FQDN to the IP of your designated machine 4. An SSL certificate (or generate one during installation) You can either bring your own SSL certificate, or you can generate one during the installation by choosing the option for Let's Encrypt. If planning to use Let's Encrypt, make sure that ports 80 and 443 are open to the internet during the installation.

To prepare for installation:

1. Create/Identify and establish root access to the server that will run the Keeper Connection Manager gateway

2. Decide if you want your KCM gateway to be public-facing (assign public IP), or internal-only (assign private IP)

3. Add a DNS A Record (or AAAA record) to point your domain to your KCM server's IP address

Check your firewall to make sure that traffic can flow between your server and Docker. Some domains that it will need to reach include docker.com, docker.io and others.

Platform-specific Setup

Virtual Machines

To check your that your linux system's entropy level is at least 1000, use the command:

$ cat /proc/sys/kernel/random/entropy_avail

To increase the speed of entropy generation, you can install the haveged service to ensure that the environment can efficiently create secure random numbers.

sudo yum install haveged
sudo systemctl start haveged
sudo systemctl enable haveged

sudo apt-get install haveged

sudo yum install epel-release
sudo yum install haveged
sudo systemctl start haveged
sudo systemctl enable haveged

RHEL / Rocky Linux 8 (and derivatives)

If Podman is installed, you must run the following two commands before installation:

sudo yum remove containerd
sudo yum remove runc

Keeper Connection Manager is installed as a gateway in your cloud, virtual or on-prem environment. There are several methods of deployment, and installation only takes a few minutes.

Install Methods

For Advanced Linux Install with package installations and custom configurations, we support Red Hat Enterprise Linux 7/8 and CentOS 7.

Configure DNS

In a production deployment, select a domain name to access the endpoint, e.g. kcm.company.com and create a new DNS record to map it to your server's public IP. You will be prompted to enter the domain name during the installation.

Ensure that the DNS record maps to your server's public IP address, or an IP that is internally available to your end-users over HTTPS port 443.

Decide on Let's Encrypt or Existing Cert

Keeper Connection Manager requires an SSL certificate for installation. Decide before starting installation if you want to use Let'sEncrypt, or if you have your own certificate file and private key.

LetsEncrypt is a certificate authority that is free, automated, open, and is also the world's largest CA. During installation using the Auto Docker Install method, Keeper Connection Manager will provide an option to utilize LetsEncrypt (option 1), which will generate a 3-month trusted certificate for your domain.

Advanced Linux Install

--> Installation Instructions for Advanced Linux Install

Keeper Connection Manager supports multiple authentication mechanisms which can be enabled through installing additional packages.

Advanced Linux Install Method

For Advanced Linux Install method, packages are available through the Keeper Connection Manager repository and automatically place the necessary Apache Guacamole extension within /etc/guacamole/extensions and any necessary dependencies (such as database drivers) within /etc/guacamole/lib.

The "Test Installation" using the user-mapping.xml file is meant as a quick means of verifying the functionality of Guacamole but is not supported for production deployments.

All authentication methods packaged listed below are production-ready:

• Authenticating users with LDAP

• Authenticating users with SAML 2.0

• Authenticating users with OpenID Connect

• Using Guacamole with a MySQL Database

• Using Guacamole with a PostgreSQL Database

• Using Guacamole with a SQL Server Database

Using a database like MySQL, PostgreSQL, or SQL Server enables additional features within Keeper Connection Manager, including connection sharing and a web-based administration interface. The LDAP authentication allows authentication to be provided through an LDAP directory such as OpenLDAP or Active Directory, and can be combined with a database, thus avoiding the need to store connections within the LDAP directory using schema modifications.

Multi-factor Authentication

If you wish to enable multi-factor authentication in front of Keeper Connection Manager, you may do so with Duo or TOTP. Multi-factor authentication is supported in front of any of the above production-ready authentication mechanisms, however keep in mind that a database is always required for TOTP:

• Using Duo for Multi-factor Authentication

• Using TOTP for Multi-factor Authentication

Important Note: MFA cannot be activated if the SAML authentication method is already active.

Keeper produces new minor releases of Keeper Connection Manager (1.1, 1.2, 1.3, etc.) roughly every 3 months following the first general availability release. Minor releases are updates to an existing major release which add new features and fix bugs, and will always maintain strict API compatibility. The details of upcoming and past releases can be found in the

Checking for updates

To check whether updates are available for Keeper Connection Manager packages without actually applying those updates, you can use the yum list updates command. Providing the "kcm-*" pattern to yum list updates restricts the packages checked to only those packages provided by Keeper Connection Manager:

If the above command lists one or more packages, then there are newer versions of Keeper Connection Manager packages available, and you should proceed with upgrading when a maintenance window permits.

Performing the upgrade

Stop Guacamole and guacd services

Before upgrading the Keeper Connection Manager packages, both Guacamole and guacd should be taken offline:

This is because:

• If both the Guacamole web application and one of its extensions are being updated, the package manager may update the web application first. The running Tomcat service may then redeploy and restart the web application before the extension is updated, resulting in inconsistency.

• If protocol support for guacd is being updated, older versions of that support may be cached by the system linker until the guacd service has been restarted.

• If the guacd service is being updated, those updates cannot take effect until the guacd service is restarted. The running process will continue to use the older, cached binary.

The system should remain stable if the upgrade is performed without stopping Tomcat and guacd, however it is best practice to do so. An upgrade to the web application will always result in the web application being restarted, and any updates being applied will likely not take effect until after services are restarted. With updates to the web application inherently causing a service restart, and updates in general requiring a service restart in order to take effect, it's best to plan this restart as a controlled part of the process.

Apply updates using yum

Once Tomcat and guacd are stopped, the Keeper Connection Manager packages can be upgraded using the yum utility, just like the other packages in the system. The upgrade can be restricted to only Keeper Connection Manager packages by specifying the "kcm-*" pattern:

Start the Guacamole and guacd services

After yum upgrade completes, the system has been updated and it is safe to start Guacamole and guacd back up:

Keeper Connection Manager provides support for Duo as a second authentication factor, automatically verifying user identity with Duo after the user is initially authenticated. To make use of Duo support, some other authentication mechanism will need be configured, as well, such as MySQL, PostgreSQL, or LDAP. Only once authentication has succeeded through another installed method will Duo be used to verify the identity of the user.

Installing Duo support for Guacamole

Keeper Connection Manager packages Guacamole’s Duo support within the kcm-guacamole-auth-duo package:

$ sudo yum install kcm-guacamole-auth-duo

The Guacamole-side installation of Duo support within Keeper Connection Manager consists solely of the kcm-guacamole-auth-duo package. Nothing else needs to be installed except for Guacamole itself and some other means of authentication. If Guacamole has not yet been installed and confirmed to work with some other authentication method, that should be done first before attempting to set up Duo.

Registering Guacamole with Duo

For Duo to be integrated with any application, that specific instance of the application must first be registered with the Duo service. Duo does not provide a specific integration option for Guacamole, but Guacamole’s Duo support uses Duo’s generic authentication API which they refer to as the “Web SDK”. To use your Guacamole deployment with Duo, you will need to add it to your Duo account as a new “Web SDK” application from within the “Applications” tab of the admin panel.

Once this has been done, Duo will expose several properties specific to your Guacamole deployment: the integration key, secret key, and API hostname. These values can be found within the application’s “Details” section in your Duo account, and will need to be copied into /etc/guacamole/guacamole.properties:

$ sudo vi /etc/guacamole/guacamole.properties

The relevant properties can be found in the “DUO-1” section:

##
## [DUO-1] Duo application integration details
##
## The API hostname, integration key, and secret key provided for you by Duo
## when you registered Guacamole in Duo's "Admin" panel. Each of these values
## is required and is generated by Duo.
##

#duo-api-hostname:    XXXXXXXX.duosecurity.com
#duo-integration-key: 0123456789ABCDEF0123
#duo-secret-key:      0123456789ABCDEF0123

Generating the application key

The Duo “Web SDK” requires that an arbitrary and random key be generated for each application. This key resides strictly on the side of the application, and is not registered with Duo.

Any random value containing at least 40 characters will suffice. To quickly grab 40 random characters from /dev/random:

$ tr -dc 'a-zA-Z0-9' < /dev/random | head -c40; echo
xqZKJODwg7ouwxdqU9hvuaWhE6lQFspijY0ofg8I
$

This value must then be copied within the duo-application-key property, which can be found in the "DUO-2" section of guacamole.properties:

##
## [DUO-2] Duo application key
##
## An arbitrary and random key to use when communicating with the Duo service.
## This key MUST be manually generated, and MUST BE AT LEAST 40 CHARACTERS.
##

#duo-application-key: abcdefghijklmnopqrstuvwxyz0123456789ABCD

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

$ sudo systemctl restart tomcat

Installing OpenID Connect support for Guacamole

Keeper Connection Manager packages Guacamole’s OpenId Connect support within the kcm-guacamole-auth-sso-openid package:

Connecting Guacamole to OpenID Connect

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the OpenID Connect installation:

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “OPENID-1” and defines the IdP configuration. Uncomment the properties in this section and edit them according to your identity provider setup.

The second section contains the Keeper Connection Manager server information that is used by the IdP.

The 3rd section contains the OpenID Connect identity mappings.

The 4th section contains optional parameters that can be set.

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

Keeper Connection Manager provides support for TOTP as a second authentication factor, verifying the identities of enrolled users using authentication codes generated with the TOTP standard. To make use of TOTP support, a database authentication mechanism will need be configured, as well, such as or . Only once authentication has succeeded through another installed method will TOTP be used to verify the identity of the user, and a database is specifically required for storage of the key that Guacamole and the user's authentication device will use to generate authentication codes.

Installing TOTP support for Keeper Connection Manager and Guacamole

Keeper Connection Manager packages Guacamole’s TOTP support within the kcm-guacamole-auth-totp package:

The Guacamole-side installation of TOTP support within Keeper Connection Manager consists solely of the kcm-guacamole-auth-totp package. Nothing else needs to be installed except for Guacamole itself and some other means of authentication. If Guacamole has not yet been installed and confirmed to work with a database authentication method, that should be done first before attempting to set up TOTP.

Unlike most other extensions, no additional configuration information is typically needed for the TOTP support to work. All configurable values have defaults which are accepted by widely used TOTP implementations like Google Authenticator. You will only need to specify additional configuration information if your authentication devices differ from these defaults:

If the above are acceptable, then no configuration changes need to be made and you should proceed to the section below. If any of the above need to be changed, you will need to edit /etc/guacamole/guacamole.properties to specify the appropriate values. These properties are documented separately in detail:

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

After TOTP support has been installed and Guacamole has been restarted, only users that exist within the database will automatically be enrolled in TOTP. Valid users that exist only outside the database will be able to log in, but will not be automatically enrolled with TOTP.

If you are and want to require all users to use TOTP, you should be sure to set the corresponding property within /etc/guacamole/guacamole.properties to enforce existence of database accounts for all logins. Each supported database has its own variant of this property:

This is particularly important if the database's concept of identity may differ from your LDAP server's concept of identity. For example, usernames within PostgreSQL are case-sensitive, but usernames within Active Directory typically are not.

SSL termination is the recommended method of encrypting communication between users’ browsers and Guacamole, and involves configuring a reverse proxy like Nginx or Apache to handle strictly the SSL/TLS portion of the conversation with the Tomcat instance hosting Guacamole, handling encrypted HTTP externally while passing unencrypted HTTP to Tomcat internally.

Proxying Guacamole through Apache

If Apache has been configured for SSL/TLS, there should be a <VirtualHost> section within this configuration that defines the certificate and private key used by Apache, and which requires Apache to listen on the standard HTTPS port (443). To proxy Guacamole through Apache such that Guacamole communication is encrypted, two additional <Location> sections will need to be added within this <VirtualHost> section:

<Location />
    Order allow,deny
    Allow from all
    ProxyPass http://HOSTNAME:8080/ flushpackets=on
    ProxyPassReverse http://HOSTNAME:8080/
</Location>

<Location /websocket-tunnel>
    Order allow,deny
    Allow from all
    ProxyPass ws://HOSTNAME:8080/websocket-tunnel
    ProxyPassReverse ws://HOSTNAME:8080/websocket-tunnel
</Location>

where “HOSTNAME” is the hostname or IP address of the internal Guacamole server.

These <Location> sections configure proxying of the HTTP and WebSocket protocols respectively. Apache handles the HTTP and WebSocket protocols separately, and thus requires separate configuration for the portion of the web application which uses WebSocket. Both sections are required for Guacamole to work correctly behind Apache, and the mod_proxy_wstunnel module must be installed and enabled.

Of particular importance is the flushpackets=on option within the ProxyPass directive used for HTTP in front of Guacamole. This option disables buffering of packets sent to/from Guacamole. By default, Apache will buffer communication between itself and the browser, effectively disrupting the stream of events and updates required for remote desktop. Without disabling buffering, the Guacamole connection will at best be slow, and at worst not function at all.

Applying the updated Apache configuration

After the above changes have been made, Apache must be reloaded to force rereading of its configuration files:

$ sudo systemctl reload httpd

If you are using SELinux (the default on both CentOS and RHEL), you must also configure SELinux to allow HTTPD implementations like Apache to establish network connections:

$ sudo setsebool -P httpd_can_network_connect 1

If Guacamole is not accessible through Apache after the service has been reloaded, check the Apache logs and/or journalctl to verify that the syntax of your configuration changes is correct. Such errors will result in Apache refusing to reload its configuration, or refusing to start up entirely. If you do not see any errors from Apache, verify that you have configured SELinux to allow Apache to connect to the network and check the SELinux audit logs (/var/log/audit/audit.log) for AVC denials.

Configuring Tomcat to trust "X-Forwarded-For" from Apache (manual deployment only)

For the client address sent by Apache via "X-Forwarded-For" to be correctly trusted as the true client address, you will need to add a "RemoteIpValve" entry within /etc/tomcat/server.xml. If this is not specified, the client address will be logged as the address of the internal proxy, which is not usually desirable.

$ sudo cp /opt/keeper/share/guacamole/server.xml /etc/tomcat/

<Valve className="org.apache.catalina.valves.RemoteIpValve"/>

        ...

        <Valve className="org.apache.catalina.valves.RemoteIpValve"/>

      </Host>
    </Engine>
  </Service>
</Server>

<Valve className="org.apache.catalina.valves.RemoteIpValve"
       internalProxies="127\.\d{1,3}\.\d{1,3}\.\d{1,3}|0:0:0:0:0:0:0:1|::1"/>

Applying the updated Tomcat configuration

Once an appropriate RemoteIpValve has been specified, Tomcat must be restarted to force rereading of server.xml:

$ sudo systemctl restart tomcat

Overview

The Keeper Connection Manager home screen provides quick access to any connection that you have been granted access to.

If you have access to multiple connections, you will be taken to the dashboard where all available connections are listed. If you only have access to a single connection, you will be routed directly to that connection.

My Connections

The home screen contains a list of all connections to which you have access, along with thumbnails of any recently used or active connections. Thumbnail images update dynamically while a machine is being accessed. If you have access to a large number of connections and wish to quickly locate a specific connection, you can also enter search terms within the “Filter” field to filter the list of connections by name.

Clicking on any connection will open that connection within the current window or tab, but multiple connections can be used simultaneously.

Each connection you use will remain active until explicitly disconnected, or until you navigate away from Keeper Connection Manager entirely. Active connections can be seen as thumbnails updating in real-time on the home screen.

User Menu

With the exception of the client connection screen, all Keeper Connection Manager screens contain a menu in the upper-right corner called the “user menu”. This menu displays your username and contains several options which depend on your level of access.

Home

Navigates back to the home screen, if you are not already there. If you only have access to one connection, this will be replaced with a link to that connection.

Settings

Navigates to the settings interface, which provides the core Administrative functions (if you have rights to access this area) and and user preferences such as display language.

Logout

Logs out of Keeper Connection Manager completely, closing all current connections and ending the Keeper Connection Manager session.

Release notes are published at Keeper's Release Notes portal.

-> Keeper Connection Manager Release Notes

Client Certificate Overview

To implement device-based access security with Keeper Connection Manager, this can be accomplished using NGINX client certificates. A client certificate is installed into the web browser of your user's approved devices, and the server will only accept communication from a device with the client certificate installed.

The steps to activate this advanced level of protection is described in the steps below.

(1) Create a Certificate Authority (CA) Key

Generate a CA Key with a strong auto-generated passphrase. Make sure to store the passphrase in your Keeper vault.

(2) Create a CA Certificate

A certificate is created with the CA Key. When answering the questions, you can leave the Common Name and Email empty. Save the information that you entered for Country, State, Locality, and Organization, because you may need these later when renewing the certificate.

Side Note: to analyze the certificate parameters, you can run the below command.

(3) Create a Client Key

For the end-user devices, a client key must be generated. You can decide if you would like to generate one key for all devices, or each user can generate their own key and request a certificate. The process is up to you. Generate a client key with a strong auto-generated passphrase. Make sure to store the passphrase in your Keeper vault.

(4) Create a CSR

For each Client Key, generate a CSR to create a signed certificate.

(5) Sign the CSR with the CA Key

You'll need to enter the CA passphrase from Step 1 to sign the request.

At this point, you now have a signed Client Certificate (client.crt).

(6) Convert the Client Certificate to PKCS#12

To import the certificate into a web browser, a pfx file in PKCS#12 is typically required. Generate the client.pfx file using the command below. A passphrase will be required. This passphrase will be provided to each of the users who need to install the certificate, so it should be used specifically for this purpose.

(7) Add to NGINX Config

Add the below line to your Keeper Connection Manager NGINX configuration file to block access without a certificate. Make sure to upload the CA certificate to the folder path designated.

In the Location block, add this section to send the user a 403 error if the client cert is not installed:

Make sure that the ca.crt file is located in a folder that NGINX can access.

After updating the configuration, restart NGINX.

(8) Test the configuration

Before installing the client certificate on the user's machine, load up the Keeper Connection Manager login screen to ensure that a 403 error is sent:

(9) Install the Client Certificate

For each end-user client device that will need access to Keeper Connection Manager, you will need to install the client certificate into the user's browser or machine. The installation of client certificates varies by platform.

On Windows

Double-click or right-click the client certificate (client.pfx) from Step 6 and enter the client certificate passphrase.

Restart the browser.

The next time Keeper Connection Manager is loaded, you can approve the certificate.

On Mac OS - Chrome

Import the client.pfx file by double-clicking or loading into the Keychain login Certificates section. In the "Trust" section of the certificate, mark as Always Trust.

Restart the browser and load the Keeper Connection Manager login screen to select the certificate.

On Mac OS - Firefox

Open Firefox > Preferences > search for Certificates and select Your Certificates tab. Click "Import" and select the client.pfx certificate file. Complete the import.

After successful import, the Keeper Connection Manager login screen will load.

Troubleshooting

After setting up the client certificate configuration, the following errors are common.

If NGINX fails to start, journalctl -xe might show something like "Permission denied:fopen('/path/to/ca.crt','r'). This might occur if the folder permissions and file permissions are not set properly.

If the folder and file permissions are set properly and you're still receiving this error, the restorecon command will repair the SELinux security context for the file:

SSL termination is the recommended method of encrypting communication between users’ browsers and Guacamole, and involves configuring a reverse proxy like Nginx orto handle strictly the SSL/TLS portion of the conversation with the Tomcat instance hosting Guacamole, handling encrypted HTTP externally while passing unencrypted HTTP to Tomcat internally.

Proxying Guacamole through NGINX

If Nginx has been configured for SSL/TLS, there should be a server section within this configuration that defines the certificate and private key used by Nginx, and which requires Nginx to listen on the standard HTTPS port (443). To proxy Guacamole through Nginx such that Guacamole communication is encrypted, a new location section will need to be added within this server section:

where “HOSTNAME” is the hostname or IP address of the internal Guacamole server. This can also be replaced with "http://127.0.0.1:8080" in most cases.

While a typical proxy configuration for Nginx may only specify the proxy_pass and proxy_http_version directives, Guacamole requires additional configuration due to the nature of the application:

• proxy_buffering off disables buffering of packets sent to/from Guacamole. By default, Nginx will buffer communication between itself and the browser, effectively disrupting the stream of events and updates required for remote desktop. Without disabling buffering, the Guacamole connection will at best be slow, and at worst not function at all.

• The X-Forwarded-For header must be explicitly set to ensure that the IP addresses logged by Guacamole are correct. Without explicitly adding this header (and), all connections will appear to come from the NGINX server.

• The Upgrade and Connection headers are required parts of the WebSocket protocol. If omitted, WebSocket will not function correctly, and Guacamole will fall back to HTTP streaming, which is less efficient.

Applying the updated NGINX configuration

After the above changes have been made, NGINX must be reloaded to force rereading of its configuration files:

If you are using SELinux (the default on both CentOS and RHEL), you must also configure SELinux to allow HTTPD implementations like Nginx to establish network connections:

If Guacamole is not accessible through NGINX after the service has been reloaded, check the NGINX logs and/or journalctl to verify that the syntax of your configuration changes is correct. Such errors will result in NGINX refusing to reload its configuration, or refusing to start up entirely. If you do not see any errors from NGINX, verify that you have configured SELinux to allow NGINX to connect to the network and check the SELinux audit logs (/var/log/audit/audit.log) for .

Configuring Tomcat to trust "X-Forwarded-For" from NGINX (manual deployment only)

For the client address sent by NGINX via "X-Forwarded-For" to be correctly trusted as the true client address, you will need to add a "" entry within /etc/tomcat/server.xml. If this is not specified, the client address will be logged as the address of the internal proxy, which is not usually desirable.

Applying the updated Tomcat configuration

Once an appropriate RemoteIpValve has been specified, Tomcat must be restarted to force rereading of server.xml:

Overview

Keeper Connection Manager allows users to share access to their connection session with a URL. This allows for easy sharing of a connection session among teams, or sharing of connections to people without Keeper Connection Manager accounts.

Create a Sharing Profile

The first step to connection sharing is to create a Sharing Profile. This needs to be made for each connection that will be shared.

To create a sharing profile, head to the "Connection" tab of the Settings menu and click the arrow next to the connection you would like to add a sharing profile to.

You will see a list of all the sharing profiles created for this connection, click "New Sharing Profile" to create a new profile, or click an existing sharing profile to edit it.

The Sharing Profile form will open. Fill in the name and options to configure the sharing profile.

Click "Save" to create the sharing profile.

Sharing Connections

To initiate a connection share, from within a connection session first open the connection menu using Ctrl+Shift+Win (Ctrl+Shift+Cmd for Mac). When at least one sharing profile exists for the connection, the "Sharing" menu will appear next to the user's name.

Click "Sharing" to see a list of the sharing profiles for this connection.

Select which profile to use and click it to create a sharing URL which can be shared to give anyone access to this connection session.

When someone without an account in this Keeper Connection Manager system connections to the session, they will have full access to the connection (unless "Read Only" was selected in the sharing profile settings) however they will not have a user menu, or sharing menu.

Overview

Keeper Secrets Manager integrates with Keeper Connection Manager to provide dynamic retrieval of credentials that are stored in the Keeper Vault. This integration allows the Admin to provide privileged sessions with credentials that are stored and protected in the encrypted Keeper vault.

Using , Keeper Connection Manager can securely access RDP, SSH, MySQL, VNC and other credentials from the Keeper Vault. With this integration, connection credentials are protected in the encrypted Keeper vault and never stored in plain text. In the connection properties, you can simply reference the hostname or specified Vault record identifier and Keeper will pull the necessary credentials at runtime. Access credentials are never exposed to the user.

Integration Features

• Securely store connection secrets like SSH keys and Admin passwords in your Keeper Vault

• Dynamically pull credentials from Keeper on-demand when establishing connections

• Eliminate hard-coded credentials and secrets

• Securely store guacamole properties in the Keeper Vault such as MySQL passwords

UDS Enterprise deployment details

When leveraging Keeper Connection Manager to fulfill a request to remotely access a virtual machine, UDS Enterprise will generate and send a temporary access token to Keeper Connection Manager. This temporary access token defines the connection details of the machine being accessed and needs to be validated against UDS Enterprise for that access to be granted. In order to reach out to UDS Enterprise to perform this validation, Keeper Connection Manager needs to know the base URL of the UDS Enterprise deployment.

The URL provided need only be a URL that your Keeper Connection Manager server can use to reach your UDS Enterprise server. If UDS Enterprise is installed on the same private network or on the same server as Keeper Connection Manager, this can be an internal URL that uses a private IP address or domain name, and does not necessarily need to be the public URL that would be used to access UDS Enterprise over the internet.

Duo application integration details

The API hostname, integration key, and secret key are provided for you by Duo when you registered Guacamole within Duo's "Admin" panel. Each of these values is required and is generated by Duo.

Duo application key

An arbitrary and random key must be provided for communicating with the Duo service. This key MUST be manually generated and MUST BE AT LEAST 40 CHARACTERS.

Any random value containing at least 40 characters will suffice. To quickly grab 40 random characters from /dev/random:

Shared JSON secret key

A shared secret key is used by systems generating JSON data to encrypt and sign the JSON, and by the Guacamole server to verify and decrypt received data. This key must be 128 bits, specified with 32 hexadecimal digits.

This key can be essentially anything as long as it is unpredictable. An easy way of generating such a key is to echo a passphrase through the "md5sum" utility. This is the technique OpenSSL itself uses to generate 128-bit keys from passphrases. For example:

Source network restrictions

By default, received encrypted JSON will be accepted as long as it is valid and properly signed with the secret key. This can be further restricted to accept encrypted JSON only from machines which match a comma-separated list of trusted IP addresses and/or CIDR subnets.

CentOS and RHEL both provide a package for the MariaDB database server called "mariadb-server". Installing this package will install a version of MariaDB that is. If you do not have an existing database instance or third-party database hosting provider that you would prefer to use, installing a fresh instance of MariaDB for use by Guacamole will work nicely:

As with other standard CentOS / RHEL packages providing a service, the MariaDB service will not be started by default after the "mariadb-server" package is installed. It must be started manually, and then configured to automatically start if the system is rebooted:

Dropping default anonymous users

If MariaDB is installed locally (on the same server as Apache Guacamole), its default configuration will prevent Guacamole from authenticating. This is due to the way that MariaDB handles authentication and anonymous database users: if an anonymous user is defined for the same hostname/address, MariaDB will use only the anonymous user, and authentication using a non-anonymous user and password from the same hostname/address will fail.

This can be checked by querying MariaDB's user table directly:

Any users with empty usernames in the results of the above query are anonymous users which may block authentication from succeeding:

Dropping those users should allow non-anonymous authentication from those same hosts to succeed:

Pointing Guacamole at the new MariaDB instance

Once MariaDB has been deployed, you should move forward with . This process is documented in its entirety, and the default /etc/guacamole/guacamole.properties file also contains placeholders and comments to help guide administrators to the correct configuration properties. Overall, the process will involve:

• Installing the package providing MySQL / MariaDB support (kcm-guacamole-auth-jdbc-mysql).

• Creating a new database within your MariaDB instance using the provided schema files.

• Creating a database user that Guacamole can use to execute queries against your database.

• Editing /etc/guacamole/guacamole.properties to point Guacamole at your database (and to specify the credentials of the database user it should use).

Keeper Connection Manager provides access to the functionality of a desktop from within your web browser. The interface is designed to be as seamless and unobtrusive as possible.

Selecting connections and user settings.

Features and functionality of the connection session and the sidebar menu.

Manage the clipboard, view multiple connections at once, upload or download files, and change input settings within a connection session

How to create Keeper Connection Manager connections for each supported protocol type

Configure and use Keeper Connection Manager drag-and-drop file transfer

Share access to Keeper Connection Manager connections with anyone with an internet browser

How to configure screen and keystroke recording for all session types.

Data can be imported to a MySQL connection from a file on your machine, or exported and downloaded to you machine.

Import

Import data from a file on your machine into the MySQL connection.

To import data from a csv file, is the LOAD DATA MySQL command:

In the example above, "<table>" should be replaced with the SQL table to import data into. The other parts of the command are required for CSV-formatted files. If your uploaded file uses different termination characters update the query accordingly.

After running the query, Keeper Connection Manager will prompt you to supply the data file. To upload the file, simply drag and drop it from your machine onto the browser window.

Export

Data from the connected MySQL database can be exported to a file on your machine. To do this, use the following query:

The result of the given <query> will be put into a CSV file with the given name and downloaded from the browser to your machine.

Data can be imported to a SQL Server connection from a file on your machine, or exported and downloaded to you machine.

Import

Import data from a file on your machine into the SQL Server connection.

To import data from a csv file, is the COPY command:

In the example above, "<table>" should be replaced with the SQL table to import data into. The other parts of the command are required for CSV-formatted files. If your uploaded file uses different termination characters update the query accordingly.

After running the query, Keeper Connection Manager will prompt you to supply the data file. To upload the file, simply drag and drop it from your machine onto the browser window.

Export

Data from the connected PostgreSQL database can be exported to a file on your machine. To do this, use the following query:

The result of the given <query> will be put into a CSV file with the given name and downloaded from the browser to your machine.

Data can be imported to a PostgreSQL connection from a file on your machine, or exported and downloaded to you machine.

Import

Import data from a file on your machine into the PostgreSQL connection.

To import data from a csv file, is the COPY command:

In the example above, "<table>" should be replaced with the SQL table to import data into. The other parts of the command are required for CSV-formatted files. If your uploaded file uses different termination characters update the query accordingly.

After running the query, Keeper Connection Manager will prompt you to supply the data file. To upload the file, simply drag and drop it from your machine onto the browser window.

Export

Data from the connected PostgreSQL database can be exported to a file on your machine. To do this, use the following query:

The result of the given <query> will be put into a CSV file with the given name and downloaded from the browser to your machine.

Defining the guacConfigGroup object class

When connection data is stored within your LDAP directory, each connection is represented by a special type of LDAP group, and permissions related to Guacamole connections can be managed directly with LDAP based on user membership of these groups. Doing this requires schema modifications which add a new object class called guacConfigGroup.

An LDIF file defining the schema changes in a manner compatible with OpenLDAP is provided by the kcm-guacamole-auth-ldap package within /opt/keeper/share/guacamole-auth-ldap/schema/guacConfigGroup.ldif. This file can be applied to your OpenLDAP server using the “ldapadd” command:

$ sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f /opt/keeper/share/guacamole-auth-ldap/schema/guacConfigGroup.ldif

Once this is done, connections can be defined by creating new guacConfigGroup objects within the LDAP directory. Each guacConfigGroup accepts a single guacConfigProtocol attribute, defining the protocol associated with the connection, and any number of guacConfigParameter attributes, each defining a connection parameter name/value pair. Users that should have access to the connection must be added as members of the guacConfigGroup using the member attribute.

For example, a connection accessible to two users which uses VNC to connect to localhost at port 5900 with the password “secret” could be defined with the following LDIF file:

dn: cn=Example Connection,ou=groups,dc=example,dc=net
objectClass: guacConfigGroup
objectClass: groupOfNames
cn: Example Connection
guacConfigProtocol: vnc
guacConfigParameter: hostname=localhost
guacConfigParameter: port=5900
guacConfigParameter: password=secret
member: cn=user1,ou=people,dc=example,dc=net
member: cn=user2,ou=people,dc=example,dc=net

Configuring Guacamole to read connections from LDAP

Auto Docker And Docker Compose Install Methods:

To read connection data from LDAP, Guacamole’s main configuration file, modify the /etc/kcm-setup/docker-compose.yml file.

The base DN of all connections defined within LDAP must be specified using the LDAP_CONFIG_BASE_DN property. This base DN should be the DN of the portion of the LDAP directory whose subtree contains all Guacamole connections accessible via LDAP. Only connections defined within the subtree of this base DN will be visible:

   guacamole:
        image: keeper/guacamole:2
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            MYSQL_HOSTNAME: "db"
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            MYSQL_PASSWORD: "xxxxxxx"
            
            # LDAP Connection
            LDAP_HOSTNAME: "localhost"
            LDAP_PORT: 389
            LDAP_ENCRYPTION_METHOD: "none"
            ADDITIONAL_GUACAMOLE_PROPERTIES: "extension-priority: *, ldap"
            
            ## Optional Settings ##
            # Read Connections from LDAP
            LDAP_CONFIG_BASE_DN: "ou=connections,dc=example,dc=net"

Advanced Linux Install Method:

To read connection data from LDAP, Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to define the subtree containing these connections:

$ sudo vi /etc/guacamole/guacamole.properties

The base DN of all connections defined within LDAP must be specified using the ldap-config-base-dn property. This base DN should be the DN of the portion of the LDAP directory whose subtree contains all Guacamole connections accessible via LDAP. Only connections defined within the subtree of this base DN will be visible:

##
## [LDAP-4] LDAP base DN for Guacamole connections ("guacConfigGroup")
##
## The base DN for all Guacamole connections defined directly within the LDAP
## directory using "guacConfigGroup" objects. If connections will not be stored
## within the directory, this property is unnecessary.
##
## If the kcm-guacamole-auth-ldap package has been installed, the LDAP
## schema for "guacConfigGroup" objects can be found at:
##
##   /usr/share/guacamole-auth-ldap/schema/guacConfigGroup.ldif
##
## Alternatively, if your LDAP directory does not accept LDIF files, the schema
## source for "guacConfigGroup" can be found at:
##
##   /usr/share/guacamole-auth-ldap/schema/guacConfigGroup.schema
##

#ldap-config-base-dn: ou=connections,dc=example,dc=net

Controlling access using group membership

Auto Docker and Docker Compose Install Method

To control group membership using LDAP, modify the /etc/kcm-setup/docker-compose.yml file.

It is also possible grant entire groups access to connections using the seeAlso attribute. This attribute is a standard LDAP attribute, and will be taken into account by Guacamole if the LDAP_GROUP_BASE_DN property is defined. This property defines the root of the subtree containing all groups which may apply to Guacamole users authenticated using LDAP:

  guacamole:
        image: keeper/guacamole:2
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            MYSQL_HOSTNAME: "db"
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            MYSQL_PASSWORD: "xxxxxxx"
            
            # LDAP Connection
            LDAP_HOSTNAME: "localhost"
            LDAP_PORT: 389
            LDAP_ENCRYPTION_METHOD: "none"
            ADDITIONAL_GUACAMOLE_PROPERTIES: "extension-priority: *, ldap"
            
            ## Optional Settings ##
            # Mapping Guacamole groups to LDAP DN's
            LDAP_GROUP_BASE_DN: "ou=groups,dc=example,dc=net"
            LDAP_GROUP_NAME_ATTRIBUTE: "cn"

Advanced Linux Install Method

It is also possible grant entire groups access to connections using the seeAlso attribute. This attribute is a standard LDAP attribute, and will be taken into account by Guacamole if the ldap-group-base-dn property is defined. This property defines the root of the subtree containing all groups which may apply to Guacamole users authenticated using LDAP:

##
## [LDAP-5] LDAP group / group DN description
##
## The base DN of all Guacamole groups within the LDAP directory, and the
## attribute which should be used by Guacamole to uniquely identify the
## group.
##
## If connections are being stored within LDAP using "guacConfigGroup" objects,
## and you wish to control access to these connections via LDAP groups, this is
## accomplished using the standard "seeAlso" attribute and the
## ldap-group-base-dn property is required.
##
## If connections are being stored outside of LDAP, such as within a database,
## and you wish to control access using LDAP groups, both ldap-group-base-dn
## and ldap-group-name-attribute will be required. The group membership of a
## user cannot be queried without a base DN, and the unique name to be used by
## other parts of Guacamole to represent the group cannot be determined without
## the name attribute.
##

#ldap-group-base-dn:        ou=groups,dc=example,dc=net
#ldap-group-name-attribute: cn

Completing installation

Changes to Guacamole’s LDAP configuration will generally only be reread from guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

Advanced Linux Install Method

$ sudo systemctl restart guacamole

$ sudo systemctl restart tomcat

As of KCM version 2.9.6, KCM can be configured to limit a user's ability to login after multiple consecutive failed login attempts. This blocks brute-force login attacks on KCM instances.

Use the following properties to change the login attempt settings

Google Workspace Configuration

The first step regardless of installation method is to configure your SAML 2.0 identity provider using Google Workspace.

(1) Login to Google Workspace at https://admin.google.com****

Visit the Apps > Web and Mobile Apps screen.

(2) Select "Add App" and select "Add Custom SAML App".

Enter an application name and description. You can also upload a Keeper Connection Manager logo. The image logo is here:

Click Continue.

(3) Download the metadata.xml file

...and then click Continue

(4) Configure the SAML Settings

Update 3 fields: ACS URL, Entity ID and Name ID format.

• The ACS URL needs to start with your Keeper Connection Manager domain followed by "/api/ext/saml/callback".

• The Entity ID is just the Keeper Connection Manager domain.

• The Name ID format must be EMAIL

Click Continue.

(5) Assign group membership (Optional)

You can now assign Group Membership to the Keeper Connection Manager application, which is optional. If you would like to assign a group, make sure that the "App Attribute" is groups (lowercase). Then click FINISH.

(6) Enable Access

After creating the SAML app, it is not yet active for all users. To enable access, click on View details and turn the application ON.

The Google Workspace side of the setup is complete. Note if you change anything, you need to re-download a new metadata.xml file.

Next: KCM Configuration

Advanced Linux Install Method

If you have installed Keeper Connection Manager using the advanced linux install method, setting up SAML can be performed following the steps below.

Installing SAML support for Guacamole

Keeper Connection Manager packages Guacamole’s SAML support within the kcm-guacamole-auth-sso-saml package:

$ sudo yum install kcm-guacamole-auth-sso-saml

Connecting Guacamole to SAML

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the SAML installation:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “SAML-1” and defines the IdP configuration. Uncomment the saml-idp-metadata-url and saml-entity-id property. You'll need to reference the IdP's metadata file and Entity ID.

##
## [SAML-1] Identity provider details
##
## The details of the identity provider (IdP) that Guacamole should use for
## authentication. These properties dictate how Guacamole should communicate
## with the IdP, including the how users should be redirected for
## authentication by the IdP.
##
## The SAML IdP will typically provide this information in advance in the form
## of an XML file. If no such XML file is provided, or if information is
## missing from that XML file, additional properties will need to be specified
## to provide that information.
##
## The key pieces of information required are:
##
##  * The URL of the SAML endpoint used by the IdP.
##  * The "entity ID" that should be used by Guacamole to identify itself with
##    the IdP.
##
## If the SAML IdP provides an XML metadata file, it is unusual for that file
## to not contain both of the above pieces of information.
##
## THIS INFORMATION IS REQUIRED if the SAML extension will be used.
##

saml-idp-metadata-url: file:///etc/guacamole/metadata.xml
saml-entity-id: https://demo3.lurey.com

The second section contains the callback URL that is used by the IdP. This is typically set to the user-facing URL of the Keeper Connection Manager service.

##
## [SAML-2] Guacamole server details
##
## The details of the Guacamole server that should be provided to the SAML IdP
## when authenticating the user. This information defines how the SAML IdP
## should send identity assertions back to the Guacamole server if their
## identity is confirmed.
##
## THIS PROPERTY IS REQUIRED if the SAML extension will be used. It is not
## otherwise possible for Guacamole to know its own public-facing URL,
## particularly in a production deployment that is expected to use SSL
## termination.
##

saml-callback-url: https://demo3.lurey.com

The 4th section contains optional parameters that can be set.

##
## [SAML-4] Request/response compression
##
## Whether compression should be used for requests sent to the SAML IdP, and
## whether compression should be requested for responses from the SAML IdP.
## By default, compression will be used for both requests and responses.
##

#saml-compress-request: true
#saml-compress-response: true

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

KCM Final Setup

Once you have activated the SAML module, there will be a new "Sign in with SAML" link on the login screen of the application as seen below:

When setting up your user identities in the Settings area, if you would like a user to login with SAML / SSO, just leave the "password" field empty.

If you would like to automatically mapping Group assignments in the identity provider to Keeper Connection Manager Groups, simply create a matching group name with the proper assignments. The name of the Group in Keeper Connection Manager needs to match this identifier exactly in order for the mapping to work.

About

The login screen is the first screen users see when they access Keeper Connection Manager. Users use a username and password, or SSO credentials to authenticate into the rest of the platform.

Logging In

Username

Users use their username to login to Keeper Connection Manager. This username is set when creating or importing users.

Password

The user's password. Set when creating or importing the user. Passwords can also be reset by users if allowed.

Other Login Methods

See the authentication documentation pages for more information about setting up additional login methods such as LDAP, SAML 2.0, and OpenID Connect as well as information on setting up 2FA

Login Attempt Limits

As of KCM version 2.9.6, KCM can be configured to limit a user's ability to login after multiple consecutive failed login attempts. This blocks brute-force login attacks on KCM instances.

This setting can be removed, and the number of attempts before a user is locked out and how long they are locked for can be configured with the following guacamole properties or environment variables (depending on installation method):

Apache Guacamole comes with a built-in, simplified, XML-driven authentication mechanism for the sake of testing. Accounts and connections can be defined within /etc/guacamole/user-mapping.xml without having to install support for a database. The default file included with Keeper Connection Manager looks like this:

As noted at the top of the file, you can leverage this to verify that your Guacamole installation is functional, however the user-mapping.xml file should not be used for production deployments. Production deployments of Guacamole should instead use one of the authentication extensions, such as the database support or LDAP. Unlike the XML, all of these extensions are intended for production use.

Format of user-mapping.xml

The user-mapping.xml file consists of a main, root-level <user-mapping> element:

Defining user accounts

This <user-mapping> element may contain any number of <authorize> blocks, each describing a user and their corresponding password:

Granting access to connections

The <authorize> blocks in turn may contain any number of <connection> blocks, each describing a connection that should be accessible to the user:

This file is automatically reread when modified, so you should be able to immediately log in when you define a new user in this way, however changes to an active user’s connections will not be available to that user until they logout.

Defining connections (protocols and parameters)

Each <connection> contains exactly one <protocol> element (specifying the unique name of the protocol to use to connect to the remote desktop) and any number of <param> elements (specifying the name of a parameter and the value to use for that connection). These protocol and parameter names are standardized and case-sensitive. The names of each are defined by Guacamole, and the names of available parameters are defined by the part of Guacamole implementing that support:

The names of many parameters are predictable and common across the supported protocols, like "hostname" and "port", but please consult the for a full list of available parameters and their allowed values, as well as which parameters are absolutely required.

Moving to production

When finished testing, you should prepare to move forward with adding the remaining layers normally required by a production deployment:

1. A supported database: , , and are supported. If you do not already have a database deployed, or are unfamiliar with deploying databases, instructions are provided for.

2. SSL termination: and are supported for this purpose. If you do not already have a reverse proxy in place, or are unfamiliar with installing and configuring a reverse proxy, instructions are provided for

Process overview

Updating an installation of Glyptodon from the 1.x major release to the 2.x major release or to Keeper Connection Manager (releases of version 2.8 and greater) is slightly more complex than simply and will involve the following steps:

2. (rather than 1.x)

4. (it may not automatically recognize the new guacamole.war as new)

5. If you are using a database:

6. If using SSL termination:

Stop Tomcat and guacd

Before upgrading the Glyptodon Enterprise packages, both Tomcat and guacd must be taken offline. By definition, the components of different major releases are incompatible with each other, and these components will be replaced during the upgrade process. It is not safe to perform a major release upgrade while components of Guacamole are running.

Update the .repo file within /etc/yum.repos.d

Each major release of Keeper Connection Manager is located within its own, isolated repository. To upgrade to a major release after 1.X, remove the current .repo file and use the following command to automatically create an updated version:

Alternatively the .repo file can be updated manually. To do this, use a text editor to replace the contents of your old .repo file within /etc/yum.repos.d:

The only difference between the 1.x and 2.x files is in the baseurl, with the relevant part of the base URL changing from "release/1/" to "kcm/2/". Once updated, your .repo file should ultimately look like:

Apply updates using yum

Once the .repo file has been updated to point to the Glyptodon Enterprise 2.x repository, the software components can be upgraded to their 2.x versions by simply running yum upgrade:

As mentioned above, be sure that Tomcat and guacd are both stopped prior to running yum upgrade. If you encounter errors during the upgrade process, double-check that both Tomcat and guacd have indeed been stopped, and re-run the yum upgrade command.

Force Tomcat to redeploy Guacamole

Tomcat may not automatically recognize that the new guacamole.war is indeed new, and may continue to use its cached copy of the older version. To ensure that the new version of Guacamole is deployed, you should remove the directory created by Tomcat when it originally deployed guacamole.war, thus forcing Tomcat to redeploy the .war during startup:

Apply database schema changes

If using MySQL, MariaDB, or PostgreSQL for connection storage and/or authentication, the database schema of your existing database will be that of Apache Guacamole 0.9.12-incubating. It will need to be brought up-to-date with the base version of Apache Guacamole provided by Glyptodon Enterprise 2.x by running the appropriate SQL script against the database in question:

If using PostgreSQL, you will additionally need to to ensure the Guacamole database user has sufficient permissions to execute queries against new tables and sequences, as PostgreSQL does not automatically extend the permissions already granted when new tables/sequences are created.

Update server.xml to trust "X-Forwarded-For" from known proxies

From Apache Guacamole 1.0.0 onward, . This includes Glyptodon Enterprise 2.x, which is based off Apache Guacamole 1.1.0. If you are using a reverse proxy like or for SSL termination, you will need to add a "" entry to /etc/tomcat/server.xml.

Start Tomcat and guacd

After yum upgrade completes, and any needed changes to the database and Tomcat's server.xml have been made, the system has been updated and it is safe to start Tomcat and guacd back up:

Your Keeper Connection Manager installation should now be working and up-to-date with the 2.x release.

Azure Configuration

The first step regardless of installation method is to configure your SAML 2.0 identity provider using Microsoft Azure.

(1) In Azure, go to Enterprise Applications and Create a new application.

(2) Give the Enterprise Application a name, and then select "non-gallery" application.

(3) Set up Single Sign On with SAML.

(4) Configure for SAML

(5) Set up the SAML properties to point Azure to your Keeper Connection Manager installation URL:

(6) To support Azure Group to Keeper Connection Manager User Group mappings, you can add a Group claim by editing the Attributes & Claims then adding a Group Claim.

When prompted, you can decide whether the group claim is always sent, or only for specific groups or assigned users.

(7) Assign users and/or groups to the Keeper Connection Manager application, as you would normally do with any SAML connected app.

(8) Download the Azure Metadata file and save to your local machine as metadata.xml

The Azure side of the setup is complete. Note if you change anything, you need to re-download a new metadata.xml file.

(9) Add the KCM Logo

From the "Properties" screen of the Enterprise Application, upload the KCM logo. The file can be downloaded below.

Here's how the logo will look:

Next: KCM Configuration

Advanced Linux Install Method

If you have installed Keeper Connection Manager using the advanced linux install method, setting up SAML can be performed following the steps below.

Installing SAML support for Guacamole

Keeper Connection Manager packages Guacamole’s SAML support within the kcm-guacamole-auth-sso-saml package:

Connecting Guacamole to SAML

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the SAML installation:

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “SAML-1” and defines the IdP configuration. Uncomment the saml-idp-metadata-url and saml-entity-id property. You'll need to reference the IdP's metadata file and Entity ID.

The second section contains the callback URL that is used by the IdP. This is typically set to the user-facing URL of the Keeper Connection Manager service.

The 3rd section contains the SAML group attribute that can be used for mapping IdP Groups to Keeper Connection Manager Groups. This is useful for assigning permissions to Connections based on a Group attribute from your identity provider. The below example is referencing a Microsoft Azure configuration.

The 4th section contains optional parameters that can be set.

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

KCM Final Setup

Once you have activated the SAML module, there will be a new "Sign in with SAML" link on the login screen of the application as seen below:

When setting up your user identities in the Settings area, if you would like a user to login with SAML / SSO, just leave the "password" field empty.

If you would like to automatically mapping Group assignments in the identity provider to Keeper Connection Manager Groups, ensure that the saml-group-attribute parameter is defined to match the Identity Provider Group Attribute. The name of the Group in Keeper Connection Manager needs to match this identifier exactly in order for the mapping to work.

If the group name attribute from the identity provider is not easy to read, this may end up requiring you to create Group Names that look like below:

If your Active Directory or LDAP deployment spans multiple servers, Guacamole can be configured to use each of your LDAP servers using ldap-servers.yml, a configuration file similar to guacamole.properties and located within /etc/guacamole. When a user authenticates with a Guacamole instance configured to use multiple LDAP servers, each configured LDAP server is tried, in order, until authentication succeeds. Authentication fails only if none of the defined LDAP servers accept the user's provided credentials.

When ldap-servers.yml is used, the values within guacamole.properties still have meaning, but instead serve as defaults for the LDAP servers defined in ldap-servers.yml.

Overview of ldap-servers.yml

The ldap-servers.yml file contains a single YAML list of LDAP servers, with each server definition consisting of a simple list of configuration properties and values. These configuration properties are identical to except that the "ldap-" prefix is omitted.

For example, a simple ldap-servers.yml that defines two LDAP servers that may be used to authenticate users would contain the following:

When a user attempts to log in, Guacamole will attempt to authenticate the user against the first defined LDAP server (server1.example.net). If that fails, Guacamole will proceed with the next (server2.example.net), and so on. Only if authentication fails against all defined LDAP servers will authentication against LDAP fail overall.

Abbreviating common LDAP parameters

Since the only property that varies between the two servers in the above example is the hostname, and since guacamole.properties serves as the source of default values when ldap-servers.yml is used, the configuration details common to all servers would be better specified within guacamole.properties:

The contents of ldap-servers.yml can then be reduced to only the hostnames:

Splitting users across multiple LDAP servers

LDAP servers listed within ldap-servers.yml may optionally be restricted to only certain users with the "match-usernames" option. This option accepts both a single string and an array of strings, where each string is a Perl-compatible regular expression. Additionally, if the regular expression includes a capturing group, the contents of the first capturing group will be used as .

For example, to define two LDAP servers covering distinct domains, splitting usage of those LDAP servers by whether the user enters their username as "DOMAIN1\username" or "DOMAIN2\username", you would edit your ldap-servers.yml to contain something like the following:

Each of the LDAP servers defined above will only be used if their corresponding regular expression matches the username specified by the user. Since each of the regular expressions in the above example define a capturing group around the username component of the "DOMAIN\username" format, that portion of the provided username will be used to determine the user's identity. If a user successfully authenticates as "DOMAIN1\myusername", then:

• The captured portion ("myusername") will be used to.

• The captured portion ("myusername") will be used when

If there are multiple username formats that need to be accepted by each LDAP server, multiple regular expressions may be specified. For example, to match both "MYDOMAIN\myusername" and the UPN-style "[email protected]" formats, you would specify:

Static Tokens

Connection Manager supports configuring custom static tokens which can correspond to a specific field of a specific Keeper Vault record contained within the Shared Folder. These static tokens must be specified in either the Docker compose or directly in the guacamole configuration file, depending on the installation method of the platform. In most cases, the Dynamic Tokens are a preferable method of integration.

Auto Docker Install Method

If you installed Keeper Connection Manager using the Auto Docker Install method, you will need to modify the auto-generated Docker Compose file to define your static tokens.

As root, edit the /etc/kcm-setup/docker-compose.yml file.

Edit the "environment" section underneath the "guacamole" docker image. Insert an environmental variable called KSM_TOKEN_MAPPING that includes a multi-line definition of your custom tokens. In the example below, there are 3 custom tokens for specific fields within the Keeper vault shared folder. The token syntax is using .

Once the file changes have been saved, update the containers:

Docker Compose Install Method

Edit your docker-compose.yml file. Look for the "guacamole" docker image and the "environment" section which defines environmental variables.

Insert an environmental variable called KSM_TOKEN_MAPPING that includes a multi-line definition of your custom tokens. In the example below, there are 3 custom tokens for specific fields within the Keeper vault shared folder. The token syntax is using .

Once the file changes have been saved, update the containers:

Advanced Linux Install Method

To configure custom tokens, add this YAML file to your guacamole configuration files: /etc/guacamole/ksm-token-mapping.yml

In this file, create the tokens that you would like to use and identify what secrets each token corresponds to using .

Example mapping file:

Then, restart the guacamole process as you typically would.

Custom Token Usage

When using custom tokens, the records can be setup in any way. Keeper notation in the mapping file can identify any specified field.

The tokens can then be used with the ${XXX} format within the Connection Manager parameters screen. A couple of examples are seen below:

TOTP issuer details

A human readable name must be associated with generated keys such that the user enrolling their authentication device will be able to easily distinguish the code they should use for this application vs. the other applications that same authentication device may be used for. This value does not affect the key generated nor handling of received codes; it only serves as a reference for the user.

TOTP code generation

Most authentication devices supporting TOTP use 6-digit codes, a code period of 30 seconds, and the SHA-1 hash algorithm. These values are used as the defaults for code generation. If your requirements differ, these default values may be overridden.

CentOS and RHEL both provide a package for the PostgreSQL database server called "postgresql-server". Installing this package will install a version of PostgreSQL that is . If you do not have an existing database instance or third-party database hosting provider that you would prefer to use, installing a fresh instance of PostgreSQL for use by Guacamole will work nicely:

As with other standard CentOS / RHEL packages providing a service, the PostgreSQL service will not be started by default after the "postgresql-server" package is installed. However, if you attempt to start the PostgreSQL service now, the service will fail to start as PostgreSQL's database has not yet been created and initialized. This must be done manually with the "postgresql-setup" command:

Once the database has been initialized, the service can be safely started and configured to start automatically if the system is rebooted:

Configuring PostgreSQL to accept password authentication locally

If PostgreSQL is installed locally (on the same server as Apache Guacamole), its default configuration will prevent Guacamole from authenticating. This is because PostgreSQL can be configured to use different authentication mechanisms for connections coming from different networks or addresses, and the default configuration uses "ident" authentication for connections from the local machine. The "ident" method is incompatible with providing a database username and password via TCP, which will result in Guacamole being unable to connect to PostgreSQL.

Edit PostgreSQL's main configuration file, /var/lib/pgsql/data/pg_hba.conf, looking for the lines which associate IPv4 or IPv6 loopback addresses with "ident":

The keyword ident should be changed to md5 to allow username/password authentication for local connections:

PostgreSQL will then need to be restarted to apply these changes:

Pointing Guacamole at the new PostgreSQL instance

Once PostgreSQL has been deployed, you should move forward with This process is documented in its entirety, and the default /etc/guacamole/guacamole.properties file also contains placeholders and comments to help guide administrators to the correct configuration properties. Overall, the process will involve:

• Installing the package providing PostgreSQL support (kcm-guacamole-auth-jdbc-postgresql).

• Creating a new database within your PostgreSQL instance using the provided schema files.

• Creating a database user that Guacamole can use to execute queries against your database.

• Editing /etc/guacamole/guacamole.properties to point Guacamole at your database (and to specify the credentials of the database user it should use).

Advanced Linux Install Method

Installing LDAP support for Guacamole

Keeper Connection Manager packages Guacamole’s LDAP support within the kcm-guacamole-auth-ldap package:

$ sudo yum install kcm-guacamole-auth-ldap

Unlike the MySQL, PostgreSQL, SQL Server and authentication backends, Guacamole’s LDAP support does not require a schema to be applied unless you intend to store connection data within your LDAP directory. If LDAP will be used only to authenticate Guacamole users, no schema modifications need be made, and a database should be used to store connection data.

If you do intend to store connection data within your LDAP directory, you will need to apply the provided schema modifications which create the guacConfigGroup object class. Be sure to first finish configuring Guacamole for LDAP authentication, and verify that Guacamole can successfully authenticate users against your LDAP directory.

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the LDAP directory:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “LDAP-1” and defines the TCP connection information for the LDAP directory. Uncomment the ldap-hostname property, modifying its value to point to your LDAP server:

##
## [LDAP-1] LDAP TCP connection information
##
## The TCP connection details of the LDAP server, as well as whether encryption
## should be used.
##
## Legal encryption methods are "none", for unencrypted connections, "ssl" 
## for LDAP over SSL/TLS (also known as LDAPS), or "starttls" for STARTTLS.
##

#ldap-hostname:          localhost
#ldap-port:              389
#ldap-encryption-method: none

By default, Guacamole will connect to your LDAP server without encryption. If your LDAP server uses encryption, you will need to uncomment and set the ldap-encryption-method property to “ssl” for LDAPS (LDAP over SSL/TLS) or “starttls” for STARTTLS.

The default port varies by encryption method, and will be 389 for unencrypted LDAP and STARTTLS, or 636 for LDAPS. If your LDAP server listens on a non-standard port, you will also need to uncomment and modify the ldap-port property.

Mapping Guacamole usernames to LDAP DN’s

To authenticate users using LDAP, Guacamole must translate usernames into their corresponding LDAP DN’s. Depending on the complexity of your LDAP directory, this can be as simple as adding a single attribute to a common base DN, or can involve an LDAP query.

The “LDAP-2” section defines the basic parameters required for either case:

##
## [LDAP-2] LDAP user / user DN description
##
## The base DN of all Guacamole users within the LDAP directory, and the
## attribute which contains each user's username. If the username attribute
## is not part of the DN, a seach DN will need to be provided, as well.
##

#ldap-user-base-dn:       ou=people,dc=example,dc=net
#ldap-username-attribute: uid

The base DN defined by the ldap-user-base-dn property should be the common base shared by all Guacamole users within your LDAP directory, while the attribute which contains the user’s username is defined by ldap-username-attribute. The base DN is always required if LDAP is being used.

Direct username mapping

By default, Guacamole will attempt to derive the user’s DN directly by prepending the username attribute to the base DN. For example, assume a user is attempting to login with the username “someUser”. If the base DN is “ou=people,dc=example,dc=net” and the username attribute is “uid” (the default), then Guacamole will perform the following steps to authenticate the user:

1. Prepend the username to the base DN using the “uid” attribute, producing the DN: “uid=someUser,ou=people,dc=example,dc=net”.

2. Attempt to bind using the DN “uid=someUser,ou=people,dc=example,dc=net” and the password provided by the user.

3. If the bind attempt succeeds, authentication is successful.

Indirect username mapping

For more complex cases, where the user DN is cannot be directly derived by prepending the username attribute, Guacamole can instead issue an LDAP query to determine the user DN. This requires a search DN and password, defined with the ldap-search-bind-dn and ldap-search-bind-password properties respectively, which Guacamole will bind as when performing the query:

##
## [LDAP-3] LDAP user search DN
##
## The DN and password of the user to bind as when searching for the DN of each
## user attempting to log in. If omitted, the DN of each user will be derived
## directly using the user base DN and username attribute.
##

#ldap-search-bind-dn:       cn=someUser,ou=people,dc=example,dc=net
#ldap-search-bind-password: some_password

With the search DN and password configured, Guacamole will perform the following steps to authenticate a user:

1. Bind to the LDAP directory using the search DN and password.

2. Issue an LDAP query for objects within the subtree of the base DN that contain the user’s username within the defined username attribute.

3. If exactly one such object is found, attempt to bind using the DN of that object and the password provided by the user.

4. If the bind attempt succeeds, authentication is successful.

Mapping Guacamole groups to LDAP DN’s

Access to connections within Guacamole may be dictated through LDAP user groups via either of two mechanisms:

1. Defining connections directly within LDAP using schema modifications and dictating group access using the "seeAlso" attribute.

2. Mapping LDAP groups to Guacamole groups and leveraging a database to dictate access.

As it is usually preferable to avoid modifying the LDAP schema, mapping LDAP groups to Guacamole groups is recommended. Doing this will require defining the base DN under which all relevant LDAP groups may be found and defining the LDAP attribute that should be used by Guacamole to determine the unique name of the group:

##
## [LDAP-5] LDAP group / group DN description
##
## The base DN of all Guacamole groups within the LDAP directory, and the
## attribute which should be used by Guacamole to uniquely identify the
## group.
##
## If connections are being stored within LDAP using "guacConfigGroup" objects,
## and you wish to control access to these connections via LDAP groups, this is
## accomplished using the standard "seeAlso" attribute and the
## ldap-group-base-dn property is required.
##
## If connections are being stored outside of LDAP, such as within a database,
## and you wish to control access using LDAP groups, both ldap-group-base-dn
## and ldap-group-name-attribute will be required. The group membership of a
## user cannot be queried without a base DN, and the unique name to be used by
## other parts of Guacamole to represent the group cannot be determined without
## the name attribute.
##

#ldap-group-base-dn:        ou=groups,dc=example,dc=net
#ldap-group-name-attribute: cn

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

Custom Root Certificate

If you require the use of a custom Root Certificate for your LDAP server, you can volume mount the file /etc/pki/ca-trust/extracted/java/cacerts in your Docker Compose to override this certificate in the guacamole docker container.

• Import the certificate into a Java truststore using "keytool".

• Volume mount the cacerts file to your target guacamole docker container

For Advanced Linux Install method leveraging the RPMs, this would be accomplished through Red Hat's automated certificate import tooling following this guide.

/etc/guacamole/guacd.conf is the configuration file for Apache Guacamole's proxy daemon, guacd. Editing this file is not normally required unless the circumstances of your deployment require internal communications to be encrypted (not just public-facing communication), the guacd service needs to listen on an external interface or non-standard port, or you need to increase logging verbosity to assist with debugging unexpected behavior.

The guacd.conf file is read only during service startup, and changes to guacd.conf will take effect only after restarting the guacd service.

Organization and general syntax

The guacd.conf file is organized within three distinct sections, each section having special meaning to guacd and containing only parameters specific to that section:

• "server" - Parameters for configuring the hostname/address and port used by guacd.

• "daemon" - Parameters for configuring the behavior of the guacd daemon, in particular logging level.

• "ssl" - Parameters for configuring SSL/TLS encryption of the internal communication between the web application and guacd.

The beginning of each section is denoted with a section name in brackets, and each section ends implicitly with the beginning of a new section, or at the end of the file.

Parameters names and values

Parameters within sections are written as a parameter name, followed by an equals sign, followed by the parameter value, all on one line.

name = value

If special characters need to be placed within a parameter value, such as whitespace, #, ", or \, the entire value must be enclosed in double quotes, and each occurrence of " or \ within the value must be escaped with backslashes:

name = "quoted # value \\ with \" special characters"

Comments

Comments may be placed anywhere, including at the end of a parameter, and consist of arbitrary text following a # symbol until end-of-line:

# Arbitrary comment
name = value # Another arbitrary comment

Server parameters

The parameters within the "server" section define the hostname/address and port that the guacd service should listen on. By default, the guacd service will listen at port 4822 on localhost, and thus will accept connections from a local instance of Guacamole only. If these values are changed, the Guacamole web application will need to be reconfigured to match by editing /etc/guacamole/guacamole.properties.

Daemon parameters

The parameters within the "daemon" section control how guacd operates as a daemon, in particular the level at which messages should be logged. Greater logging verbosity may be desired if unexpected behavior is encountered.

SSL/TLS parameters

guacd can be configured to communicate with the web application using SSL/TLS. If a certificate and key are specified, guacd will require SSL/TLS for all connections from the web application, and the web application will need to be reconfigured to match by editing /etc/guacamole/guacamole.properties. If the certificate cannot be verified by Java against well-known CA certificates, the certificate will also need to be added to Java's truststore.

By default, internal communication between guacd and the web application is not encrypted.

SAML 2.0 Configuration Properties

Controlling Login Behavior

Keeper Connection Manager loads authentication extensions in order of priority, and evaluates authentication attempts in this same order. This has implications for how the login process behaves when an SSO extension is present:

If the SSO extension has priority:

Users that are not yet authenticated will be immediately redirected to the configured identity provider. They will not see a Keeper Connection Manager login screen.

If a non-SSO extension has priority:

Users that are not yet authenticated will be presented with a Keeper Connection Manager login screen. Additionally, links to the configured identity provider(s) will be available for users that wish to log in using SSO.

The default priority of extensions is dictated by their filenames, with extensions that sort earlier alphabetically having higher priority than others. This can be overridden by setting the extension-priority property within guacamole.properties.

Automatically redirecting all unauthenticated users

To ensure users are redirected to the SAML identity provider immediately (without a Keeper Connection Manager login screen), ensure the SAML extension has priority over all others:

extension-priority: saml

Presenting unauthenticated users with a login screen

To ensure users are given a normal Keeper Connection Manager login screen and have the option to log in with traditional credentials or with SAML, ensure the SAML extension does not have priority:

extension-priority: *, saml

The values of connection parameters can contain "tokens" which will be dynamically replaced by Keeper Connection Manager when used. These tokens allow the values of connection parameters to vary dynamically by the user using the connection, and provide a simple means of forwarding authentication information without storing that information in the connection configuration itself, so long as the remote desktop connection uses the same credentials as Keeper Connection Manager.

Common uses for these tokens include:

• Automatically authenticating users with their remote desktops by passing through the credentials provided during login. This is typically useful when both Keeper Connection Manager and the remote desktops authenticate against the same, central authority, such as Active Directory or LDAP.

• Providing remote desktops with the user's IP address or hostname, as may be required for licensing, auditing, or logging.

• Automatically organizing session recordings using the current date and time.

Each token is of the form ${TOKEN_NAME}, where TOKEN_NAME is some descriptive name for the value the token represents. Tokens with no corresponding value will never be replaced, but should you need such text within your connection parameters, and wish to guarantee that this text will not be replaced with a token value, you can escape the token by adding an additional leading "$", as in "$${TOKEN_NAME}".

Username/password pass-through

When a user authenticates with Keeper Connection Manager, the credentials that they used may be automatically passed through to their connections using the "${GUAC_USERNAME}" and "${GUAC_PASSWORD}" tokens. These may be specified within any connection parameters, including the parameters which specify the username and password to be used to connect to the remote desktop, thus allowing the administrator to explicitly define how and whether user credentials are passed through. Unless these tokens are specified by the administrator, no such pass-through will take place.

Client hostname/address information

The hostname (if known) or IP address of the machine that the current Keeper user is connecting from may be included within connection parameters using the "${GUAC_CLIENT_HOSTNAME}" and "${GUAC_CLIENT_ADDRESS}" tokens respectively. Note that the client address may not be the true address of the user if they are connecting through one or more proxies, or if they are connecting through a VPN, and there may be no associated hostname for that address.

Current date and time

Timestamps representing when the user started the connection may be included within connection parameters using the "${GUAC_DATE}" and "${GUAC_TIME}" tokens. Each of these tokens are replaced by values that consist only of digits. It is common to use these tokens within the parameter specifying the name of the session recording to be created, perhaps together with the "${GUAC_USERNAME}" token, to allow recordings to be given reasonably unique names and to be organized automatically.

For example, if connection were configured to record sessions to files names "${GUAC_USERNAME}-${GUAC_DATE}-${GUAC_TIME}.guac", and a user named "someuser" connected to that connection on January 1st, 2020, at exactly midnight, the session recording created would be named "someuser-20200101-000000.guac".

Okta Configuration

The first step regardless of installation method is to configure your SAML 2.0 identity provider using Okta.

(1) In Okta, go to Admin > Applications > Create App Integration and select SAML 2.0. Click Next.

(2) Give the Enterprise Application a name and upload the logo file linked below then click Next.

The image logo is here:

(3) Configure the SAML Settings

The SAML configuration should match the format as seen below:

• Replace demo3.lurey.com with the URL of your Keeper Connection Manager domain.

• Ensure the full path appears, e.g. https://DOMAIN/api/ext/saml/callback

• For the Audience URI, use the path to the Login screen (remove the trailing slash). For example, https://demo3.lurey.com

Scroll down to the Group Attribute Statements. To send the group attribute, set the name to "groups", and the name format to "Basic". If you would like ALL groups assigned to the user to be sent to Keeper Connection Manager, select the "Matches regex" with a value of ".*"

Click Next.

(4) In the Feedback section, make the selections as appears below.

(5) Assign users and/or groups to the Keeper Connection Manager application, as you would normally do with any SAML connected app.

(6) Download the Okta Metadata file and save to your local machine as metadata.xml

The location of the metadata file depends on your version of the Okta interface. In this example there is a link called "Identity Provider metadata" on the application page. There may also be a text box that contains the metadata which you can copy and paste into a local file on your computer.

The metadata XML file could also be linked in the Sign On tab > SAML Signing Certificate section under "Actions".

Save the resulting metadata.xml file by selecting "Save page as..." in your browser.

The Okta side of the setup is complete. Note if you change anything, you need to re-download a new metadata.xml file.

Next: KCM Configuration

Advanced Linux Install Method

If you have installed Keeper Connection Manager using the advanced linux install method, setting up SAML can be performed following the steps below.

Installing SAML support for Guacamole

Keeper Connection Manager packages Guacamole’s SAML support within the kcm-guacamole-auth-sso-saml package:

$ sudo yum install kcm-guacamole-auth-sso-saml

Connecting Guacamole to SAML

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the SAML installation:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “SAML-1” and defines the IdP configuration. Uncomment the saml-idp-metadata-url and saml-entity-id property. You'll need to reference the IdP's metadata file and Entity ID.

##
## [SAML-1] Identity provider details
##
## The details of the identity provider (IdP) that Guacamole should use for
## authentication. These properties dictate how Guacamole should communicate
## with the IdP, including the how users should be redirected for
## authentication by the IdP.
##
## The SAML IdP will typically provide this information in advance in the form
## of an XML file. If no such XML file is provided, or if information is
## missing from that XML file, additional properties will need to be specified
## to provide that information.
##
## The key pieces of information required are:
##
##  * The URL of the SAML endpoint used by the IdP.
##  * The "entity ID" that should be used by Guacamole to identify itself with
##    the IdP.
##
## If the SAML IdP provides an XML metadata file, it is unusual for that file
## to not contain both of the above pieces of information.
##
## THIS INFORMATION IS REQUIRED if the SAML extension will be used.
##

saml-idp-metadata-url: file:///etc/guacamole/metadata.xml
saml-entity-id: https://demo3.lurey.com

The second section contains the callback URL that is used by the IdP. This is typically set to the user-facing URL of the Keeper Connection Manager service.

##
## [SAML-2] Guacamole server details
##
## The details of the Guacamole server that should be provided to the SAML IdP
## when authenticating the user. This information defines how the SAML IdP
## should send identity assertions back to the Guacamole server if their
## identity is confirmed.
##
## THIS PROPERTY IS REQUIRED if the SAML extension will be used. It is not
## otherwise possible for Guacamole to know its own public-facing URL,
## particularly in a production deployment that is expected to use SSL
## termination.
##

saml-callback-url: https://demo3.lurey.com

The 4th section contains optional parameters that can be set.

##
## [SAML-4] Request/response compression
##
## Whether compression should be used for requests sent to the SAML IdP, and
## whether compression should be requested for responses from the SAML IdP.
## By default, compression will be used for both requests and responses.
##

#saml-compress-request: true
#saml-compress-response: true

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

KCM Final Setup

Once you have activated the SAML module, there will be a new "Sign in with SAML" link on the login screen of the application as seen below:

When setting up your user identities in the Settings area, if you would like a user to login with SAML / SSO, just leave the "password" field empty.

If you would like to automatically mapping Group assignments in the identity provider to Keeper Connection Manager Groups, simply create a matching group name with the proper assignments. The name of the Group in Keeper Connection Manager needs to match this identifier exactly in order for the mapping to work.

Config Parameter Protection

The Keeper Vault can be utilized to protect and store configuration secrets that would normally be hard-coded into the guacamole.properties or Docker Compose file.

Auto Docker Install Method

If you installed Keeper Connection Manager using the Auto Docker Install method, configuration secrets are protected in the auto-generated Docker Compose file.

As root, edit the /etc/kcm-setup/docker-compose.yml file.

For each configuration secret that you want to protect, you can replace the entry with a direct lookup in the Keeper vault. A good example of this is replacing the hard-coded MySQL database password with a vault record.

BEFORE:

MYSQL_HOSTNAME: "db"
MYSQL_DATABASE: "guacamole_db"
MYSQL_USERNAME: "guacamole_user"
MYSQL_PASSWORD: "your_mysql_database_password"

AFTER:

MYSQL_HOSTNAME: "db"
MYSQL_DATABASE: "guacamole_db"
MYSQL_USERNAME: "guacamole_user"
MYSQL_PASSWORD_KSM_SECRET: keeper://2ZlOFQAYi4DubJWBtSbRxw/field/password

The token syntax is using Keeper Notation. The name of the parameter must follow the format of *_KSM_SECRET. In this example, the MySQL database password is pulled directly from a Keeper record in the Shared Folder.

The value of each *_KSM_SECRET variable should be the Keeper notation of the secret that should be used to pull the necessary configuration value. For example, if SOME_VARIABLE_KSM_SECRET were set to valid Keeper notation, then the value of the Guacamole property normally associated with SOME_VARIABLE will be pulled from that secret in KSM.

Once the file changes have been saved, update the containers:

$ sudo ./kcm-setup.run upgrade

Docker Compose Install Method

Edit your docker-compose.yml file.

For each configuration secret that you want to protect, you can replace the entry with a direct lookup in the Keeper vault. A good example of this is replacing the hard-coded MySQL database password with a vault record:

MYSQL_HOSTNAME: "db"
MYSQL_DATABASE: "guacamole_db"
MYSQL_USERNAME: "guacamole_user"
MYSQL_PASSWORD_KSM_SECRET: keeper://2ZlOFQAYi4DubJWBtSbRxw/field/password

The token syntax is using Keeper Notation. In this example, the MySQL database password is pulled directly from a Keeper record in the Shared Folder as seen below:

The value of each *_KSM_SECRET variable should be the Keeper notation of the secret that should be used to pull the necessary configuration value. For example, if SOME_VARIABLE_KSM_SECRET were set to valid Keeper notation, then the value of the Guacamole property normally associated with SOME_VARIABLE will be pulled from that secret in KSM.

Once the file changes have been saved, update the containers:

sudo su
docker-compose up -d

Advanced Linux Install Method

To utilize Keeper Vault storage of Guacamole properties, create a file guacamole.properties.ksm in the same location as your guacamole.properties file (/etc/guacamole/ by default).

In the new file, add any properties that you would like to store in the Keeper vault, and set the value to a Keeper Notation query of the record field to use for that property. Note that the guacamole.properties file must still contain the ksm-config property to identify the Keeper Secrets Manager configuration.

Example Setup

guacamole.properties:

ksm-config: eyJob3N0bm[...]1IzRTN2UVNTNkhsb0NZQW9nUmlPVlY5cjhvUT0ifQ==

guacamole.properties.ksm:

mysql-hostname: keeper://tqd1F9zHRKokN44Xso8PkQ/field/host[hostname]
mysql-port: keeper://tqd1F9zHRKokN44Xso8PkQ/field/host[port]
mysql-password: keeper://tqd1F9zHRKokN44Xso8PkQ/field/password

The token syntax is using Keeper Notation. In this example, the MySQL database password is pulled directly from a Keeper record with the specified UID tqd1F9zHRKokN44Xso8PkQ.

Then, restart the guacamole process as you typically would.

$ sudo systemctl restart guacamole

Other configuration options

In docker installations, the parameter ADDITIONAL_GUACAMOLE_PROPERTIES_KSM can be used to move parameters from the guacamole.properties file into guacamole.properties.ksm.

Software affected

• Glyptodon Enterprise 2.6 and older

Description

Apache Guacamole 1.2.0 and 1.3.0 do not properly validate responses received from a SAML identity provider. If SAML support is enabled, this may allow a malicious user to assume the identity of another Guacamole user.

Preconditions for exploitation

• SAML support for Apache Guacamole is enabled.

Results of a successful attack

• A malicious user may assume the identity of another existing Guacamole user.

Mitigation

Glyptodon Enterprise 2.x has been patched with respect to this vulnerability. Users should evaluate their exposure/risk based on this advisory and plan to upgrade when possible.

Glyptodon Enterprise 1.x does not have support for SAML available and is not affected.

Analysis and CVSS score breakdown

Severity rating scale

Keeper Connection Manager evaluates the factual details of each known vulnerability affecting Keeper Connection Manager and assigns severity ratings using the CVSS v3.1 scoring system, a standard owned by FIRST.Org, Inc. which FIRST has made freely available for public use. This scoring system produces a numeric rating between 0.0 and 10.0, which we then classify according to the "Qualitative Severity Rating Scale" published with the CVSS standard. The specific analysis that went into each assigned score can also be found within the document specific to the vulnerability, linked within the main table above.

Software affected

• Glyptodon Enterprise 1.15 and older

• Glyptodon Enterprise 2.5 and older

Description

Apache Guacamole 1.3.0 and older may incorrectly include a private tunnel identifier in the non-private details of some REST responses. This may allow an authenticated user who already has permission to access a particular connection to read from or interact with another user's active use of that same connection.

Preconditions for exploitation

• Multiple users that share access to the same connections, which are (1) already in use and (2) originally established using the HTTP tunnel instead of WebSocket.

Results of a successful attack

• A user with access to a connection that is already in use by another user via the HTTP tunnel is able to read instantaneous blocks of transmitted connection data, as well as transmit data over that connection.

Mitigation

Both Glyptodon Enterprise 1.x and 2.x have been patched with respect to this vulnerability. Users should evaluate their exposure/risk based on this advisory and plan to upgrade when possible.

Analysis and CVSS score breakdown

Overview

Keeper Connection Manager can pull secrets from different vaults or different shared folders of the Keeper Vault, via the Keeper Secrets Manager integration. There are two main ways which KCM can connect to multiple Keeper Vaults for retreiving secrets:

1. Connection Groups can be assigned to different secrets manager configurations. Any connection defined within a Connection Group will retrieve secrets from the group assignment.

2. Users can be assigned Secrets Manager configurations, and connections can retrieve secrets from configurations defined by each individual user profiles. This allows different users to connect to the same set of connections with their own set of secrets.

Connection Groups

Each Keeper Connection Manager "Connection Group" can use a Keeper Secrets Manager configuration for the connections in the group. When this is activated, each connection group will look for records in the corresponding Secrets Manager configuration to retrieve secrets and replace tokens in the connection settings.

In order to use a Keeper Secrets Manager with a Connection Group, enter a Keeper Secrets Manager One-Time Access Token, or Configuration into the "KSM Service Configuration" field of the connection group form.

All connections created within this Connection Group will then use the Secrets Manager configuration defined to retrieve secrets when establishing connections, instead of using the root level Secrets Manager configuration.

The Secrets Manager configuration can come from the same vault, or any other vault.

See the Dynamic Tokens documentation for more information on the available tokens and how to use them.

User-Specified Configuration

Each Keeper Connection Manager User profile can be assigned to a Keeper Secrets Manager configuration for any connection. When the connection is updated to allow user-specific vaults, Keeper Connection Manager will pull the secret from the user's corresponding configuration.

In order to use user-specific secrets manager connections, the Keeper Connection Manager installation needs to have the feature enabled. It is disabled by default.

Docker Install Method

An additional environmental variable must be added to the keeper/guacamole Docker image in your docker-compose.yml file.

KSM_ALLOW_USER_CONFIG

For example:

            ....
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            KSM_CONFIG: "XXX"
            ....
            ....
            KSM_ALLOW_USER_CONFIG: "true"
            ....

Advanced Linux Install Method

You must set the setting in the guacamole.properties file, or set the associate environment variable for the keeper/guacamole docker image.

guacamole.properties

In the Edit User screen, fill in the KSM Service Configuration that has been set up for that user. This is also available to each user to set up the KSM Service Configuration for themselves.

When creating or editing a connection, there is a field which appears called "Allow user-provided KSM configuration".

When this option is selected, Keeper Connection Manager will look for corresponding secrets in the user's vault corresponding to the Keeper Secrets Manager configuration.

Order of Precedence

Keeper Connection Manager will always use the base (or Connection Group) secrets if any are applicable. It will only use user-provided secrets if there isn't an admin-provided secret for the same, to ensure that users cannot override the intent of the admin.

Keeper Connection Manager and Apache Guacamole support multiple protocols through a common, centralized gateway. The "guacd" service sits between the Guacamole web application and the remote desktops and dynamically translates between low-level remote desktop protocols and the Guacamole protocol, applying additional optimization and compression in the process.

Installing support for a protocol

Within Keeper Connection Manager, support for each protocol is provided via separate packages. Only the packages for protocols that you will be using need be installed:

When using any particular connection, the package providing support for that connection's underlying protocol must already be installed on the server running the guacd service. If support for the underlying protocol has not been installed, users attempting to use the connection will see an error message, and system administrators will see a message like the following within the systemd journal:

If a needed package was not installed and a message like that above is logged, installing the needed package will solve the problem. If using , all protocol support is already installed. If using the @kcm-guacamole package group, as described within , protocol support for VNC, RDP, and SSH is installed.

Configuring the protocol of a connection

When using one of the supported databases, administrators can define new connections using Guacamole's web interface, selecting the protocol to be used for that connection from a dropdown menu labeled "Protocol":

If defining a connection through a mechanism which does not leverage one of the supported databases, such as via /etc/guacamole/user-mapping.xml,, or, the protocol will must be specified using the unique, internal name for that protocol:

Creating and initializing the Guacamole database

If you haven’t already done so, a database specific to Guacamole needs to be created within PostgreSQL. The database can be called anything you like; all that matters is that the database be dedicated to Guacamole, and not shared by different applications:

Guacamole will not automatically initialize the database with the required schema. You will need to do this yourself using the SQL scripts provided with the kcm-guacamole-auth-jdbc-postgresql package, which are located within the /opt/keeper/share/guacamole-auth-jdbc-postgresql/schema directory:

The above scripts must be run in sequence, as it is the first script which actually creates the database schema. The second script, which defines a default administrative user, can only successfully run if the tables created by the first script exist. The simplest way to run both scripts in sequence is to concatenate them:

Alternatively, the scripts can be run individually, as long as the order is correct:

Connecting Guacamole to PostgreSQL

To execute queries against the database, Guacamole will need its own database user with sufficient privileges. Because Guacamole does not automatically apply or update its own schema, the required privileges are minimal, dealing only with creation and maintenance of data within already-defined tables and indexes:

Advanced Linux Install Method

Keeper Connection Manager packages Guacamole’s PostgreSQL support within the kcm-guacamole-auth-jdbc-postgresql package. This package must be installed before creating Guacamole’s database within PostgreSQL, as it includes the SQL scripts necessary for doing so:

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must now be modified to specify the credentials of the PostgreSQL user and to point the PostgreSQL database:

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “JDBC-1” and defines the TCP connection information for the database in use. Uncomment the postgresql-hostname and postgresql-port properties, modifying their values to point to your PostgreSQL server:

The “JDBC-2” section, which defines the database name and associated credentials, must also be modified to specify the correct database name, username, and password. These values are given with the postgresql-database, postgresql-username, and postgresql-password properties respectively:

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process.

Advanced Linux Install Method

To make sure everything is working as expected, you should also visit your Guacamole instance with a web browser (most likely at http://HOSTNAME:8080/guacamole/, where “HOSTNAME” is the hostname or IP address of your server). If all is working correctly, you should see a login screen with a username/password prompt, and you will be able to log in using the default account created with the 002-create-admin-user.sql script: