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.

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.

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

Install Methods

For Auto Docker Install method, we support any version of Linux.

For Docker Compose Install, Keeper Connection Manager will run on any platform that supports Docker or Docker Desktop, including all versions of Windows and Linux.

Customers who directly installed via Linux RPMs can refer to our advanced linux install docs.

Configure DNS

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

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

Decide on Let's Encrypt or Existing Cert

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

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

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.

Go to: Installation Instructions for Auto Docker Install

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.

Go to: Installation Instructions for Docker Compose Install

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

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.

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

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

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.

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

Amazon Linux 2

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.

Ubuntu

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

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.

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:

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:

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:

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.

Image: keeper/guacamole

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

Viewing the Guacamole logs

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

KCM_LICENSE

ADDITIONAL_GUACAMOLE_PROPERTIES

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_*

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:

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_*

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_*

LDAP_*

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

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_*

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_*

Optional variables:

POSTGRES_*

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_*

The following environment variables are required if using SAML authentication:

Optional environmental variables:

SQLSERVER_*

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_*

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_*

UDS_*

USER_MAPPING

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:

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:

Overview

Auto Docker Install is Keeper's recommended installation method.

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.

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

Installation

(1) Download the Installer

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

(2) Add the execute permission to the Installer

(3) Run the Installer as root

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)

Set up SSO Login (optional)

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.

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.

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

Update Instructions

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

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

Select "Y" when prompted.

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

Image: keeper/guacamole-db-mysql

Environment variables

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

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:

Image: keeper/guacamole-db-postgres

keeper/guacamole-db-postgres is a Dockerized deployment of PostgreSQL, built off Docker's official PostgreSQL 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 PostgreSQL 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 PostgreSQL image are accepted, as the official PostgreSQL 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.

POSTGRES_PASSWORD

The PostgreSQL administrator password.

GUACAMOLE_DATABASE

The name of the database to create and initialized for use with Apache Guacamole. This environment variable ultimately maps to the POSTGRES_DB environment variable of the official PostgreSQL image. If omitted, the default value defined by the official PostgreSQL image will be used.

The GUACAMOLE_DATABASE variable is provided here for consistency with the other Guacamole-specific variables and may be omitted if POSTGRES_DB 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 PostgreSQL database user specific to the Guacamole web application. This pair of variables differ from the POSTGRES_USER and POSTGRES_PASSWORD environment variables provided by the official PostgreSQL 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 POSTGRES_USER and POSTGRES_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 GUACAMOLE_DATABASE=guacamole_db \
    -e POSTGRES_PASSWORD=some_password \
    -e GUACAMOLE_ADMIN_PASSWORD=some_password \
    -e GUACAMOLE_USERNAME_FILE=/run/secrets/postgres-username \
    -e GUACAMOLE_PASSWORD_FILE=/run/secrets/postgres-password \
    -d keeper/guacamole-db-postgres

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.

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.

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

sudo docker-compose pull
sudo docker-compose up -d

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

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

Select "Y" when prompted.

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.

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

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.

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.

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

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

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

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:

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:

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

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

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

To restart the service with the new certificate:

Annual Renewal

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.

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:

Image: keeper/guacamole-ssl-nginx

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:

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.

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

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.

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

ACCEPT_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

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

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

Advanced Configuration

SSL_CIPHERS

SSL_PROTOCOLS

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.

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:

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.

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.