Preparing for Installation

Keeper Connection Manager will serve your secure "jumpbox" and you'll use your web browser to access it. First, choose a URL that you'd like to use for accessing KCM.

You'll need the following:

1. A designated machine (usually a Linux VM) with a static IP address 2. Choose 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

No cert? Don't worry, you can:

1. Start by choosing "use a self-signed certificate" (for testing)

2. Choose "Let's Encrypt" to generate a 90 day auto-renewing cert (requires 80 and 443 open)

3. Bring your own cert during setup or add it in later using the reconfigure command

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 internal/external DNS A Record (or AAAA record) to point your domain to your KCM server's IP address

4. Make sure that ports 80 and 443 are open to the public if you plan to use Let's Encrypt.

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

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 staff will generate your KCM on-prem license key. It can then be accessed directly from the Keeper Admin Console:

To install your license key, follow the steps below:

New Customers

During the installation process, you will be prompted to input the license key.

Existing Customers

If using the Auto Docker Install or Docker Compose Install method, simply update the keeper/guacamole container definition with the license as the value of the KCM_LICENSE environment variable.

Example:

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            .
            .
            .
            KCM_LICENSE: "XXXXXXXXXXXXXXXXXXXXXXXXXX"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

• (Optional) If the license will be present within a file in your container, you may alternatively use the KCM_LICENSE_FILE environment variable to point to that file.

• (Optional) If using the RPM packages, you must provide the license as the sole contents of /etc/guacamole/kcm.license, which must be readable by the guacamole group.

After adding the license key, restarting the container is necessary. If using the Auto Docker Install method, simply run:

sudo ./kcm-setup.run apply

Keeper is Fanatical About Data Protection

Keeper utilizes best-in-class security with a zero-trust framework and zero-knowledge security architecture to safeguard your infrastructure and mitigate the risk of a data breach.

Overview

Keeper Security, Inc. (KSI) is passionate about protecting its customer's information and infrastructure with Keeper desktop and mobile security software. Millions of consumers and businesses trust Keeper to secure and access remote systems, passwords and private information. Keeper's software is constantly improved and updated to provide our customers with the latest in technology and protection. This page provides an overview of Keeper's security architecture and encryption methodologies.

System Architecture

The Keeper Connection Manager Gateway is a platform that is fully hosted by the customer in any cloud, on-prem or virtual environment. Keeper provides customers with the Auto Docker Install and Docker Compose Install method of installation.

The Docker container is made up of several core components including:

• Apache Guacamole web application software

• Apache Guacamole "guacd" protocol service

• NGINX for SSL termination and reverse proxy

• Apache Tomcat services

• MySQL, PostgreSQL or other supported databases

Additional packages that support Enterprise capabilities such as SAML 2.0 / SSO, OpenID Connect, TOTP, Vault Integration and components are provided as part of the package installers or as separate add-on components.

Apache Guacamole™

The engineering team at Keeper Security that built Keeper Connection Manager (formerly Glyptodon) are the inventors and primary maintainers of the open source Apache Guacamole project. Keeper Security is proud to support the open source community and millions of users who use the Apache Guacamole remote desktop software.

Least Privilege Access

The packages provided by Keeper Connection Manager have been designed to follow best practices with respect to security, particularly with respect to the Principle of Least Privilege. This is accomplished through careful delegation of rights through users and groups which are automatically created by the Keeper Connection Manager packages, and through strict file permissions.

Production Configuration

Once ready to deploy Keeper Connection Manager to production, it is critically important that customers configure SSL encryption. You will need to obtain an SSL certificate for your server such that all Keeper Connection Manager traffic is encrypted.

If you have have deployed Keeper Connection Manager using the Auto Docker Install or Docker Compose Install method, you may have already configured SSL.

Upgrade Methods

• Customers who deploy the Auto Docker Install version can use the built-in update capabilities.

• Customers who deploy the Docker Compose Install version can use the Docker update capabilities.

Compliance & Audits

Certified SOC 2 Compliant

Customer vault records are protected using stringent and tightly monitored internal control practices. Keeper is certified as SOC 2 Type 2 compliant in accordance with the AICPA Service Organization Control framework. SOC 2 certification helps ensure that your vault is kept secure through the implementation of standardized controls as defined in the AICPA Trust Service Principles framework.

ISO 27001 Certified (Information Security Management System)

Keeper Security is ISO 27001 certified, covering the Keeper Security Information Management System which supports the Keeper Enterprise Platform. Keeper's ISO 27001 certification is scoped to include the management and operation of the digital vault and cloud services, software and application development, and protection of digital assets for the digital vault and cloud services.

GDPR Compliance

Keeper is GDPR compliant and we are committed to ensuring our business processes and products continue to maintain compliance for our customers in the European Union. Click here to learn more about Keeper's GDPR compliance and download data processing agreements.

Protection of Patient Medical Data

Keeper software is compliant with global, medical data protection standards covering, without limitation, HIPAA (Health Insurance Portability and Accountability Act) and DPA (Data Protection Act).

HIPAA Compliance and Business Associate Agreements

Keeper is a SOC2-certified and ISO 27001-certified zero-knowledge security platform that is HIPAA compliant. Strict adherence and controls covering privacy, confidentiality, integrity and availability are maintained. With this security architecture, Keeper cannot decrypt, view or access any information, including ePHI, stored in a user’s Keeper Vault. For the foregoing reasons, Keeper is not a Business Associate as defined in the Health Insurance Portability and Accountability Act (HIPAA), and therefore, is not subject to a Business Associate Agreement.

To learn more about the additional benefits for healthcare providers and health insurance companies, please read our Security Disclosure and visit our Enterprise Guide.

Penetration Testing

Keeper performs quarterly pen testing with 3rd party experts including NCC Group and Cybertest. In addition, Keeper works with independent security researchers who test against all of our products and systems through our Bugcrowd bug bounty program.

Third-Party Security Scanning & Penetration Tests

Keeper Security environments are tested daily by TrustedSite to ensure that the Keeper web application and KSI's Cloud Security Vault are secure from known remote exploits, vulnerabilities and denial-of-service attacks. A comprehensive external security scan is conducted monthly on the Keeper websites, Keeper web application, and Keeper Cloud Security Vault by TrustedSite. Keeper staff periodically initiate on-demand external scans.

Payment Processing and PCI Compliance

Keeper Security uses PayPal and Stripe for securely processing credit and debit card payments through the KSI payment website. PayPal and Stripe are PCI-DSS compliant transaction processing solutions. Keeper Security is certified PCI-DSS compliant.

EU-US Privacy Shield

The Keeper web client, Android App, Windows Phone App, iPhone/iPad App and browser extensions have been certified Privacy Shield compliant with the U.S. Department of Commerce's EU-U.S. Privacy Shield program, meeting the European Commission's Directive on Data Protection. For more information about the U.S. Department of Commerce U.S. Privacy Shield program, see https://www.privacyshield.gov

FIPS 140-2 Validated

Keeper utilizes FIPS 140-2 validated encryption modules to address rigorous government and public sector security requirements. Keeper’s encryption has been certified by the NIST CMVP and validated to the FIPS 140 standard by accredited third party laboratories. Keeper has been issued certificate #3967 under the NIST CMVP. For the best FIPS experience use KCM version 2.9.6+ for improvements including:

• Improved FIPS compliance support for SSH and RDP connections

• Better log messaging when a compliant connection cannot be made

U.S. Department of Commerce Export Licensed Under EAR

Keeper is certified by the U.S. Department of Commerce Bureau of Industry and Security under Export Commodity Classification Control Number 5D992, in compliance with Export Administration Regulations (EAR). For more information about EAR: https://www.bis.doc.gov

24x7 Remote Monitoring

Keeper is monitored 24x7x365 by a global third-party monitoring network to ensure that our website and Cloud Security Vault are available worldwide. If you have any questions regarding this security disclosure, please contact us.

Phishing or Spoofed Emails

If you receive an email purporting to be sent from KSI and you are unsure if it is legitimate, it may be a “phishing email” where the sender's email address is forged or “spoofed”. In that case, an email may contain links to a website that looks like KeeperSecurity.com but is not our site. The website may ask you for your Keeper Security master password or try to install unwanted software on your computer in an attempt to steal your personal information or access your computer. Other emails contain links that may redirect you to other potentially dangerous web sites. The message may also include attachments, which typically contain unwanted software called "malware." If you are unsure about an email received in your inbox, you should delete it without clicking any links or opening any attachments. If you wish to report an email purporting to be from KSI that you believe is a forgery or you have other security concerns involving other matters with KSI, please contact us.

Hosting Infrastructure Certified to the Strictest Industry Standards

Keeper Connection Manager is hosted by the customer. The Keeper website and cloud storage runs on secure Amazon Web Services (AWS) cloud computing infrastructure. The AWS cloud infrastructure which hosts Keeper's system architecture has been certified to meet the following third-party attestations, reports and certifications:

• SOC 1 / SSAE 16 / ISAE 3402 (SAS70)

• SOC 2

• SOC 3

• PCI DSS Level 1

• ISO 27001, 27017 and 27018

• FedRamp

• DIACAP

• FISMA

• ITAC

• FIPS 140-2

• CSA

• MPAA

Vulnerability Reporting and Bug Bounty Program

Keeper Security is committed to the industry best practice of responsible disclosure of potential security issues. We take your security and privacy seriously and, we are committed to protecting our customers’ privacy and personal data. KSI’s mission is to build world’s most secure and innovative security apps, and we believe that bug reports from the worldwide community of security researchers is a valuable component to ensuring the security of KSI’s products and services.

Keeping our users secure is core to our values as an organization. We value the input of good-faith researchers and believe that an ongoing relationship with the cybersecurity community helps us ensure their security and privacy, and makes the Internet a more secure place. This includes encouraging responsible security testing and disclosure of security vulnerabilities.

The Keeper Connection Manager team actively monitors the upstream Apache Guacamole project for newly-disclosed security vulnerabilities, and has procedures in place for releasing security updates outside the normal release cycle. Should a vulnerability be found in Guacamole, the patch for that vulnerability will made be immediately available through the Keeper Connection Manager repository, and can be applied automatically using the upgrade process based on your installation method.

Guidelines

Keeper's Vulnerability Disclosure Policy sets out expectations when working with good-faith researchers, as well as what you can expect from us.

If security testing and reporting is done within the guidelines of this policy, we:

• Consider it to be authorized in accordance with Computer Fraud and Abuse Act,

• Consider it exempt from DMCA, and will not bring a claim against you for bypassing any security or technology controls,

• Consider it legal, and will not pursue or support any legal action related to this program against you,

• Will work with you to understand and resolve the issue quickly, and

• Will recognize your contributions publicly if you are the first to report the issue and we make a code or configuration change based on the issue.

If at any time you are concerned or uncertain about testing in a way that is consistent with the Guidelines and Scope of this policy, please contact us at security@keepersecurity.com before proceeding.

To encourage good-faith security testing and disclosure of discovered vulnerabilities, we ask that you:

• Avoid violating privacy, harming user experience, disrupting production or corporate systems, and/or destroying data,

• Perform research only within the scope set out by the Bugcrowd vulnerability disclosure program linked below, and respect systems and activities which are out-of-scope,

• Contact us immediately at security@keepersecurity.com if you encounter any user data during testing, and

• You give us reasonable time to analyze, confirm and resolve the reported issue before publicly disclosing any vulnerability finding.

Submitting a Report

Keeper has partnered with Bugcrowd to manage our vulnerability disclosure program.

Please submit reports through [https://bugcrowd.com/keepersecurity].

Additional Information

Keeper Security utilizes best-in-class security with a Zero-Knowledge security architecture and Zero-Trust framework. Additional technical documentation about Keeper's Zero-Knowledge encryption model can be found at the links below:

Keeper Encryption Model

Secrets Manager Encryption Model

Security Disclosure Page

Product Documentation

System Status

Release Notes

Keeper is SOC 2 Type 2, ISO27001 certified, FedRAMP Authorized. Customers may request access to our certification reports, 3rd party penetration reports and technical architecture documentation with a signed mutual NDA.

Overview

The Auto Docker Method installs Docker and 4 containers (if you selected all options) which start up automatically after the installer completes:

• Database (MySQL or PostgreSQL depending on selection)

• Guacamole (Tomcat)

• Guacd

• SSL (NGINX)

The installer also creates a docker-compose.yml file that can be found in the filesystem:

/etc/kcm-setup/docker-compose.yml

This Docker Compose file is the configuration file which manages the multi-docker container system. If you need to make further changes to the environment, you can modify this file and restart the docker services using the kcm-setup.run script or by directly using Docker functionality.

Managing the Service

When using the Docker Simple Install method, the kcm-setup.run script can be used to manage the entire service and the underlying docker containers. The purpose of this script is to make management of the Keeper Connection Manager platform very simple.

Usage:

sudo ./kcm-setup.run [OPTIONS] [COMMAND] [ARG...]

Install, maintain, or uninstall Keeper Connection Manager automatically.

Shared Volume

When using the Auto Docker Install method, a shared volume is automatically added to store file transfers and session recordings. The created volumes are located at /var/lib/guacamole/ which contains the drives and recordings.

Keeper Connection Manager On-Prem

Keeper Connection Manager (KCM) On-Prem is an agentless remote desktop gateway that provides instant and secure access to desktops, servers, databases and web applications from a web browser.

Benefits of the KCM On-Prem platform:

• Self-hosted

• Agentless

• Lightning Fast and Responsive

• Simple Access Controls

• Customizable

• Works in air-gapped environments

Features include:

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

• Support for MySQL, PostgreSQL, SQL Server database protocols

• Support for web application protection through Remote Browser Isolation technology

• Session Recording and playback

• Privileged Session Management

• Multi-User Session Sharing

• Role-Based Access Controls

• MFA Options: TOTP, Duo

• PIV/CAC smart card authentication

• SSO, OpenID Connect, Active Directory, LDAP Integration

• Custom Branding

Video Overview

System Diagram

Keeper is typically deployed as a Docker container. 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.

KeeperPAM Licensing

Keeper Connection Manager on-prem is included in your license of KeeperPAM. KeeperPAM is a modern, cloud-based privileged access management platform. Learn more about KeeperPAM at the links below:

• KeeperPAM Website

Getting Started

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

Update Instructions

From the Linux command line, update to the latest installer script using the curl command.

curl -O https://keepersecurity.com/kcm/kcm-setup.run

To update all of the underlying software and Docker containers when using the Docker Automated Install method, run the below commands:

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

Select "Y" when prompted.

Once the upgrade is complete, the service is started again automatically after a minute.

If you run into any issues during the upgrade, see Troubleshooting

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

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.

However, if you would like to use your own certificate obtained by a different CA, you can do so by choosing (option 2) during the installation prompt.

If you would like to use your own certificate, Keeper Connection Manager installation will prompt you to enter the full path and file name first for your .crt file, and next for your .pem file. Make sure to transfer these files to your server before beginning installation.

Select an Install Method

Keeper Connection Manager can be installed using one of the following methods.

Option 1: Auto Docker Install

An automated installer script is available for Linux which performs several of the Docker setup steps, such as generating a Docker Compose file, setting up SSL certificates and other options.

This method is recommended for users who are new to Docker and prefer Linux.

Option 2: Docker Compose Install

This advanced and customized Docker install for Keeper Connection Manager provides the Docker Compose file to deploy in any Docker environment with support for additional packages such as SSO, LDAP, TOTP and more.

This method is required for Windows and recommended for users who are familiar with Docker.

For convenience, Docker images for both MySQL and PostgreSQL are provided which automatically initialize themselves using the Apache Guacamole database schema:

Each of these images:

• Is based off Docker's official images for the same databases, and thus each accepts the same core environment variables.

• Accepts a common set of Guacamole-specific environment variables defining the name to be used for Guacamole's database and the reduced-privilege credentials to be used by Guacamole to execute queries.

• Requires the same ACCEPT_EULA environment variable as the keeper/guacamole and keeper/guacd images.

The images may be used as part of an entirely Dockerized deployment of Apache Guacamole, or separately as an easier method of deploying a functional, pre-initialized, and supported database. When combined with the keeper/guacamole and keeper/guacd images using docker-compose, an entire deployment of Apache Guacamole can be created and managed using a single docker-compose.yml.

Image: keeper/guacamole-db-mysql

keeper/guacamole-db-mysql is a Dockerized deployment of MySQL, built off Docker's official MySQL image which is automatically initialized with the Apache Guacamole database schema. It is built using the packages provided by Keeper Connection Manager and made available under the same EULA. It is normally used to provide a MySQL database for a container using the keeper/guacamole image.

Environment variables

In addition to the environment variables documented below, all environment variables supported by the official Docker MySQL image are accepted, as the official MySQL image forms the basis of this image.

ACCEPT_EULA

The ACCEPT_EULA environment variable must be set to "Y" to indicate your acceptance of the Keeper Connection Manager EULA. This Docker image may not be used except under the terms of the EULA.

MYSQL_RANDOM_ROOT_PASSWORD

This is an optional variable. Set to a non-empty value, like yes, to generate a random initial password for the root user (using pwgen). The generated root password will be printed to stdout (GENERATED ROOT PASSWORD: .....).

GUACAMOLE_DATABASE

The name of the database to create and initialized for use with Apache Guacamole. This environment variable is required and ultimately maps to the MYSQL_DATABASE environment variable of the official MySQL image.

The GUACAMOLE_DATABASE variable is provided here for consistency with the other Guacamole-specific variables, but may be omitted if MYSQL_DATABASE is provided.

GUACAMOLE_ADMIN_PASSWORD

This is the Administrator password for the guacadmin user.

GUACAMOLE_USERNAME and GUACAMOLE_PASSWORD

The username and password to use for the MySQL database user specific to the Guacamole web application. This pair of variables differ from the MYSQL_USER and MYSQL_PASSWORD environment variables provided by the official MySQL image in that the created user has limited privileges, being granted only what privileges are absolutely required for Guacamole to run.

The GUACAMOLE_USERNAME and GUACAMOLE_PASSWORD are not strictly required, as the user created with MYSQL_USER and MYSQL_PASSWORD may be used instead, however they are strongly recommended to ensure the Principle of Least Privilege is followed.

Docker secrets

Rather than pass data directly in environment variables, a _FILE suffix may be added to any environment variable supported by this image to force that variable to be read from the named file within the container. As Docker secrets store sensitive data within files beneath /run/secrets/ within the container, this can be used to load sensitive data from Docker secrets.

For example, to load the username and password for the limited-privilege user specific to the Guacamole web application from Docker secrets:

docker run --name some-guacamole-db \
    -e ACCEPT_EULA=Y \
    -e MYSQL_RANDOM_ROOT_PASSWORD=yes \
    -e GUACAMOLE_ADMIN_PASSWORD=some_password \
    -e GUACAMOLE_DATABASE=guacamole_db \
    -e GUACAMOLE_USERNAME_FILE=/run/secrets/mysql-username \
    -e GUACAMOLE_PASSWORD_FILE=/run/secrets/mysql-password \
    -d keeper/guacamole-db-mysql

Supported Operating Systems:

The recommended method to install Keeper Connection Manager is via the automated docker install. This removes any operating system, system pre-requisites and other requirements. If the underlying system supports a current version of Docker, the container is fully supported.

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:

Minimum 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.

Image: keeper/guacamole

To activate advanced features of Keeper Connection Manager, you simply add an environmental variable to the docker file that controls the feature, or you add one of the EXTENSIONS flags as documented below.

Arbitrary third-party extensions may be used through volume mounts and setting ADDITIONAL_GUACAMOLE_PROPERTIES variables as needed.

• Environment variables

  • ACCEPT_EULA

  • KCM_LICENSE

  • ADDITIONAL_GUACAMOLE_PROPERTIES

  • ALLOWED_LANGUAGES

  • API_*

  • AWS_DISCOVERY_*

  • BAN_*

  • CA_CERTIFICATES

  • CATALINA_OPTS

  • CONTEXT_PATH

  • DUO_*

  • EXTENSIONS

  • EXTENSION_PRIORITY

  • GUACD_*

  • JSON_*

  • KSM_*

  • LDAP_*

  • LOG_LEVEL

  • MYSQL_*

  • OPENID_*

  • POSTGRES_*

  • REQUIRE_ACCOUNT_APPROVAL

  • SAML_*

  • SQLSERVER_*

  • SSL_*

  • TOTP_*

  • UDS_*

  • USER_MAPPING

  • USE_DEFAULT_BRANDING

  • USE_SHM

• Docker secrets

Viewing the Guacamole logs

The Guacamole logs are useful if debugging unexpected behavior of the aspects of the web application which are not directly related to remote desktop, including authentication. To view the Tomcat/Guacamole logs follow the troubleshooting documentation.

By default, these logs will show messages only at the "info" level or above. This can be overridden when the container is created using the LOG_LEVEL environment variable.

Environment variables

ACCEPT_EULA

The ACCEPT_EULA environment variable must be set to "Y" to indicate your acceptance of the Keeper Connection Manager EULA. This Docker image may not be used except under the terms of the EULA.

KCM_LICENSE

The KCM_LICENSE environment variable contains the license key provided by Keeper support.

ADDITIONAL_GUACAMOLE_PROPERTIES

This variable is optional and specifies any additional content that should be appended to /etc/guacamole/guacamole.properties during startup. This content is added via guacamole.properties.docker, thus environment variable substitution will be automatically performed on the content of this variable.

ALLOWED_LANGUAGES

This variable is optional and restricts the display languages within Guacamole to the comma-separated list of language keys. If specified, only the listed languages will be made available to the user, and only the listed languages will be selected from automatically based on the user's browser's preferred language. For example, to restrict Guacamole to only English and German, specify ALLOWED_LANGUAGES="en, de". As English is the fallback language, used whenever a translation key is missing from the chosen language, English should only be omitted from this list if you are absolutely positive that no strings are missing from your custom translations.

By default, all defined languages will be available.

API_*

All environment variables which start with API_ correspond to configuration properties for configuring the Guacamole web application as a whole. These variables control how Guacamole handles user sessions and any HTTP requests that it receives. Note that these variables control only aspects of the Guacamole web application. They do not control the behavior of remote desktop sessions.

AWS_DISCOVERY_*

All environment variables which start with AWS_DISCOVERY_ correspond to configuration properties for AWS EC2 discovery which would normally be specified within guacamole.properties.

The following environment variables are required if using EC2 discovery:

Other, optional environment variables are available for the other properties related to EC2 discovery:

BAN_*

All environment variables which start with BAN_ correspond to configuration properties for configuring how apparent brute-force authentication attempts against the web application are automatically blocked. Each of these variables is optional.

CA_CERTIFICATES

This variable is optional and specifies the contents of one or more certificates used by your internal certificate authority (CA), in PEM form. When specified, SSL/TLS connections to other servers will be verified against these certificates, including connections to LDAP servers that use SSL/TLS.

CATALINA_OPTS

This variable is optional and specifies arbitrary command-line options that should be passed to the JVM running Tomcat. It corresponds to Tomcat's own CATALINA_OPTS environment variable and is primarily used to pass additional system properties to the JVM, as may be necessary to configure platform-level options like whether an HTTP proxy should be used.

For example, if you wish to ensure that all outbound HTTPS connections go through an HTTP proxy, including API calls to services like Keeper Secrets Manager (KSM), you would set CATALINA_OPTS to:

-Dhttps.proxyHost=my.proxy -Dhttps.proxyPort=3129

where "my.proxy" is the hostname or IP address of the desired HTTP proxy and "3129" is its TCP port number.

CONTEXT_PATH

This variable is optional and specifies the path that the Guacamole web application should be served under. By default, the web application will be served at the root directory (http://your-container:8080/), but this can be overridden by setting CONTEXT_PATH to the name of a different location.

Note that the location specified with CONTEXT_PATH may not contain slashes. If you need to serve the web application beneath a more complex nested path, you will need to use a reverse proxy like Nginx or Apache HTTPD.

DUO_*

The following environment variables are required if using Duo multi-factor authentication:

EXTENSIONS

This variable is optional and specifies a comma- or newline-separated list of the names of all extensions that should be activated in the image, regardless of which other environment variables may be specified. Empty names, whitespace, and trailing commas are ignored.

Extension names are dictated by the guacamole(*) package capability of the corresponding Keeper Connection Manager package (part of the RPM package's metadata):

This variable is mainly of use for extensions which can be used without setting any configuration options, like TOTP two-factor authentication, or to force sanity checks on the presence of required environment variables even if all associated variables might be accidentally omitted. Extensions not listed within this environment variable will still be included if any of their corresponding environment variables are set.

EXTENSION_PRIORITY

This variable is optional and specifies the order that extensions should be loaded relative to each other. By default, extensions are loaded in alphabetical order based on their filenames.

To override the load order of extensions, list the names of each extension that should be loaded first, separated by commas. The special name * may be used as a placeholder for all other extensions. For example:

GUACD_*

TCP connection information for guacd.

Other, optional environment variables are available for configuring other aspects of the connection to guacd:

JSON_*

All environment variables which start with JSON_ correspond to configuration properties for encrypted JSON authentication which would normally be specified within guacamole.properties.

The following environment variables are required if using encrypted JSON authentication:

Other, optional environment variables are available for the other properties related to encrypted JSON authentication:

KSM_*

All environment variables which start with KSM_* correspond to configuration properties for Keeper Secrets Manager. See the Keeper Vault Integration guide.

LDAP_*

All environment variables which start with LDAP_ correspond to configuration properties for LDAP authentication which would normally be specified within guacamole.properties.

The following environment variables are required if using LDAP authentication (for a single LDAP server):

If using multiple LDAP servers, or if you prefer to provide LDAP server configuration in YAML format, the following environment variable is required:

Other, optional environment variables are available for the other properties related to LDAP authentication:

LOG_LEVEL

This variable is optional and specifies the lowest level of log message that should be displayed. In order of increasing verbosity, valid values are: "error", "warn", "info", "debug", "trace".

The default log level is "info".

MYSQL_*

All environment variables which start with MYSQL_ correspond to configuration properties for MySQL authentication which would normally be specified within guacamole.properties.

If intending to use MySQL, you may wish to use the keeper/guacamole-db-mysql image which provides a MySQL database that is automatically initialized for use by Guacamole.

The following environment variables are required if using MySQL authentication:

Other, optional environment variables are available for the other properties related to MySQL authentication:

OPENID_*

All environmental variables which start with OPENID_ correspond to configuration properties for Open ID Connect authentication which would normally be specified within guacamole.properties.

Optional variables:

POSTGRES_*

All environment variables which start with POSTGRES_ correspond to configuration properties for PostgreSQL authentication which would normally be specified within guacamole.properties.

If intending to use PostgreSQL, you may wish to use the keeper/guacamole-db-postgres image which provides a PostgreSQL database that is automatically initialized for use by Guacamole.

The following environment variables are required if using PostgreSQL authentication:

Other, optional environment variables are available for the other properties related to PostgreSQL authentication:

REQUIRE_ACCOUNT_APPROVAL

This variable is optional and specifies the extensions that should require explicit approval from an administrator on a per-account basis before they can be used to authenticate a user. By default, any installed authentication method may be used.

To require approval for particular authentication methods, list the names of each extension that should require approval, separated by commas. For example:

SAML_*

All environment variables which start with SAML_ correspond to configuration properties for SAML Authentication which would normally be specified within guacamole.properties.

The following environment variables are required if using SAML authentication:

Optional environmental variables:

SQLSERVER_*

All environment variables which start with SQLSERVER_ correspond to configuration properties for SQL Server authentication which would normally be specified within guacamole.properties.

The following environment variables are required if using SQL Server authentication:

Other, optional environment variables are available for the other properties related to SQL Server authentication:

SSL_*

All environment variables which start with SSL_ correspond to configuration properties for SSL/TLS client authentication (smart card authentication) which would normally be specified within guacamole.properties.

The following environment variables are required if using SSL/TLS client authentication:

Other, optional environment variables are available for the other properties related to SSL/TLS client authentication:

TOTP_*

All environment variables which start with TOTP_ correspond to configuration properties for TOTP multi-factor authentication which would normally be specified within guacamole.properties.

UDS_*

All environment variables which start with UDS_ correspond to configuration properties for integrating with UDS Enterprise that would normally be specified within guacamole.properties.

USER_MAPPING

This variable is optional and specifies the full contents of the /etc/guacamole/user-mapping.xml file that can be used to test a Guacamole deployment without configuring a more complex authentication method like MySQL, PostgreSQL, or LDAP. This is the authentication mechanism described within the Keeper Connection Manager installation instructions.

As the contents of this file are inherently sensitive, the file will be stored purely in memory (within /dev/shm) unless the USE_SHM environment variable is set to "N" as documented below.

USE_DEFAULT_BRANDING

Keeper Connection Manager ships with its own default branding. If you will be using your own custom branding, the optional USE_DEFAULT_BRANDING environment variable should be set to "N" to disable the Keeper branding and avoid conflicts with your branding extension.

USE_SHM

This variable is optional and may be used to force storage of known sensitive files on disk rather than in memory. To force storage to disk, set USE_SHM to "N".

By default, the keeper/guacamole image stores the contents of files that are known to be sensitive within /dev/shm, thus storing those files only in memory and without potentially persisting sensitive data to disk. As such files are generated by the Docker image from environment variables during startup, this is particularly useful if Docker secrets are being used.

Docker secrets

Rather than pass data directly in environment variables, a _FILE suffix may be added to any environment variable supported by this image to force that variable to be read from the named file within the container. For example, to read /etc/guacamole/user-mapping.xml from a file:

docker run --name some-guacamole \
    -e ACCEPT_EULA=Y \
    -e GUACD_HOSTNAME=some-guacd \
    -e USER_MAPPING_FILE=/some/volume/mount/user-mapping.xml \
    -d keeper/guacamole

As Docker secrets store sensitive data within files beneath /run/secrets/ within the container, this can be used to load sensitive data from Docker secrets:

docker run --name some-guacamole \
    -e ACCEPT_EULA=Y \
    -e GUACD_HOSTNAME=some-guacd \
    -e MYSQL_HOSTNAME=some-mysql \
    -e MYSQL_DATABASE=guacamole_db \
    -e MYSQL_USERNAME_FILE=/run/secrets/mysql-username \
    -e MYSQL_PASSWORD_FILE=/run/secrets/mysql-password \
    -d keeper/guacamole

For convenience, a Docker image for SSL termination using NGINX is provided which automatically configures itself with an SSL certificate:

This image:

• Is based off Docker's official image for NGINX, and thus each accepts the same core environment variables.

• Accepts a set of Keeper-specific environment variables defining the Guacamole instance that will be behind SSL termination.

• Can automatically retrieve a certificate from Let's Encrypt, generate its own self-signed certificate for testing, or use an existing certificate that you have already obtained from a certificate authority.

• Requires the same ACCEPT_EULA environment variable as the keeper/guacamole and keeper/guacd images.

See the next section to view configuration examples.

This page provides details on how to create an SSL certificate for use with the Keeper Connection Manager service.

Generate and Prepare the SSL Certificate

The process of generating an SSL certificate varies depending on the provider, but the general flow is documented here.

(1) On your local workstation, Generate a private key

openssl genrsa -out demo3.kcmdemo.com.key

(2) Generate a CSR, making sure to use the hostname which you plan to use for KCM. In this case, we will be using demo3.kcmdemo.com. The important item here is that the Common Name matches exactly to the domain.

openssl req -new -key demo3.kcmdemo.com.key -out demo3.kcmdemo.com.csr

(3) Purchase an SSL certificate and Submit the CSR to your SSL certificate provider.

If you don't have a provider already, a good site is: https://www.ssls.com/

Create a certificate for a domain that is specific for this KCM instance, e.g. demo3.kcmdemo.com. The SSL certificate provider will deliver you a zip file that contains a signed certificate (.crt file) and intermediate CA cert.

(4) After the certificate has been issued, combine the certificate (.crt) and bundle (bundle.crt) into a single file that is PEM-encoded.

The file needs to be formatted like this:

-----BEGIN CERTIFICATE-----
MIIGQjCCBSqgAwIBAgIQeLDY2eR6ZdAagFwb7A/YxzANBgkqhkiG9w0BAQsFADCB
jzELMAkGA1UEBhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G
A1UEBxMHU2FsZm9yZDEYMBYGA1UEChMPU2VjdGlnbyBMaW1pdGVkMTcwNQYDVQQD
.....
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIGEzCCA/ugAwIBAgIQfVtRJrR2uhHbdBYLvFMNpzANBgkqhkiG9w0BAQwFADCB
iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl
yOGBQMkKW+ESPMFgKuOXwIlCypTPRpgSabuY0MLTDXJLR27lk8QyKGOHQ+SwMj4K
00u/I5sUKUErmgQfky3xxzlIPK1aEn8=
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFgTCCBGmgAwIBAgIQOXJEOvkit1HX02wQ3TE1lTANBgkqhkiG9w0BAQwFADB7
MQswCQYDVQQGEwJHQjEbMBkGA1UECAwSR3JlYXRlciBNYW5jaGVzdGVyMRAwDgYD
...
-----END CERTIFICATE-----

Note that a newline exists after each "END CERTIFICATE" line. KCM will reject a malformed certificate.

The private key file will be PEM-encoded, formatted like this:

-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBBAKCAQDAvzLIMM7MnVa7z/CTLm+dTnxcd9Rn0QOVdIRIHbQnoBQ9irv6
lgNp8pnpIKp/WPcvoNKEZND08CX8Ylxbw51ccoERNBPtvyXbJtfIFu81nplqr+Lt
....
eABEVrVcYwO10apQQ0lkXWyYhTS0WuB1wFZlIiFq7RJg2X7s9tmVMw==
-----END RSA PRIVATE KEY-----

(5) Transfer the 2 files to the KCM server

Copy the files to a location in the server which is running Keeper Connection Manager.

If you are using the Auto Docker install method of Keeper Connection Manager, a good place to put the files is in /etc/kcm-setup. Make sure to set the permissions appropriately, e.g.:

sudo mv demo3.kcmdemo.com_bundle.crt /etc/kcm-setup/
sudo mv demo3.kcmdemo.com.key /etc/kcm-setup/

sudo chmod 600 /etc/kcm-setup/demo3.kcmdemo.com_bundle.crt
sudo chmod 600 /etc/kcm-setup/demo3.kcmdemo.com.key

chown root:root /etc/kcm-setup/demo3.kcmdemo.com_bundle.crt
chown root:root /etc/kcm-setup/demo3.kcmdemo.com.key

(6) Update the docker-compose.yml file with the SSL cert

Using your preferred editor, update the Docker Compose file. If you used the Auto Docker install method of KCM, the file will be located in /etc/kcm/setup/docker-compose.yml. The section to edit is below:

sudo vi /etc/kcm-setup/docker-compose.yml

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            CERTIFICATE_FILE: "/etc/ssl/certs/certificate.pem"
            PRIVATE_KEY_FILE: "/etc/ssl/certs/private.pem"
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: "guacamole"
            SSL_HOSTNAME: "demo3.kcmdemo.com"
        volumes:
            - "/etc/kcm-setup:/etc/ssl/certs/:ro"

Make sure to edit the SSL_HOSTNAME and volume mount paths and filenames.

To restart the service with the new certificate:

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

Annual Renewal

Image: keeper/guacd

keeper/guacd is a Dockerized deployment of guacd, the Apache Guacamole proxy daemon, with support for VNC, RDP, SSH, K8s, MySQL, PostgreSQL, SQL Server and telnet. It is normally used to provide a guacd instance for a container using the keeper/guacamole image.

Starting a guacd instance

To start a guacd instance which listens on TCP port 4822:

docker run --name some-guacd -e ACCEPT_EULA=Y -d keeper/guacd

where some-guacd is the name you wish to assign to your container.

Viewing the guacd logs

The guacd logs are useful if debugging unexpected behavior of the remote desktop or failure to connect, as it is guacd that handles protocol-specific communication. To view the guacd logs:

docker logs some-guacd

By default, these logs will show messages only at the "info" level or above. This can be overridden when the container is created using the LOG_LEVEL environment variable.

Environment variables

ACCEPT_EULA

The ACCEPT_EULA environment variable must be set to "Y" to indicate your acceptance of the Keeper Connection Manager EULA. This Docker image may not be used except under the terms of the EULA.

CA_CERTIFICATES

This variable is optional and specifies the contents of one or more certificates used by your internal certificate authority (CA), in PEM form. When specified, SSL/TLS connections to other servers will be verified against these certificates, including connections to RDP servers and Remote Browser Isolation sessions that use SSL/TLS.

Below is an example guacd section of docker-compose.yml with 2 certificates:

    guacd:
        image: keeper/guacd:2
        restart: unless-stopped
        shm_size: 1001500k
        security_opt:
            - "seccomp:/etc/kcm-setup/guacd-docker-seccomp.json"
        environment:
            ACCEPT_EULA: "Y"
            CA_CERTIFICATES: |
              -----BEGIN CERTIFICATE-----
              MIIEczCCA1ugAwIBAgIBADANBgkqhkiG9w0BAQQFAD..AkGA1UEBhMCR0Ix
              EzARBgNVBAgTClNvbWUtU3RhdGUxFDASBgNVBAoTC0..0EgTHRkMTcwNQYD
              VQQLEy5DbGFzcyAxIFB1YmxpYyBQcmltYXJ5IENlcn..XRpb24gQXV0aG9y
              aXR5MRQwEgYDVQQDEwtCZXN0IENBIEx0ZDAeFw0wMD..TUwMTZaFw0wMTAy
              -----END CERTIFICATE-----
              -----BEGIN CERTIFICATE-----
              MIIEczCCA1ugAwIBAgIBADANBgkqhkiG9w0BAQQFAD..AkGA1UEBhMCR0Ix
              EzARBgNVBAgTClNvbWUtU3RhdGUxFDASBgNVBAoTC0..0EgTHRkMTcwNQYD
              VQQLEy5DbGFzcyAxIFB1YmxpYyBQcmltYXJ5IENlcn..XRpb24gQXV0aG9y
              aXR5MRQwEgYDVQQDEwtCZXN0IENBIEx0ZDAeFw0wMD..TUwMTZaFw0wMTAy
              -----END CERTIFICATE-----
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

GUACD_UID

This variable is optional and specifies the numeric UID which should be assigned to the user that the guacd service runs as. If omitted, the guacd service will run with the UID of the reduced-privilege user created by the Keeper Connection Manager package for guacd.

This is mainly useful if guacd will need to write to a volume mount whose file permissions may not match those of the keeper/guacd Docker image.

GUACD_GID

This variable is optional and specifies the numeric GID which should be assigned to the group that the guacd service runs as. If omitted, the guacd service will run with the GID of the reduced-privilege group created by the Keeper Connection Manager package for guacd.

This is mainly useful if guacd will need to write to a volume mount whose file permissions may not match those of the keeper/guacd Docker image.

LOG_LEVEL

This variable is optional and specifies the lowest level of log message that should be displayed. In order of increasing verbosity, valid values are: "error", "warning", "info", "debug", "trace".

The default log level is "info".

AUTOFILL_RULES

This variable is optional and specifies the full contents of the /etc/guacamole/autofill-rules.yml file that can be used to configure autofill of username/password in the Remote Browser Isolation protocol.

Image: keeper/guacamole-ssl-nginx

keeper/guacamole-ssl-nginx is a Dockerized deployment of NGINX, built off Docker's official Nginx image which is pre-configured to provide SSL termination for Guacamole. It supports:

• Automatic retrieval of a certificate from Let's Encrypt.

• Automatic generation of a self-signed certificate.

• Usage of an existing certificate that you have already obtained from a certificate authority.

This image is produced as part of Keeper Connection Manager and made available under the same EULA. It is normally used to provide SSL termination for a container using the keeper/guacamole image.

Supported Types of SSL certificates

The keeper/guacamole-ssl-nginx supports several mechanisms for generating, retrieving, or using existing SSL certificates. The mechanism used depends on which environment variables are specified when the Docker container is created.

In addition to these mechanism-specific environment variables, there is a set of environment variables that must always be specified:

• ACCEPT_EULA - Whether you accept the Keeper Connection Manager EULA (acceptance of the EULA is required to use the image).

• GUACAMOLE_HOSTNAME - The hostname/address of the Guacamole instance.

• SSL_HOSTNAME - The public domain name that will be used to access Guacamole.

Let's Encrypt

Let's Encrypt is used by default if no existing certificate is supplied and generation of a self-signed certificate is not requested. The keeper/guacamole-ssl-nginx image will reach out to the Let's Encrypt service using the "certbot" tool to retrieve an SSL certificate.

Only one environment variable specific to Let's Encrypt is strictly required if using Let's Encrypt certificates:

• LETSENCRYPT_ACCEPT_TOS - Whether you accept the Let's Encrypt Terms of Service (acceptance of Let's Encrypt's Terms of Service is required to use that service).

In addition to accepting their Terms of Service, beware that Let's Encrypt strongly recommends providing an email address so that you can get important alerts regarding your certificate. You should additionally provide an email address unless you have a reason not to do so:

• LETSENCRYPT_EMAIL - The email address to submit to Let's Encrypt when requesting the certificate.

If you are just testing usage of Let's Encrypt, you should use the Let's Encrypt staging/testing environment instead of the production environment:

• LETSENCRYPT_STAGING - Set to "Y" to use Let's Encrypt's staging environment instead of production.

The retrieved certificate be automatically renewed by the image when necessary. If retrieval fails, the container will stop, details describing the failure will be logged, and the process will be retried the next time the container starts.

The keeper/guacamole-ssl-nginx image leverages Docker volumes to enable Let's Encrypt certificates and state to persist across container recreation.

For example, below will generate a Let's Encrypt certificate in your docker-compose.yml file:

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            LETSENCRYPT_ACCEPT_TOS: "Y"
            LETSENCRYPT_EMAIL: "you@company.com"

Existing certificate from an arbitrary CA

If you already have a certificate that you obtained from a certificate authority, you can use that certificate by pointing to the relevant files with the CERTIFICATE_FILE and PRIVATE_KEY_FILE environment variables. The relevant files will need to be exposed to the image using Docker volume mounts.

• CERTIFICATE_FILE - The full path to the certificate PEM file.

• PRIVATE_KEY_FILE - The full path to the private key PEM file.

When your certificate comes up for renewal with your CA, you will need to replace the certificate and private key and reload NGINX. Stop and start the Docker Compose after the certificate has been updated.

For Docker Compose configuration, the example below will load a custom certificate from a shared volume that will hold the keys.

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            CERTIFICATE_FILE: "/path/in/container/mycert.pem"
            PRIVATE_KEY_FILE: "/path/in/container/mykey.pem"
        volumes:
            - "/local/path/to/keys:/path/in/container/"

Self-signed Certificates

If deploying for testing, the image can automatically generate and maintain its own self-signed certificate:

• SELF_SIGNED - Set to "Y" to automatically generate a self-signed certificate for testing.

The keeper/guacamole-ssl-nginx image will regenerate the self-signed certificate on startup. As the certificate expires 30 days after generation, the image will also automatically regenerate the certificate every 21 days to ensure it does not expire.

The certificate expiration date and fingerprints will be logged each time the certificate is regenerated, allowing rudimentary server identity verification.

Environment Variables

In addition to the environment variables documented below, all environment variables supported by the official Docker Nginx image are accepted, as the official NGINX image forms the basis of this image.

ACCEPT_EULA

The ACCEPT_EULA environment variable must be set to "Y" to indicate your acceptance of the Keeper Connection Manager EULA. This Docker image may not be used except under the terms of the EULA.

SSL_HOSTNAME

The public-facing hostname of the server hosting Docker. This environment variable is required and should be the full public domain name that will be used to access Guacamole over the internet, already associated with the IP address that reaches the server running Docker and this image.

GUACAMOLE_HOSTNAME

The internal hostname or IP address of the Guacamole server. This environment variable is required, and should be the hostname/address that NGINX will connect to internally when servicing connections.

Note that the Guacamole service whose hostname/address is provided here should be reachable only on the internal network. Only the SSL terminating service (this image) should be public-facing.

GUACAMOLE_PORT

The TCP port number that the Guacamole server is listening on. This environment variable is optional. If omitted, the typical port 8080 will be used by default.

GUACAMOLE_CONTEXT_PATH

The path that Guacamole is being served beneath. This environment variable is optional. By default, this will be blank, representing that Guacamole is being served from the root path. As with the GUACAMOLE_CONTEXT_PATH environment variable of the keeper/guacamole image, this parameter may not contain slashes.

For example, if Guacamole is running internally at http://some-host/guacamole/, you would set GUACAMOLE_CONTEXT_PATH to guacamole.

SELF_SIGNED

If set to "Y", requests that a self-signed certificate be automatically generated for SSL_HOSTNAME rather than using an existing certificate or retrieving a new certificate from Let's Encrypt.

Self-signed certificates are inherently insecure. This option should be used only for testing.

CERTIFICATE_FILE and PRIVATE_KEY_FILE

The paths of the PEM files for the SSL certificate and associated private key, respectively. These paths are relative to the filesystem of the Docker container. Externally-provided SSL certificate PEM files will need to be exposed within the container using Docker volume mounts.

These environment variables are only required if providing your own certificate. They will be ignored if using a self-signed certificate for testing with SELF_SIGNED.

LETSENCRYPT_ACCEPT_TOS

If intending to use Let's Encrypt, the LETSENCRYPT_ACCEPT_TOS environment variable must be set to "Y" to indicate your acceptance of the Let's Encrypt Terms of Service. Let's Encrypt cannot be used unless you agree to the relevant Terms of Service.

This environment variable is only required if using Let's Encrypt. It is ignored if providing your own certificate using CERTIFICATE_FILE and PRIVATE_KEY_FILE, or if using a self-signed certificate for testing with SELF_SIGNED.

LETSENCRYPT_EMAIL

The email address that should be provided to Let's Encrypt when requesting a certificate. This environment variable is optional and is ignored if providing your own certificate using CERTIFICATE_FILE and PRIVATE_KEY_FILE, or if using a self-signed certificate for testing with SELF_SIGNED.

While this environment variable is optional, beware that Let's Encrypt strongly recommends providing an email address when obtaining a certificate using their service. From the help content for the certbot tool:

... This is strongly discouraged, because in the event of key loss or account compromise you will irrevocably lose access to your account. You will also be unable to receive notice about impending expiration or revocation of your certificates. Updates to the Subscriber Agreement will still affect you, and will be effective 14 days after posting an update to the web site.

LETSENCRYPT_STAGING

If set to "Y", requests that the Let's Encrypt staging environment be used to retrieve an SSL certificate, rather than the production environment. This option should be used if you are just testing the Let's Encrypt functionality.

Content Security Policy (CSP)

Content Security Policy (CSP) is a browser feature that allows web applications like KCM to declare to the browser what types of operations should be allowed in the context of that web application. In particular, CSP allows web applications to request that the browser block attempts to load resources or run scripts that the web application considers unsafe or unexpected. This is done by adding a Content-Security-Policy header to HTTP responses.

A default Content-Security-Policy header with known-good default value is set automatically by the keeper/guacamole-ssl-nginx image unless configured otherwise using the CONTENT_SECURITY_POLICY environment variable.

CONTENT_SECURITY_POLICY

Configures the value of the Content-Security-Policy header that will be sent in responses from Nginx.

If set to "Y", a reasonable default Content-Security-Policy value will be set that's known to work with most KCM installations: script-src 'self' 'unsafe-eval'; default-src 'self' data:; style-src 'self' 'unsafe-inline';. This configuration allows loading of assets from the same domain as KCM, along with allowing eval() for translations, and allowing JavaScript to dynamically load CSS.

If set to "N", the header will not be added to responses.

If this variable is set to any other value, the literal value of the variable will be sent with the response.

HTTP Strict Transport Security (HSTS)

HTTP Strict Transport Security (HSTS) is a browser feature that allows the owners of a domain to advise browsers that connections should only use HTTPS, and that any HTTP connections should be upgraded to HTTPS before being sent.

STRICT_TRANSPORT_SECURITY

Configures the value of the Strict-Transport-Security header that will be sent in responses from Nginx.

If set to "Y", a reasonable default Strict-Transport-Security value will be set: 'max-age=31536000; includeSubDomains; preload;' always, as recommended by https://https.cio.gov/hsts/.

If set to "N", the header will not be added to responses.

If this variable is set to any other value, the literal value of the variable will be sent with the response.

Docker secrets

Rather than pass data directly in environment variables, a _FILE suffix may be added to any environment variable supported by this image to force that variable to be read from the named file within the container. As Docker secrets store sensitive data within files beneath /run/secrets/ within the container, this can be used to load sensitive data from Docker secrets.

For example, to load the Let's Encrypt account email from Docker secrets:

docker run --name some-guacamole-ssl \
    -e ACCEPT_EULA=Y \
    -e LETSENCRYPT_ACCEPT_TOS=Y \
    -e LETSENCRYPT_EMAIL_FILE=/run/secrets/letsencrypt-email \
    -d keeper/guacamole-ssl-nginx

Advanced Configuration

SSL_CIPHERS

Configures the allowable SSL ciphers for the Nginx instance. For information on the allowable values for this parameter, see the Nginx documentation. If not otherwise specified, the value will default to "HIGH:!aNULL:!MD5".

SSL_PROTOCOLS

Configures the allowable SSL protocols for the Nginx instance. For information on the allowable values for this parameter, see the Nginx documentation. If not otherwise specified, TLS 1.2 and 1.3 will be enabled.

SSL_EXTERNAL_PORT

Configures value of the X-Forwarded-Port header that will be sent to the KCM web application in requests from Nginx. This header advises the KCM server know that SSL requests are being received at a non-standard port.

If not specified, KCM will expect that inbound requests are coming from the standard HTTPS port (443).

ADDITIONAL_CONFIG

Arbitrary configuration for the server block that points at the KCM web application in the Nginx configuration files generated by this image.

This variable functions as a catch-all for applying Nginx configuration options that do not have corresponding environment variables in the keeper/guacamole-ssl-nginx image.

Any value provided via the ADDITIONAL_CONFIG environment variable will be included in the main server block pointing at the KCM web application. Only configuration options that Nginx will accept within a server block may be included here.

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

It is highly recommended to perform backups of the following components:

1. Server backup

2. Database snapshots

3. Docker compose and other critical files

Server Backup Instructions

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

• In most installations, a database running locally or within the Docker containers 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

• For Docker and Auto Docker install methods, the kcm-setup.run backup command will run a backup locally.

• For other installation methods, please use the database platform's backup features, for example mysqladmin on MySQL-backed installs.

Docker compose

• Back up and protect the files located in /etc/kcm-setup/ which include docker-compose.yml and any other files which are being utilized by your container.

When using the Auto Docker Install method, packages can be added by directly modifying the generated Docker Compose file. For example, adding SSO or LDAP support.

To modify your Keeper Connection Manager environment, you'll need to edit the docker-compose.yml file located here:

/etc/kcm-setup/docker-compose.yml

Applying Configuration Changes

The kcm-setup.run script has an apply feature which allows you to apply configuration changes without updating the containers. From the Linux command line, update to the latest installer script using the curl command.

curl -O https://keepersecurity.com/kcm/kcm-setup.run

Apply the changes

sudo ./kcm-setup.run apply

Update and Restart the Containers

To update the environment, use the kcm-setup.run upgrade command to update the containers and start with the latest configuration:

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

or.....

sudo su
cd /etc/kcm-setup/
docker-compose -p kcm up -d

Overview

Auto Docker Install is Keeper's recommended installation method.

Make sure to read the Preparing for Installation section first.

The Auto Docker Install method creates a standard Keeper Connection Manager environment using a script that is easy to run. This method does not restrict any features and you can still utilize this installation with advanced control at a later time.

If you are already familiar with Docker, you may choose to use the Docker Compose Install method.

Licensing

Before installing KCM 2.19 or later versions, please ensure you have a valid license key. Without a valid license key, users and administrators will be unable to use KCM after the update is applied

For more info, visit this page.

Installation

(1) Download the Installer

From the linux command line, download the installer script using the curl command.

curl -O https://keepersecurity.com/kcm/kcm-setup.run

(2) Add the execute permission to the Installer

chmod +x kcm-setup.run

(3) Run the Installer as root

sudo ./kcm-setup.run

The next question asks if you already have SSL termination available. If unsure, select N for no.

At the next prompt, enter your FQDN, even if it is internal. This is where users will access KCM in their browser.

Then, choose an option for SSL. A self-signed certificate (option 3) is okay for testing. After testing is complete, make sure to put a proper SSL certificate in place.

Secrets Manager Integration (optional)

The next prompt will be to choose your database, and then it will prompt for "Your one-time access token or base64 configuration". This value is generated from Keeper Secrets Manager (a tab in your vault). If this doesn't apply to you, just press enter. You can always add it later, too.

Set up SSO Login (optional)

Next up is SAML. You can choose "no" to skip it (you can come back and set it up later), or you can choose "yes" to set up SSO now. Follow the SSO setup steps here.

Save the creds and URL into a record in your Vault

After installation is completed, an admin login and password is created for you. Make sure to store this in your Keeper vault, as it's not provided again later.

Installation has completed successfully! You may now access your Keeper 
Connection Manager installation at:

    https://connection.mycompany.com/

The administrator credentials are:

    Username: guacadmin
    Password: **************************

Thank you for installing Keeper Connection Manager!

Navigate to the URL in your Browser

Now that the installation is complete, simply go to the URL/hostname that you designated. You'll be able to login as the guacadmin default user with the credentials provided at the completion of the installation.

Now that your Keeper Connection Manager instance is running, you can login as guacadmin and start setting up some connections. Need to import connections in bulk? Follow the steps here.

The next section of this documentation reviews the process of managing, upgrading and adding packages to the Docker Compose environment.

Overview

This section describes how to install Keeper Connection Manager using Docker by building a customized docker-compose orchestration file.

Step 1: Platform-specific Setup

Windows

Install Docker Desktop following Docker's official instructions.

Amazon Linux 2

Install Docker on your instance. A nice step by step guide is published here.

CentOS7, RHEL

In addition to installing Docker, please install the haveged package to ensure that the environment is capable of generating enough entropy for creating secure random numbers.

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

Ubuntu

Install the haveged package to ensure that the environment is capable of generating enough entropy for creating secure random numbers.

sudo apt-get install haveged

Step 2: Create Docker Compose File

Now that you have Docker running on your instance, you need to generate a docker-compose.yml file that must be transferred to a working directory on your machine.

An example docker-compose.yml file for a deployment of Keeper Connection Manager which uses Let's Encrypt for its SSL certificate and an automatically-initialized database for authentication is provided below with a MySQL and PostgreSQL option.

version: "3"
services:

    guacd:
        image: keeper/guacd:2
        restart: unless-stopped
        shm_size: 1001500k
        security_opt:
            - "seccomp:/etc/kcm-setup/guacd-docker-seccomp.json"
        environment:
            ACCEPT_EULA: "Y"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    db:
        image: keeper/guacamole-db-mysql:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            MYSQL_RANDOM_ROOT_PASSWORD: "yes"
            GUACAMOLE_DATABASE: guacamole_db
            GUACAMOLE_USERNAME: guacamole_user
            GUACAMOLE_PASSWORD: some_strong_password
            GUACAMOLE_ADMIN_PASSWORD: some_strong_password

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: guacd
            MYSQL_HOSTNAME: db
            MYSQL_DATABASE: guacamole_db
            MYSQL_USERNAME: guacamole_user
            MYSQL_PASSWORD: some_password
            KCM_LICENSE: "XXXXXXXXXXXXXXXXXXXXXXXXXX"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            LETSENCRYPT_ACCEPT_TOS: "Y"
            LETSENCRYPT_EMAIL: you@company.com

volumes:
    common-storage:

version: "3"
services:

    guacd:
        image: keeper/guacd:2
        restart: unless-stopped
        shm_size: 1001500k
        security_opt:
            - "seccomp:/etc/kcm-setup/guacd-docker-seccomp.json"
        environment:
            ACCEPT_EULA: "Y"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    db:
        image: keeper/guacamole-db-postgres:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            POSTGRES_PASSWORD: some_strong_password
            GUACAMOLE_DATABASE: guacamole_db
            GUACAMOLE_USERNAME: guacamole_user
            GUACAMOLE_PASSWORD: some_strong_password
            GUACAMOLE_ADMIN_PASSWORD: some_strong_password

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            POSTGRES_HOSTNAME: "db"
            POSTGRES_DATABASE: "guacamole_db"
            POSTGRES_USERNAME: "guacamole_user"
            POSTGRES_PASSWORD: "xxxxxxx"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            LETSENCRYPT_ACCEPT_TOS: "Y"
            LETSENCRYPT_EMAIL: you@company.com

volumes:
    common-storage:

Using a Custom SSL Certificate

If you plan to use a custom SSL certificate instead of Let's Encrypt, replace the "ssl" section of the Docker Compose file with a section that looks like this:

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            SELF_SIGNED: "N"
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: "guacamole"
            SSL_HOSTNAME: "keeper.mycompany.com"
            CERTIFICATE_FILE: "/var/lib/guacamole/your_certificate.pem"
            PRIVATE_KEY_FILE: "/var/lib/guacamole/your_private_key.key"
        volumes:
            - "C:\Users\Path\To\Cert:/var/lib/guacamole:ro"

In this case, CERTIFICATE_FILE is the PEM-encoded certificate including the intermediate certificate chain. The PRIVATE_KEY_FILE is the private key file.

Also, note that in the above snippet, there is a volume mount that assigns the local filesystem to the target container. You should only modify the C:\Users\Path\To\Cert portion of the string. On linux environments it will be /path/to/cert.

Step 3: Start the Docker Containers

On Windows, open a Command Prompt. On Linux, open the terminal shell. Navigate to the location of the docker-compose.yml file that was saved in step 2.

To start up the environment, simply type the below command:

docker compose up -d

Note: Some versions require "docker-compose" with a hyphen.

That's it. If everything is successful, you can open the Keeper Connection Manager login screen on the specified FQDN.

Important Notes

• If you have not set up a proper domain name routing to the server, you can temporarily host-hack the local system in order to at least access the user interface and start testing.

• If you're using your own SSL certificate, we don't recommend using a wildcard cert. A certificate that has been explicitly created for the Keeper Connection Manager endpoint is the best practice since you'll be storing the SSL private key on the device.

• If you're using Windows, you will need to modify your Windows Defender Firewall to open up ports 443 to the Docker service.

• Running docker compose down will delete all data in the container including users, connections and history. To simply stop the containers, use docker compose stop.

Remote Browser Isolation Configuration

If you plan to use remote browser isolation, you'll need to create a seccomp security profile for the guacd container. For a new installation of Keeper Connection Manager, the kcm-setup.run script automatically handles this for you and places the file called guacd-docker-seccomp.json in the folder /etc/kcm-setup/ on the instance.

If this file is not automatically created, or you are upgrading an instance to use remote browser isolation, you may need to create the file manually.

You can obtain a copy of the file directly from the guacd Docker image once your docker containers are updated and running. For example, the following prints the contents of that file to a terminal:

docker run --rm --entrypoint=/bin/cat keeper/guacd:2 /opt/keeper/share/guacd/docker-seccomp.json

Place the output of this command into /etc/kcm-setup/guacd-docker-seccomp.json and restart the containers.

Images

Below is a description of each of the images.

Now that your Keeper Connection Manager instance is running, you can login as guacadmin and start setting up some connections. Follow the Using Keeper Connection Manager documentation for next steps.

The next several sections of this installation guide provide detailed information about each specific Docker image, if you plan to customize or modify the environment.

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. If unsure, choose all groups.

If you would like to automatically mapp 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.

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

(8) Copy the URL of the App Federation Metadata and paste it into the prompt on your KCM server.

(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:

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

Authentication Methods

• SAML 2.0

• OpenID Connect

• LDAP

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.

• TOTP

• Duo

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

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.

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.

Docker Environmental Variables

To enable TOTP add the following lines to the "environment" section of the "guacamole" service in the docker-compose.yml file. Only the EXTENSIONS: totp line is required, the rest are optional.

For example:

TOTP with SAML / OIDC

Keeper Connection Manager supports the use of 2FA with TOTP in addition to supporting SAML or OIDC authentication. If TOTP is configured along with SAML, the user will be prompted for 2FA after successfully authenticating with the identity provider.

OneLogin Configuration

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

You must have OneLogin developer account.

Configure OneLogin

2. Search for SAML, and select SAML Test Connector (IdP).

3. When prompted, change the Display Name of your app. Enter an application name and description. You can also upload a Keeper Connection Manager logo. Click save.

4. Go to the Configuration tab, Update 3 fields: Recipient, ACS (Consumer) URL Validator, and ACS (Consumer) URL with your KCM server URL and /api/ext/saml/callback on the end as shown below.

1. Click on the More Actions dropped-down menu. Select SAML Metadata to download and save the .XML file.

2. Under the Users tab on the top, find the users that need to log in using SSO, click into them and on the applications tab on the left, add the new SAML application to them.

PingIdentity Configuration

1. Login as an Administrator for PingIdentity. From the PingIdentity menu, click Applications > Add Application

2. Give the Application a name such as "KCM," select SAML and Save.

1. Next, you'll encounter the SAML configuration. Select Manually Enter, then add the URL of your KCM server to the ACS URLs box as follows: https://<YOUR DOMAIN>/api/ext/saml/callback

2. Then add the URL of your KCM server to the Entity ID box as follows: https://<YOUR DOMAIN> and press Save.

1. Next, Edit Attribute Mappings. Since saml_subject is immutable, leave it as is. Add an attribute named EMAIL that has a Mapping of Username, and an attribute named groups that has a Mapping of Group Names.

1. Then Edit Configuration and scroll down to SUBJECT NAMEID FORMAT and select the option urn:oasis:names:to:SAML:1.1:nameid-format:emailAddress. And hit Save.

1. On the Overview section, verify that Access is for All Users (or the group you specified). Leave the Signon URL as the Default Signon Page. And Enable the Application by clicking the slider at the top of the application.

1. Download the Metadata file from the Configuration tab, and ensure that it is named to metadata.xml.

1. Ensure that all users are added with a Username that matches the email address of a user in your Keeper Connection Manager. **When you add users to Keeper Connection Manager use the matching email address, but leave the password blank.

Video Example

To update all of the Keeper Connection Manager docker images when using the Docker Compose Install method, run the below command (assuming docker-compose.yml is in the current folder):

If you originally installed with the Auto Docker Install method (kcm-setup.run script), run the below command:

Select "Y" when prompted.

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 login page as shown below.

Auto Docker Install Method

Run the reconfigure command listed below and press enter to accept all the pre-populated selections until you get to the SAML prompt.

Retreive your IdP Metadata

Instructions for setting up your identity provider and retrieving the XML metadata are found in the guides blow. Any SAML 2.0 identity provider is compatible.

Complete the Prompts

• Enter your SAML IdP URL.

• When asked about signed requests, if unsure, select no.

• Enter your SAML entity ID, and then the group attribute (this must match to your IdP's group attribute).

• Next, you're asked if you want SAML as the default login process. If you want SAML login to be an option (link) on the login page, select no. If you want SAML as the only possible method of authentication, select yes.

• Answer yes when asked if you want user accounts created automatically. If you select no, you'll need to create each account manually within KCM.

SSO Configuration is complete!

Docker Compose Install Method

If you installed Keeper Connection Manager using the Docker Compose Install method, this does not come preconfigured with SAML support. The instructions for activating SAML are below:

(1) On the local instance, stop the containers.

(2) Edit the docker-compose file

Using the custom docker method requires modification of docker-compose.yml file to add SAML support. As root, edit your docker-compose.yml file and find the "guacamole" section.

Create a volume mount for sharing the metadata.xml file with the container. If you already have a shared volume for this purpose, you can use that one. There is also another section needed which needs SAML environmental variables. A sample file is listed below.

Notes:

• Replace "/var/lib/guac_home" with the local path to your volume

• Replace "https://demo.lurey.com" in 2 spots with your Keeper Connection Manager login URL

• Only use this SAML group attribute if you're using Azure. Other identity providers will use a different Group attribute ID.

• If you want ALL users to login with SAML, then remove the ADDITIONAL_GUACAMOLE_PROPERTIES line. As written, it will give users the choice of password or SAML login.

(3) Create the local folder volume if it doesn't exist yet

(4) Copy the metadata.xml file from your local computer (downloaded from step 8 above) into the location of the volume mount referenced in the guacamole section of the docker-compose file.

(5) Restart the containers

Configuration is complete.

Complete

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:

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. Transfer this metadata.xml file to your KCM server machine.

Keeper Connection Manager provides support for OpenID Connect for authentication.

Docker Environmental Variables

The image keeper/guacamole can be modified to support OpenID using environmental variables. See the OPENID_* variables defined in the documentation.

Keeper Connection Manager provides support for Duo as a second authentication factor, automatically verifying user identity with Duo after the user is initially authenticated. This integration utilizes the Duo Web SDK V4.

Duo Setup

From the DUO Security Admin portal:

• Select "Protect an Application"

• Search for "Web SDK" (Do NOT select Keeper Security - this is for the Vault only)

• Select Web SDK and click "Protect"

• Capture the Client ID, Client Secret, and API Hostname

• Provide these 3 configuration options as DUO_* environment variables in the keeper/guacamole Docker image.

Docker Environment Variables

The image keeper/guacamole section in the docker-compose.yaml file can be modified to support Duo using environment variables.

Multiple Hostnames/Configurations for SSL Termination

The keeper/guacamole-ssl-nginx image is specifically intended to provide SSL termination for the Guacamole image provided by Keeper for KCM. Historically, this image supported only a single hostname and configuration:

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            SELF_SIGNED: "Y"
            ACCEPT_EULA: "Y"
            CONTENT_TYPE_OPTIONS: "Y"
            CONTENT_SECURITY_POLICY: "Y"
            GUACAMOLE_HOSTNAME: "guacamole"
            SSL_HOSTNAME: "example.net"

As of KCM 2.12.0, the keeper/guacamole-ssl-nginx image can be used with multiple hostnames and configurations via a special SERVERS environment variable that accepts YAML (or JSON).

The SERVERS variable must contain a YAML (or JSON) array of objects, where each object contains the name/value pairs of environment variables that should apply to that additional configuration. Any variable that is not specified is inherited from the top-level environment. For example:

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            SELF_SIGNED: "Y"
            ACCEPT_EULA: "Y"
            CONTENT_TYPE_OPTIONS: "Y"
            CONTENT_SECURITY_POLICY: "Y"
            GUACAMOLE_HOSTNAME: "guacamole"
            
            SERVERS: |
               - SSL_HOSTNAME: "example.net"
               - SSL_HOSTNAME: "*.example.net"

The above configuration would result in an NGINX instance that handles both example.net and *.example.net hostnames equivalently. Both will get their own self-signed certificates because SELF_SIGNED is set to Y.

A more complex example:

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            CONTENT_TYPE_OPTIONS: "Y"
            CONTENT_SECURITY_POLICY: "Y"
            GUACAMOLE_HOSTNAME: "guacamole"
            
            SERVERS: |
               - SSL_HOSTNAME: "example.net"
                 LETSENCRYPT_ACCEPT_TOS: "Y"
                 LETSENCRYPT_EMAIL=your.email@example.net

               - SSL_HOSTNAME: "*.example.net"
                 SELF_SIGNED: "Y"

The above configuration would result in an NGINX instance that generates and uses a self-signed certificate for *.example.net, but obtains a certificate for example.net from Let’s Encrypt.

IMPORTANT: The value of SERVERS must be a string, hence the | symbol within the above examples. If this symbol is omitted, then the YAML that follows is parsed as an object, and validation of the docker-compose.yml will fail, as all Docker environment variables must be strings.

NOTE: NGINX will use the first server as the default for any request that does not match any configured hostname. If any server declared in SERVERS should have this behavior, it must be the first server listed.

Go to your Oracle Admin Console and navigate to the Identity Domains Overview page, then select Applications as depicted above.

Click on Add Application.

Select SAML as the application type.

Apply the appropriate settings to the Application Information as needed for your security posture. Click on Edit SSO Configuration. Download the Metadata and rename the file to metadata.xml. Set the Entity ID to the URL of your Connection Manager server. For example: https://kcm.somedomain.com. For the Assertion Consumer URL, add /api/ext/saml/callback to the end of the domain URL. For example: https://kcm.somedomain.com/api/ext/saml/callback. Next, set the Name ID Format to Email Address and the Name ID Value to Primary Email. Leave the Signed SSO setting as Assertion. Uncheck the box to Include Signing Certificate in Signature, and leave the Signature Hashing Algorithm as SHA-256.

Assign attributes for email as listed above mapped to the value User Name. Add another attribute for groups with the settings of Type Value Group Membership and a Condition of All groups.

Assign users and groups as appropriate to your SAML application. You'll need to assign at least one user for testing purposes.

Connection Manager Server Configuration

Upload the metadata.xml file to your KCM server and move it into the directory /etc/kcm-setup.

Run the reconfigure command after production hours on your Connection Manager server.

Say Y to the option when presented to setup SAML support.

Select 1 for Local Metadata file. Then input the path of your metadata file as /etc/kcm-setup/metadata.xml and press enter. Answer N to Does your SAML IDP require signed requests? Input your SAML entity ID as the URL of your Connection Manager instance. For example: https://kcm.somedomain.com. Then enter groups as the SAML group attribute.

Choose which setting best applies to your security posture with regard to the default authentication method. If you want Just-In-Time provisioning of users, then answer Y to Would you like user accounts to be automatically created for each successful login?

Click the SAML link to authenticate to the main sign on page.

Your user email address should display in the top right corner after authenticating.

Keeper Connection Manager can be configured to require SSL/TLS client authentication.

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.

openssl genrsa -des3 -out ca.key 4096

(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.

openssl req -new -x509 -days 365 -key ca.key -out ca.crt

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

openssl x509 -in ca.crt -noout -text

(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.

openssl genrsa -des3 -out client.key 4096

(4) Create a CSR

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

openssl req -new -key client.key -out client.csr

(5) Sign the CSR with the CA Key

openssl x509 -req -days 365 -in client.csr \
 -CA ca.crt -CAkey ca.key \
 -set_serial 01 -out client.crt

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.

openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.pfx

(7) Add to NGINX Config

The keeper/guacamole-ssl-nginx image can be configured to require SSL/TLS client authentication by specifying the CLIENT_CERTIFICATE_FILE environment variable. A user will only be able to connect to the KCM instance of NGINX using their browser if their browser has access to a private key that is signed by this certificate.

This variable is similar to the CERTIFICATE_FILE environment variable in that it points to a file within the container, but in this case it controls the certificate used to authenticate the client’s private key.

Example:

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            CLIENT_CERTIFICATE_FILE: "/path/in/container/ca.crt"
        volumes:
            - "/local/path/to/keys:/path/in/container/"

After updating the configuration, restart the containers.

(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.

Optional Parameters

Additional environment variables are also available to modify SSL/TLS auth behavior further: