Loading...
Loading...
Loading...
Loading...
Detailed list of system and operating system requirements for Keeper Connection Manger
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.
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
The generalized formula for sizing Keeper Connection Manager is 1 CPU core and 2 GB of memory for every 25 concurrent users anticipated. We recommend a minimum of 8GB RAM and 2 cores for any small deployment.
0-25
2
8gb
26-50
3
12gb
51-100
4
16gb
101-200
8
32gb
200+
Contact us
Contact us
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.
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.
There are far too many variables in play to accurately predict disk space needs for recordings. The best practices are to monitor the recordings folder and offload them to another location as needed.
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.
Loading...
Loading...
Auto Docker Install service management
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.
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.
backup
Backup all database data to a file.
check
Perform an automated self-check of all services.
install
Install Keeper Connection Manager (DEFAULT).
logs
Display the log files from all installed services.
reconfigure
Modify the configuration of an existing KCM installation.
restart
Restart all installed services, starting any that are stopped.
restore
Restore database data from a prior backup.
start
Start all installed services that are not started.
status
Display the status of installed services.
stop
Stop all installed services that are not stopped.
uninstall
Completely remove the existing installation. This will delete all stored data in the database.
upgrade
Upgrade the existing installation by pulling the latest docker images. Your data stored in the service is retained.
apply
Strictly apply changes made externally to docker-compose.yml
and do not pull new images.
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.
Loading...
Activating additional packages on the Auto Docker Install method
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.
Apply the changes
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:
or.....
Loading...
Docker deployment of Apache Guacamole with Keeper Connection Manager
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.
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.
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.
API_MAX_REQUEST_SIZE
The maximum number of bytes to accept within the entity body of any particular HTTP request to the REST API, including authentication requests. This limit does not apply to files transferred within a remote desktop session. Specifying 0 disables request size limitations. By default, requests are limited to 2097152 bytes (2 MB).
API_SESSION_TIMEOUT
The amount of time, in minutes, a Guacamole session may remain valid despite being inactive. By default, Guacamole sessions are limited to one hour.
This setting affects Guacamole sessions only, not remote desktop sessions. To enforce limits on the duration of remote desktop sessions, you must change the relevant setting within your remote desktop server, such as the session time limit GPOs provided by the Windows RDP server. Guacamole considers a connected remote desktop session to be user activity, and does not attempt to define what constitutes an idle but connected remote desktop session.
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:
AWS_DISCOVERY_ACCESS_KEY_ID
The access key ID for the AWS account that should be used to authenticate with AWS.
AWS_DISCOVERY_SECRET_KEY
The secret key associated with the access key
AWS_DISCOVERY_REGIONS
Comma-separated list of regions to query for EC2 instances, such as us-west-1,us-east-1
.
Other, optional environment variables are available for the other properties related to EC2 discovery:
AWS_DISCOVERY_INSTANCE_BASE_PATH
The name of the organizational connection group that should be used to house the EC2 instances for convenience. By default, this will be "Amazon EC2".
AWS_DISCOVERY_ADMIN_GROUP
The name of the User Group in Keeper Connection Manager to require for any user to see the discovered EC2 instances. By default, this will be a group called "AWS EC2 Administrators".
AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT
If set to "true", screen recording will be enabled by default on all connections. Connection session recording can also be set at an individual machine level using the "kcm:record
" EC2 instance tag, which overrides the value set here, if any.
AWS_DISCOVERY_KSM_CONFIG
The base64-encoded Keeper Secrets Manager configuration to use to retrieve the private keys for EC2 instances from the Keeper vault.
AWS_DISCOVERY_KSM_API_CALL_INTERVAL
The minimum number of milliseconds that must elapse between API calls to Keeper Secrets Manager. By default, KCM will wait 10 seconds between each call, using cached data from the last retrieval until another retrieval attempt is allowed.
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.
BAN_ADDRESS_DURATION
The amount of time an IP address is temporarily blocked after repeatedly failing to authenticate, in seconds. By default, addresses are blocked for 5 minutes.
BAN_MAX_ADDRESSES
The maximum number of IP addresses that KCM will track to check for invalid attempts. By default, up to 10485760 addresses will be tracked.
BAN_MAX_INVALID_ATTEMPTS
The number of invalid attempts that may occur before the source IP address is temporarily blocked from further attempts. By default, 5 failed authentication attempts will result in a temporary block.
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:
DUO_API_HOSTNAME
REQUIRED. The hostname of the Duo API endpoint that will be used to verify user identities, assigned by Duo when Guacamole was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel.
DUO_AUTH_TIMEOUT
The timeout, in minutes, for in-progress Duo authentication attempts. Authentication attempts exceeding this duration will be invalidated. By default, Duo authentication attempts will time out after 5 minutes.
DUO_CLIENT_ID
REQUIRED. The client ID provided for you by Duo when KCM was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel.
DUO_CLIENT_SECRET
REQUIRED. The client secret provided for you by Duo when KCM was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel.
DUO_REDIRECT_URI
REQUIRED. The user-facing URI that the Duo service can use to redirect an authenticated user's browser back to KCM. This is the URI that you use for the KCM deployment, e.g. https://kcm.company.com
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):
mysql
guacamole(mysql)
kcm-guacamole-auth-jdbc-mysql
postgresql
guacamole(postgresql)
kcm-guacamole-auth-jdbc-postgresql
sqlserver
guacamole(sqlserver)
kcm-guacamole-auth-jdbc-sqlserver
uds
guacamole(uds)
kcm-guacamole-auth-uds
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:
Force SAML to take priority over all other extensions.
saml
Force all other extensions to take priority over SAML.
*, saml
Prefer LDAP over any other authentication method, and force all other extensions to take priority over SAML and OpenID.
ldap, *, saml, openid
GUACD_*
TCP connection information for guacd.
GUACD_HOSTNAME
The hostname of the machine hosting the guacd service.
Other, optional environment variables are available for configuring other aspects of the connection to guacd:
GUACD_PORT
The port used by the guacd service.
GUACD_SSL
Whether the guacd service has been configured for SSL/TLS.
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:
JSON_SECRET_KEY
The shared secret key that will be used by systems generating JSON data to encrypt and sign that data. This key must be 128 bits, specified with 32 hexadecimal digits.
Other, optional environment variables are available for the other properties related to encrypted JSON authentication:
JSON_TRUSTED_NETWORKS
A comma-separated list of trusted IP addresses and/or CIDR subnets which should be allowed to send encrypted JSON. If omitted, any address will be allowed to send JSON.
KSM_*
All environment variables which start with KSM_*
correspond to configuration properties for Keeper Secrets Manager. See the Keeper Vault Integration guide.
KSM_ALLOW_USER_CONFIG
If set to "true", users will be allowed to provide their own KSM configuration or one-time token. Vault records of users that provide this will be additionally considered for any connection that (1) an administrator enables for use with user vaults and (2) contains a token that cannot be satisfied with a record from the system-wide vault configured with KSM_CONFIG
. By default, users are not allowed to provide their own KSM configuration.
KSM_API_CALL_INTERVAL
The minimum number of milliseconds that must elapse between API calls to Keeper Secrets Manager. By default, KCM will wait 10 seconds between each call, using cached data from the last retrieval until another retrieval attempt is allowed.
KSM_CONFIG
The Keeper Secrets Manager b64 configuration, generated by Keeper Commander.
KSM_MATCH_DOMAINS_FOR_USERS
If set to "true", Active Directory domains within KSM records and KCM connections will be considered when determining whether a record matches a username. By default, only the username itself is considered.
KSM_STRIP_WINDOWS_DOMAINS
If set to "true", Active Directory domains within KSM records will be alternatively determined by splitting the record username into username and domain components. Splitting is performed based on the User Principal Name and Down-Level Logon Name formats. By default, usernames are not split, and Windows domains will be read only from a separate "Domain" field on the record.
KSM_TOKEN_MAPPING
Static tokens used to identify specific Keeper vault records and fields.
*_KSM_SECRET
Used for protection and storage of configuration values in the Keeper vault.
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):
LDAP_HOSTNAME
The hostname or IP address of the LDAP server that Guacamole should use for authentication.
LDAP_USER_BASE_DN
The common base DN shared by all Guacamole users within the LDAP directory.
If using multiple LDAP servers, or if you prefer to provide LDAP server configuration in YAML format, the following environment variable is required:
LDAP_SERVERS
A list of LDAP servers in the proper yml format. Follow this guide.
Other, optional environment variables are available for the other properties related to LDAP authentication:
LDAP_PORT
The TCP port that the LDAP server is listening on. If omitted, the standard LDAP or LDAPS port will be used, depending on the encryption method. Unencrypted LDAP uses the standard port of 389, while LDAPS uses port 636.
LDAP_ENCRYPTION_METHOD
The encryption mechanism to use when communicating with your LDAP server, if any. Legal values are "none" for unencrypted LDAP, "ssl" for LDAP over SSL/TLS (commonly known as LDAPS), or "starttls" for STARTTLS. If omitted, encryption will not be used.
LDAP_NETWORK_TIMEOUT
LDAP_OPERATION_TIMEOUT
The maximum amount of time to allow for any LDAP query, in seconds. By default, LDAP queries will time out after 30 seconds.
LDAP_USERNAME_ATTRIBUTE
The attribute which contains the username within all relevant user objects in the LDAP directory. If multiple attributes may contain the username, multiple attributes may be specified separated by commas, and a search DN is required.
LDAP_SEARCH_BIND_DN
The DN that the web application should bind as when determining the DN of the user attempting to authenticate. Specifying a search DN is required if usernames may be within any one of several attributes, or if the user's username is not part of their DN.
LDAP_SEARCH_BIND_PASSWORD
The password to use when authenticating with the search DN.
LDAP_CONFIG_BASE_DN
The common base DN shared by all guacConfigGroup
objects, if the LDAP directory is being used to store connection data.
LDAP_GROUP_BASE_DN
The common base DN shared by all user groups which may dictate guacConfigGroup
access within the LDAP directory via the seeAlso
attribute.
LDAP_MAX_SEARCH_RESULTS
The maximum number of results to attempt to retrieve from the LDAP directory for any particular search. Searches which exceed this limit will fail. By default, searches are limited to 1000 entries.
LDAP_USER_SEARCH_FILTER
The LDAP search filter to use when querying user accounts. If omitted, (objectClass=*)
will be used by default.
LDAP_GROUP_SEARCH_FILTER
The LDAP search filter to use when retrieving groups. If omitted, (objectClass=*)
will be used by default.
LDAP_DEREFERENCE_ALIASES
Whether aliases should be automatically dereferenced. Legal values are "never", "searching" (dereference only after the base DN is located), "finding" (dereference only when locating the base DN), and "always". By default, aliases are not derefenced.
LDAP_FOLLOW_REFERRALS
If "true", automatically follow referrals received from the LDAP directory. By default, LDAP referrals are not followed.
LDAP_MAX_REFERRAL_HOPS
The maximum number of referrals that may be followed when resolving any particular LDAP referral. By default, if LDAP automatic following of referrals is enabled, up to 5 hops are allowed for any one referral.
CA_CERTIFICATES
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.
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:
MYSQL_HOSTNAME
The hostname or IP address of the MySQL or MariaDB server hosting the Guacamole database.
MYSQL_DATABASE
The name of the database that has been created for Guacamole on the MySQL or MariaDB server.
MYSQL_USERNAME
The username that Guacamole should use when authenticating with the MySQL or MariaDB server.
MYSQL_PASSWORD
The password that Guacamole should provide when authenticating with the MySQL or MariaDB server.
Other, optional environment variables are available for the other properties related to MySQL authentication:
MYSQL_PORT
The TCP port that the MySQL or MariaDB server is listening on. If omitted, the standard MySQL port of 3306 will be used.
MYSQL_USER_PASSWORD_MIN_LENGTH
The minimum length to require for user passwords. By default, password complexity is not enforced.
MYSQL_USER_PASSWORD_REQUIRE_MULTIPLE_CASE
If set to "true", require that user passwords use both uppercase and lowercase characters.
MYSQL_USER_PASSWORD_REQUIRE_SYMBOL
If set to "true", require that user passwords contain at least one symbol. By default, password complexity is not enforced.
MYSQL_USER_PASSWORD_REQUIRE_DIGIT
If set to "true", require that user passwords contain at least one digit. By default, password complexity is not enforced.
MYSQL_USER_PASSWORD_PROHIBIT_USERNAME
If set to "true", disallow user passwords that contain the user's username. By default, password complexity is not enforced.
MYSQL_USER_PASSWORD_MIN_AGE
The minimum number of days that must elapse following a password change before the user may change their password again. By default, users are not required to wait before changing their password.
MYSQL_USER_PASSWORD_MAX_AGE
The maximum number of days that may elapse since the last password change before the user is required to change their password. By default, users are not required to regularly change their password.
MYSQL_USER_PASSWORD_HISTORY_SIZE
Remember this number of previous passwords and prohibit reuse of those passwords when the user's password is changed. By default, users are allowed to reuse previous passwords.
MYSQL_DEFAULT_MAX_CONNECTIONS
The maximum number of concurrent connections to allow to any particular connection, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connections is not limited.
MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS
The maximum number of concurrent connections to allow to any particular connection group, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connection groups is not limited.
MYSQL_DEFAULT_MAX_CONNECTIONS_PER_USER
The maximum number of concurrent connections to allow each user to hold to any particular connection, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connections is not limited.
MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER
The maximum number of concurrent connections to allow each user to hold to any particular connection group, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connection groups is limited to one.
MYSQL_ABSOLUTE_MAX_CONNECTIONS
The maximum number of concurrent connections to allow to overall, regardless of user, connection or connection group, where a value of "0" indicates unlimited. By default, overall concurrent usage is not limited.
MYSQL_USER_REQUIRED
If set to "true", require that each user have a corresponding account defined within the database, even if the user authenticated through some other mechanism (such as LDAP). By default, users that successfully authenticate through another mechanism are not required to also have an account within the database.
MYSQL_TRACK_EXTERNAL_CONNECTION_HISTORY
Whether connections that do not exist within the database should have connection history tracked in the database. If set to "true", connection history records will be created for any connection established. If set to "false", connection history records will be created only for connections defined in the database. By default, external connections will be tracked.
MYSQL_ENFORCE_ACCESS_WINDOWS_FOR_ACTIVE_SESSIONS
Whether access time restrictions imposed by the administrator on user accounts should be enforced while a user is logged in. If set to "true", users will be automatically logged out within roughly one minute of reaching their access time limits. If set to "false", access time restrictions will only be enforced at the moment a user attempts to log in. By default, access time restrictions are enforced while users are logged in.
MYSQL_AUTO_CREATE_ACCOUNTS
Whether user account entries should automatically be created within the database for users that successfully authenticate through other means, such as an SSO provider or LDAP. This may be necessary if using an extension that requires account-specific storage, like TOTP or per-account approvals. If set to "true", user account entries will automatically be created. By default, administrators must manually create such entries if needed.
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.
OPENID_AUTHORIZATION_ENDPOINT
The authorization endpoint (URI) of the OpenID service. This value should be provided to you by the identity provider. For identity providers that implement OpenID Connect Discovery, this value can be retrieved from the "authorization_endpoint" property of your provider's ".well-known/openid-configuration" JSON file.
OPENID_CLIENT_ID
The OpenID client ID which should be submitted to the OpenID service when necessary. This value is typically provided to you by the OpenID service when OpenID credentials are generated for your application.
OPENID_ISSUER
The issuer to expect for all received ID tokens. This value should be provided to you by the identity provider. For identity providers that implement OpenID Connect Discovery, this value can be retrieved from the "issuer" property of your provider's
".well-known/openid-configuration" JSON file.
OPENID_JWKS_ENDPOINT
The endpoint (URI) of the JWKS service which defines how received ID tokens (JSON Web Tokens or JWTs) shall be validated. This value should be provided to you by the identity provider. For identity providers that
implement OpenID Connect Discovery, this value can be retrieved from the "jwks_uri" property of your provider's ".well-known/openid-configuration" JSON file.
OPENID_REDIRECT_URI
The URI that should be submitted to the OpenID service such that they can redirect the authenticated user back to Keeper Connection Manager after the authentication process is complete. This must be the full URL that a user would enter into their browser to access Keeper Connection Manager. The URI that should be submitted to the OpenID service such that they can redirect the authenticated user back to Keeper Connection Manager after the authentication process is complete. This must be the full URL that a user would enter into their browser to access Keeper Connection Manager.
Optional variables:
OPENID_ALLOWED_CLOCK_SKEW
The amount of clock skew tolerated for timestamp comparisons between the Guacamole server and OpenID service clocks, in seconds. By default, clock skew of up to 30 seconds is tolerated.
OPENID_GROUPS_CLAIM_TYPE
The claim type within any valid JWT that contains the list of groups of which the authenticated user is a member. By default, the “groups” claim type is used.
OPENID_MAX_NONCE_VALIDITY
The maximum amount of time that a nonce generated by the Guacamole server should remain valid, in minutes. As each OpenID request has a unique nonce value, this imposes an upper limit on the amount of time any particular OpenID request can result in successful authentication within Guacamole. By default, each generated nonce expires after 10 minutes.
OPENID_MAX_TOKEN_VALIDITY
The maximum amount of time that an OpenID token should remain valid, in minutes. By default, each OpenID token remains valid for 300 minutes (5 hours).
OPENID_SCOPE
The space-separated list of OpenID scopes to request. OpenID scopes determine the information returned within the OpenID token, and thus affect what values can be used as an authenticated user’s username. To be compliant with OpenID, at least “openid profile” must be requested. By default, “openid email profile” is used.
OPENID_USERNAME_CLAIM_TYPE
The claim type within any valid JWT that contains the list of groups of which the authenticated user is a member. By default, the “groups” claim type is used.
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:
POSTGRES_HOSTNAME
The hostname or IP address of the PostgreSQL server hosting the Guacamole database.
POSTGRES_DATABASE
The name of the database that has been created for Guacamole on the PostgreSQL server.
POSTGRES_USERNAME
The username that Guacamole should use when authenticating with the PostgreSQL server.
POSTGRES_PASSWORD
The password that Guacamole should provide when authenticating with the PostgreSQL server.
Other, optional environment variables are available for the other properties related to PostgreSQL authentication:
POSTGRES_PORT
The TCP port that the PostgreSQL server is listening on. If omitted, the standard PostgreSQL port of 5432 will be used.
POSTGRES_USER_PASSWORD_MIN_LENGTH
The minimum length to require for user passwords. By default, password complexity is not enforced.
POSTGRES_USER_PASSWORD_REQUIRE_MULTIPLE_CASE
If set to "true", require that user passwords use both uppercase and lowercase characters.
POSTGRES_USER_PASSWORD_REQUIRE_SYMBOL
If set to "true", require that user passwords contain at least one symbol. By default, password complexity is not enforced.
POSTGRES_USER_PASSWORD_REQUIRE_DIGIT
If set to "true", require that user passwords contain at least one digit. By default, password complexity is not enforced.
POSTGRES_USER_PASSWORD_PROHIBIT_USERNAME
If set to "true", disallow user passwords that contain the user's username. By default, password complexity is not enforced.
POSTGRES_USER_PASSWORD_MIN_AGE
The minimum number of days that must elapse following a password change before the user may change their password again. By default, users are not required to wait before changing their password.
POSTGRES_USER_PASSWORD_MAX_AGE
The maximum number of days that may elapse since the last password change before the user is required to change their password. By default, users are not required to regularly change their password.
POSTGRES_USER_PASSWORD_HISTORY_SIZE
Remember this number of previous passwords and prohibit reuse of those passwords when the user's password is changed. By default, users are allowed to reuse previous passwords.
POSTGRES_DEFAULT_MAX_CONNECTIONS
The maximum number of concurrent connections to allow to any particular connection, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connections is not limited.
POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS
The maximum number of concurrent connections to allow to any particular connection group, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connection groups is not limited.
POSTGRES_DEFAULT_MAX_CONNECTIONS_PER_USER
The maximum number of concurrent connections to allow each user to hold to any particular connection, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connections is not limited.
POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER
The maximum number of concurrent connections to allow each user to hold to any particular connection group, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connection groups is limited to one.
POSTGRES_ABSOLUTE_MAX_CONNECTIONS
The maximum number of concurrent connections to allow to overall, regardless of user, connection or connection group, where a value of "0" indicates unlimited. By default, overall concurrent usage is not limited.
POSTGRES_USER_REQUIRED
If set to "true", require that each user have a corresponding account defined within the database, even if the user authenticated through some other mechanism (such as LDAP). By default, users that successfully authenticate through another mechanism are not required to also have an account within the database.
POSTGRESQL_TRACK_EXTERNAL_CONNECTION_HISTORY
Whether connections that do not exist within the database should have connection history tracked in the database. If set to "true", connection history records will be created for any connection established. If set to "false", connection history records will be created only for connections defined in the database. By default, external connections will be tracked.
POSTGRESQL_ENFORCE_ACCESS_WINDOWS_FOR_ACTIVE_SESSIONS
Whether access time restrictions imposed by the administrator on user accounts should be enforced while a user is logged in. If set to "true", users will be automatically logged out within roughly one minute of reaching their access time limits. If set to "false", access time restrictions will only be enforced at the moment a user attempts to log in. By default, access time restrictions are enforced while users are logged in.
POSTGRESQL_AUTO_CREATE_ACCOUNTS
Whether user account entries should automatically be created within the database for users that successfully authenticate through other means, such as an SSO provider or LDAP. This may be necessary if using an extension that requires account-specific storage, like TOTP or per-account approvals. If set to "true", user account entries will automatically be created. By default, administrators must manually create such entries if needed.
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:
Require approval for logins from SAML.
saml
Require approval for logins from SAML and LDAP.
saml, ldap
Account approval status can only be stored and enforced on users with identities in the KCM database. Depending on which database you are using, you can request that KCM automatically create this storage for accounts that do not yet exist within the database by setting one of the following environment variables to "true":
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:
SAML_CALLBACK_URL
The URI that should be submitted to the SAML service such that they can POST the authentication result to Keeper Connection Manager and redirect the user back to the application. This must be the full URL that a user would enter into their browser to access Keeper Connection Manager.
Optional environmental variables:
SAML_COMPRESS_REQUEST
Enable compression of the HTTP requests sent to the SAML IdP. This property is optional and will default to true (compression enabled).
SAML_COMPRESS_RESPONSE
Request that the SAML response returned by the IdP be compressed. This property is optional and will default to true (compression will be requested).
SAML_ENTITY_ID
The entity ID of the Guacamole SAML client, which is generally the URL of the Guacamole server, but is not required to be so. This property is required if either the saml-idp-metadata-url property is not specified, or if the provided metadata file does not contain the SAML SP Entity ID for Guacamole Client.
SAML_GROUP_ATTRIBUTE
The name of the attribute provided by the SAML IdP that contains group membership of the user. These groups will be parsed and used to map group membership of the user logging in, which can be used for permissions management within Guacamole Client, particularly when layered with other authentication modules. This property is optional, and defaults to “groups”.
SAML_IDP_METADATA_URL
The URI of the XML metadata file that from the SAML Identity Provider that contains all of the information the SAML extension needs in order to know how to authenticate with the IdP. This URI can either be a remote server (e.g. https://) or a local file on the filesystem (e.g. file://). Often the metadata file contains most of the required properties for SAML authentication and the other parameters are not required.
SAML_IDP_URL
The base URL of the SAML IdP. This is the URL that the SAML authentication extension will use to redirect when requesting SAML authentication. If the saml-idp-metadata-url property is provided, this parameter will be ignored. If the metadata file is not provided this property is required.
SAML_PRIVATE_KEY_PATH
The full path of the private key in PEM format that should be used to sign SAML requests submitted to the SAML IdP. This is required only if the SAML IdP requires signed requests. By default, SAML requests are not signed.
SAML_X509_CERT_PATH
The full path of the X.509 certificate in PEM format that should be used to sign SAML requests submitted to the SAML IdP. This is required only if the SAML IdP requires signed requests. By default, SAML requests are not signed.
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:
SQLSERVER_HOSTNAME
The hostname or IP address of the SQL Server instance hosting the Guacamole database.
SQLSERVER_DATABASE
The name of the database that has been created for Guacamole on the SQL Server instance.
SQLSERVER_USERNAME
The username that Guacamole should use when authenticating with the SQL Server instance.
SQLSERVER_PASSWORD
The password that Guacamole should provide when authenticating with the SQL Server instance.
Other, optional environment variables are available for the other properties related to SQL Server authentication:
SQLSERVER_PORT
The TCP port that the SQL Server instance is listening on. If omitted, the standard SQL Server port of 1433 will be used.
SQLSERVER_USER_PASSWORD_MIN_LENGTH
The minimum length to require for user passwords. By default, password complexity is not enforced.
SQLSERVER_USER_PASSWORD_REQUIRE_MULTIPLE_CASE
If set to "true", require that user passwords use both uppercase and lowercase characters.
SQLSERVER_USER_PASSWORD_REQUIRE_SYMBOL
If set to "true", require that user passwords contain at least one symbol. By default, password complexity is not enforced.
SQLSERVER_USER_PASSWORD_REQUIRE_DIGIT
If set to "true", require that user passwords contain at least one digit. By default, password complexity is not enforced.
SQLSERVER_USER_PASSWORD_PROHIBIT_USERNAME
If set to "true", disallow user passwords that contain the user's username. By default, password complexity is not enforced.
SQLSERVER_USER_PASSWORD_MIN_AGE
The minimum number of days that must elapse following a password change before the user may change their password again. By default, users are not required to wait before changing their password.
SQLSERVER_USER_PASSWORD_MAX_AGE
The maximum number of days that may elapse since the last password change before the user is required to change their password. By default, users are not required to regularly change their password.
SQLSERVER_USER_PASSWORD_HISTORY_SIZE
Remember this number of previous passwords and prohibit reuse of those passwords when the user's password is changed. By default, users are allowed to reuse previous passwords.
SQLSERVER_DEFAULT_MAX_CONNECTIONS
The maximum number of concurrent connections to allow to any particular connection, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connections is not limited.
SQLSERVER_DEFAULT_MAX_GROUP_CONNECTIONS
The maximum number of concurrent connections to allow to any particular connection group, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connection groups is not limited.
SQLSERVER_DEFAULT_MAX_CONNECTIONS_PER_USER
The maximum number of concurrent connections to allow each user to hold to any particular connection, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connections is not limited.
SQLSERVER_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER
The maximum number of concurrent connections to allow each user to hold to any particular connection group, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connection groups is limited to one.
SQLSERVER_ABSOLUTE_MAX_CONNECTIONS
The maximum number of concurrent connections to allow to overall, regardless of user, connection or connection group, where a value of "0" indicates unlimited. By default, overall concurrent usage is not limited.
SQLSERVER_USER_REQUIRED
If set to "true", require that each user have a corresponding account defined within the database, even if the user authenticated through some other mechanism (such as LDAP). By default, users that successfully authenticate through another mechanism are not required to also have an account within the database.
SQLSERVER_TRACK_EXTERNAL_CONNECTION_HISTORY
Whether connections that do not exist within the database should have connection history tracked in the database. If set to "true", connection history records will be created for any connection established. If set to "false", connection history records will be created only for connections defined in the database. By default, external connections will be tracked.
SQLSERVER_ENFORCE_ACCESS_WINDOWS_FOR_ACTIVE_SESSIONS
Whether access time restrictions imposed by the administrator on user accounts should be enforced while a user is logged in. If set to "true", users will be automatically logged out within roughly one minute of reaching their access time limits. If set to "false", access time restrictions will only be enforced at the moment a user attempts to log in. By default, access time restrictions are enforced while users are logged in.
SQLSERVER_AUTO_CREATE_ACCOUNTS
Whether user account entries should automatically be created within the database for users that successfully authenticate through other means, such as an SSO provider or LDAP. This may be necessary if using an extension that requires account-specific storage, like TOTP or per-account approvals. If set to "true", user account entries will automatically be created. By default, administrators must manually create such entries if needed.
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:
SSL_CLIENT_AUTH_URI
A wildcard URI that points to this Guacamole instance and requests SSL/TLS client authentication.
SSL_PRIMARY_URI
A non-wildcard URI that points to this Guacamole instance and does not request SSL/TLS client authentication.
Other, optional environment variables are available for the other properties related to SSL/TLS client authentication:
SSL_CLIENT_CERTIFICATE_HEADER
The name of the header to use to retrieve the URL-encoded client certificate from an HTTP request received from an SSL termination service providing SSL/TLS client authentication. By default, X-Client-Certificate
is used, matching the behavior of the keeper/guacamole-ssl-nginx
image.
SSL_CLIENT_VERIFIED_HEADER
The name of the header to use to retrieve the verification status of the certificate an HTTP request received from an SSL termination service providing SSL/TLS client authentication. This value of this header must be "SUCCESS" (all uppercase) if the certificate was successfully verified. By default, X-Client-Verified
is used, matching the behavior of the keeper/guacamole-ssl-nginx
image.
SSL_MAX_DOMAIN_VALIDITY
The amount of time that the temporary, unique subdomain generated for SSL/TLS authentication may remain valid, in minutes. By default, temporary subdomains are valid for 5 minutes.
SSL_MAX_TOKEN_VALIDITY
The amount of time that a temporary authentication token for SSL/TLS authentication may remain valid, in minutes. By default, temporary authentication tokens are valid for 5 minutes.
SSL_SUBJECT_BASE_DN
The base DN containing all valid subject DNs. If specified, only certificates asserting subject DNs beneath this base DN will be accepted. By default, all DNs are accepted as long as the certificate is valid.
SSL_SUBJECT_USERNAME_ATTRIBUTE
The LDAP attribute or attributes that may be used to represent a username within the subject DN of a user's X.509 certificate. If the least-significant attribute of the subject DN is not one of these attributes, the certificate will be rejected. By default, any attribute is accepted and used as the username.
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
.
TOTP_ISSUER
The human-readable name of the entity issuing user accounts. By default, this is "Apache Guacamole".
TOTP_DIGITS
The number of digits which should be included in each generated code. TOTP allows for 6-, 7-, or 8-digit codes. Longer or shorter codes than this are not possible as they violate the TOTP standard. By default, 6-digit codes will be used.
TOTP_PERIOD
The duration that each generated code should remain valid, in seconds. The code generation period is given in positive integer seconds and may be any value, however the value should be long enough to allow the user a reasonable amount of time to enter their code. Their authentication device will generate a new code after this period elapses. By default, generated codes are valid for 30 seconds.
TOTP_MODE
The hash algorithm that should be used to generate codes. Valid TOTP modes (hashes) are "sha1", "sha256", and "sha512". By default, "sha1" is used.
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
.
UDS_BASE_URL
The base URL of the UDS Enterprise deployment that may leverage Keeper Connection Manager to provide remote access. Keeper Connection Manager will use this URL to contact UDS to authenticate and authorize connection requests.
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.
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:
Docker deployment of guacd with Keeper Connection Manager
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.
To start a guacd instance which listens on TCP port 4822:
where some-guacd
is the name you wish to assign to your container.
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:
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.
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_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.
Docker deployment of Pre-Initialized Database Images with Keeper Connection Manager
For convenience, Docker images for both MySQL and PostgreSQL are provided which automatically initialize themselves using the Apache Guacamole database schema:
An instance of MySQL, automatically initialized with the Apache Guacamole database schema.
An instance of PostgreSQL, automatically initialized with 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
.
Docker deployment of MySQL with Keeper Connection Manager
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.
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.
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 deployment of Postgres with Keeper Connection Manager
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.
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.
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 deployment of NGINX with Keeper Connection Manager for SSL Termination
For convenience, a Docker image for SSL termination using NGINX is provided which automatically configures itself with an SSL certificate:
An instance of NGINX which automatically provides SSL termination for Keeper Connection Manager.
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.
Docker deployment of NGINX for SSL termination with Keeper Connection Manager
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:
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.
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 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:
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.
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.
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) 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.
It is not typically necessary set this environment variable except in cases where custom KCM/Guacamole extensions require a more lenient policy.
Be careful if overriding the default policy is necessary. An overly-strict CSP can easily prevent KCM from performing core required tasks, such as decoding graphical data or making requests to its own REST API.
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) 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.
As HSTS is not always appropriate for all deployments of KCM, particularly if KCM will share a domain with other web applications that do not all support HTTPS, installations of KCM do not enable HSTS by default.
The STRICT_TRANSPORT_SECURITY
environment variable must be set to a value to enable HSTS. A recommended default is available for convenience.
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.
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:
The environment variables in this section are only needed in unusual cases, such as when serving KCM from a non-standard port or when older ciphers or versions of SSL must be enabled. Do not set these variables unless you are certain that doing so is necessary.
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 a non-standard port is used for SSL, this port must additionally be mapped to the standard port, e.g. -p 8443:443
. Setting this variable has no impact on the ports used by Nginx internally within the image.
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.
How to deploy a custom SSL Certificate to Keeper Connection Manager
This page provides details on how to create an SSL certificate for use with the Keeper Connection Manager service.
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.
Ensure that the SSL certificate created for your KCM instance is only used for this purpose. Do not use a wildcard certificate that is shared with other services.
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:
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:
On an annual basis, you will need to renew your cert. Most certificate providers will generate a new cert for you. After certificate renewal, you need to replace the certificate file and restart the service.
Upgrading Keeper Connection Manager with the Docker Manual Install method
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.
Backup and recovery options
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:
Docker compose and other critical files
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.
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.
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.
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Integrating TOTP based authentication for 2FA
Keeper Connection Manager provides support for TOTP as a second authentication factor, verifying the identities of enrolled users using authentication codes generated with the TOTP standard.
To 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:
The image keeper/guacamole
can be modified to support TOTP using environmental variables. See the TOTP_* variables defined in the documentation.
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.
Integrating Duo with Keeper Connection Manager for MFA
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.
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.
The image keeper/guacamole
section in the docker-compose.yaml file can be modified to support Duo using environment variables.
DUO_API_HOSTNAME
REQUIRED. The hostname of the Duo API endpoint that will be used to verify user identities, assigned by Duo when Guacamole was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel.
DUO_AUTH_TIMEOUT
The timeout, in minutes, for in-progress Duo authentication attempts. Authentication attempts exceeding this duration will be invalidated. By default, Duo authentication attempts will time out after 5 minutes.
DUO_CLIENT_ID
REQUIRED. The client ID provided for you by Duo when KCM was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel.
DUO_CLIENT_SECRET
REQUIRED. The client secret provided for you by Duo when KCM was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel.
DUO_REDIRECT_URI
REQUIRED. The user-facing URI that the Duo service can use to redirect an authenticated user's browser back to KCM. This is the URI that you use for the KCM deployment, e.g. https://kcm.company.com
Requiring SSL/TLS Client Authentication with KCM
Keeper Connection Manager can be configured to require SSL/TLS client authentication.
To implement device-based access security with Keeper Connection Manager, this can be accomplished using NGINX client certificates. A client certificate is installed into the web browser of your user's approved devices, and the server will only accept communication from a device with the client certificate installed.
The steps to activate this advanced level of protection is described in the steps below.
(1) Create a Certificate Authority (CA) Key
Generate a CA Key with a strong auto-generated passphrase. Make sure to store the passphrase in your Keeper vault.
(2) Create a CA Certificate
A certificate is created with the CA Key. When answering the questions, you can leave the Common Name and Email empty. Save the information that you entered for Country, State, Locality, and Organization, because you may need these later when renewing the certificate.
Side Note: to analyze the certificate parameters, you can run the below command.
(3) Create a Client Key
For the end-user devices, a client key must be generated. You can decide if you would like to generate one key for all devices, or each user can generate their own key and request a certificate. The process is up to you. Generate a client key with a strong auto-generated passphrase. Make sure to store the passphrase in your Keeper vault.
(4) Create a CSR
For each Client Key, generate a CSR to create a signed certificate.
(5) Sign the CSR with the CA Key
You'll need to enter the CA passphrase from Step 1 to sign the request.
At this point, you now have a signed Client Certificate (client.crt).
(6) Convert the Client Certificate to PKCS#12
To import the certificate into a web browser, a pfx file in PKCS#12 is typically required. Generate the client.pfx file using the command below. A passphrase will be required. This passphrase will be provided to each of the users who need to install the certificate, so it should be used specifically for this purpose.
(7) Add to NGINX Config
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:
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.
Additional environment variables are also available to modify SSL/TLS auth behavior further:
Variable
Description
Default
ADDITIONAL_PROXY_CONFIG
Arbitrary, additional NGINX configuration statements that should be included within the location
block that configures NGINX to proxy Guacamole.
SSL_VERIFY_CLIENT
Controls how and whether NGINX requires and verifies the certificate presented by the client (browser), as provided by the NGINX ssl_verify_client
directive.
on
SSL_VERIFY_DEPTH
Controls how deep NGINX will follow through the client’s certificate chain when attempting to validate their certificate, as provided by the NGINX ssl_verify_depth
directive.
1
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:
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:
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:
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.
Loading...
Approve or Deny User's ability to authenticate with KSM using SSO
In an environment where KCM users may be automatically created from an SSO system, such as SAML or OpenID or PIV/CAC, administrators may wish to more tightly control whether those users are allows to use KCM. To facilitate this, KCM provides administrators an approve/deny workflow to decide whether an individual user should be allowed to authenticate with KCM using that SSO method.
To require approval for users signing in with a particular authentication method, use the require-account-approval
property (or, for Docker, the REQUIRE_ACCOUNT_APPROVAL
environment variable). This property accepts a comma-separated list of the names of all authentication methods that should require administrator approval. KCM supports the following authentication types:
Authentication Method
Name
Encrypted JSON
json
LDAP
ldap
OpenID
openid
SAML
saml
SSL/TLS Client Authentication (PIV/CAC)
ssl
For example, to require administrator approval for SAML and LDAP, you would specify:
The following examples shows a docker.yaml
file with the SAML Authentication method enabled:
Once you have successfully configured and setup the authentication method, the corresponding SSO login method will be displayed on the logic screen of the application. In the following image, the instance has been configured to use the saml
authentication method:
Users with at least one authentication method that needs to be approved or denied will be shown in the user list with a “Pending Login Request” badge next to their username:
Administrators can approve/deny access for that user via that authentication method by editing the user account in KCM:
Instructions for authenticating users with OpenID Connect
Keeper Connection Manager provides support for OpenID Connect for authentication.
The image keeper/guacamole
can be modified to support OpenID using environmental variables. See the OPENID_* variables defined in the documentation.
Instructions for authenticating users with LDAP
Keeper Connection Manager provides support for LDAP authentication.
The image keeper/guacamole
can be modified to support LDAP using environmental variables. See the LDAP_* variables defined in the documentation.
If you installed Keeper Connection Manager using the Docker Install method, this does not come preconfigured with LDAP support. The instructions for activating LDAP are below:
(1) On the local instance, stop the containers.
Auto Docker Install:
Docker Compose Install:
(2) Edit the docker-compose file
Using the simple or custom docker method requires modification of docker-compose.yml file to add LDAP support. As root, edit your docker-compose.yml
file and find the "guacamole
" section.
(3) Restart the containers
Simple Install:
The containers should restart after the upgrade. If not run:
Custom Install:
Configuration is complete.
If you require the use of a custom Root Certificate for your LDAP server, you can volume mount the file /etc/pki/ca-trust/extracted/java/cacerts in your Docker Compose to override this certificate in the guacamole docker container.
Import the certificate into a Java truststore using "keytool".
Volume mount the cacerts file to your target guacamole docker container
Multiple LDAP Servers with KCM
When using the docker version of KCM, you can list the multiple LDAP servers in your docker-compose.yml file using the environment variable LDAP_SERVERS in the environment section of the guacamole service, as shown below:
Using LDAP_SERVERS will automatically create /etc/guacamole/ldap-servers.yml within the guacamole container.
guacConfigGroup
object classWhen connection data is stored within your LDAP directory, each connection is represented by a special type of LDAP group, and permissions related to Guacamole connections can be managed directly with LDAP based on user membership of these groups. Doing this requires schema modifications which add a new object class called guacConfigGroup
.
An LDIF file defining the schema changes in a manner compatible with OpenLDAP is provided by the kcm-guacamole-auth-ldap package within /opt/keeper/share/guacamole-auth-ldap/schema/guacConfigGroup.ldif
. This file can be applied to your OpenLDAP server using the “ldapadd” command:
Once this is done, connections can be defined by creating new guacConfigGroup
objects within the LDAP directory. Each guacConfigGroup
accepts a single guacConfigProtocol attribute, defining the protocol associated with the connection, and any number of guacConfigParameter attributes, each defining a connection parameter name/value pair. Users that should have access to the connection must be added as members of the guacConfigGroup
using the member attribute.
For example, a connection accessible to two users which uses VNC to connect to localhost at port 5900 with the password “secret” could be defined with the following LDIF file:
To read connection data from LDAP, Guacamole’s main configuration file, modify the /etc/kcm-setup/docker-compose.yml
file.
The base DN of all connections defined within LDAP must be specified using the LDAP_CONFIG_BASE_DN
property. This base DN should be the DN of the portion of the LDAP directory whose subtree contains all Guacamole connections accessible via LDAP. Only connections defined within the subtree of this base DN will be visible.
The EXTENSION_PRIORITY
property specifies the order that extensions should be loaded relative to each other. In the following example, all other extensions take priority over LDAP:
To control group membership using LDAP, modify the /etc/kcm-setup/docker-compose.yml
file.
It is also possible grant entire groups access to connections using the seeAlso attribute. This attribute is a standard LDAP attribute, and will be taken into account by Guacamole if the LDAP_GROUP_BASE_DN
property is defined. This property defines the root of the subtree containing all groups which may apply to Guacamole users authenticated using LDAP:
If multiple authentication methods are installed, Guacamole will poll each method as it attempts to authenticate users, and will retrieve connection data from each method once a user has successfully authenticated. This behavior is designed to allow authentication methods to work together, and can be leveraged to authenticate Guacamole users against LDAP while storing the connection data for those users within MySQL, PostgreSQL, or SQL Server.
When reading data from multiple authentication methods, Guacamole compares the unique identifiers of users (usernames) and groups to determine identity. This means that user accounts from different authentication systems will be automatically combined by Guacamole upon successful authentication as long as those user accounts have the same username, and group memberships will take effect across authentication systems so long as the unique names of those groups match.
If both LDAP and a database authentication method have been configured, Guacamole will automatically attempt to authenticate against both systems whenever a user attempts to log in. The LDAP account will be considered equivalent to the database user if the username is identical, and that user will have access to any data associated with them via the database, as well as any visible objects within the LDAP directory. If that user has permission to query their group memberships within LDAP, and Guacamole has been configured to query groups within LDAP, then the user's group membership will also be retrieved upon authentication, and the user will have access to any data associated with those groups via the database.
For a user known to exist within LDAP, that user can be granted permissions to connections within the database by logging in as the administrative user (by default, “guacadmin”) and creating a corresponding database account having the same username. By leaving the password unspecified for the database account, the user will only be able to log in using LDAP, but will still have access to any associated connections defined within the database.
Rather than having to manually look up users or groups within the LDAP directory, and then manually create those same users and groups within Guacamole, it is possible to set up administrative user accounts which can already see and manage available LDAP objects. This streamlines the administrative process, reducing the number of users which must be manually created to one.
To see LDAP objects within Guacamole’s administrative interface, one of the following tasks must be performed:
An administrative user within the Guacamole database, such as the default “guacadmin” user, must be manually created within LDAP with the same username and with sufficient privileges to query all Guacamole users and groups defined within LDAP.
An administrative user must be manually created within Guacamole having the same username as an LDAP user with sufficient privileges to query all Guacamole users and groups defined within LDAP.
Because a Guacamole user created as defined above would have access to LDAP users and groups, database users and groups, and database connections, all of this data will be unified within the same administrative interface within Guacamole. The user will be able to grant LDAP users and groups access to connections within the database to just as they would if only the database were in use.
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Keeper Connection Manager installation instructions in the cloud or on-prem environments.
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.
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.
The container running Keeper Connection Manager needs network access to the target desktops/systems that will be managed.
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.
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.
If you plan to use Let's Encrypt as your CA, you should open port 80 and 443. LetsEncrypt uses port 80 to perform automated SSL certificate generation.
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.
Keeper Connection Manager can be installed using one of the following methods.
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.
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 Connection Manager security and encryption model
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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
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
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
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.
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.
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
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.
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.
Keeper has partnered with Bugcrowd to manage our vulnerability disclosure program.
Please submit reports through [https://bugcrowd.com/keepersecurity].
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:
Secrets Manager Encryption Model
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.
Get your environment, network, and system ready and prepared.
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:
Start by choosing "use a self-signed certificate" (for testing)
Choose "Let's Encrypt" to generate a 90 day auto-renewing cert (requires 80 and 443 open)
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:
Create/Identify and establish root access to the server that will run the Keeper Connection Manager gateway
Decide if you want your KCM gateway to be public-facing (assign public IP), or internal-only (assign private IP)
Add internal/external DNS A Record (or AAAA record) to point your domain to your KCM server's IP address
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.
To check your that your linux system's entropy level is at least 1000, use the command:
To increase the speed of entropy generation, you can install the haveged
service to ensure that the environment can efficiently create secure random numbers.
On RHEL, the haveged
package is not available from the Red Hat repositories and must instead be installed from the EPEL repository. EPEL provides instructions for configuring their repository here: https://docs.fedoraproject.org/en-US/epel/. After EPEL is installed, run the following commands:
If Podman is installed, you must run the following two commands before installation:
Instantly access your infrastructure with zero-trust security.
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
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
Keeper is typically deployed as a Docker container. The system architecture diagram is below.
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.
Ready to get started with Keeper Connection Manager? Proceed to the installation instructions.
Automated Linux Docker installer for users without Docker experience
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.
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.
(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.
If you want to use Let's Encrypt (option 1) to quickly and easily generate and install an SSL certificate, you must have public DNS in place pointing to your static public IP. Also, Let's Encrypt requires HTTP port 80 and HTTPS port 443 to be open during the install process.
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.
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.
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.
Store the provided username, password, and URL in your Keeper Vault
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.
How to Use KCMThe next section of this documentation reviews the process of managing, upgrading and adding packages to the Docker Compose environment.
Upgrading Keeper Connection Manager with the Docker Automated Install method
Before making any changes to your environment, we recommend backing up in accordance with the instructions on the Backup and Recovery page.
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.
If you run into any issues during the upgrade, see Troubleshooting
Activating your Keeper Connection Manager license key
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.
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
To obtain a license key, please contact Keeper Support directly at: https://www.keepersecurity.com/support.html
Upon request, Keeper staff will generate and send a copy of your license key.
To install your license key, follow the steps below:
During the installation process, you will be prompted to input the license key.
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:
(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:
Deployment of Keeper Connection Manager using Docker Compose
This section describes how to install Keeper Connection Manager using Docker by building a customized docker-compose orchestration file.
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.
Ubuntu
Install the haveged
package to ensure that the environment is capable of generating enough entropy for creating secure random numbers.
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.
Copy this file to your target KCM instance. Please note that you'll need to modify a few of the fields immediately:
shm_size should be roughly half of available physical memory on the instance.
security_opt refers to the path of the seccomp security profile and must be included for remote browser isolation.
GUACAMOLE_PASSWORD and MYSQL_PASSWORD need to match, and should be a randomly generated strong password. We recommend using your Keeper vault for generating a password. Avoid using special characters like backslashes, dollar signs and forward slashes.
GUACAMOLE_ADMIN_PASSWORD is the password for the default "guacadmin" user login. This should be a strong and randomly generated password. We recommend using your Keeper vault for generating a password. Avoid using special characters like backslashes, dollar signs and forward slashes.
SSL_HOSTNAME needs to be the FQDN you set up to point to this server. Make sure that the DNS is routable to the IP from the outside world, and ports 80/443 are open so that Let's Encrypt can register the certificate.
Copy this file to your target KCM instance. Please note that you'll need to modify a few of the fields immediately:
shm_size should be roughly half of available physical memory on the instance.
security_opt refers to the path of the seccomp security profile and must be included for remote browser isolation.
GUACAMOLE_PASSWORD and POSTGRES_PASSWORD need to match, and should be a randomly generated strong password. We recommend using your Keeper vault for generating a password. Avoid using special characters like backslashes, dollar signs and forward slashes.
GUACAMOLE_ADMIN_PASSWORD is the password for the default "guacadmin" user login. This should be a strong and randomly generated password. We recommend using your Keeper vault for generating a password. Avoid using special characters like backslashes, dollar signs and forward slashes.
SSL_HOSTNAME needs to be the FQDN you set up to point to this server. Make sure that the DNS is routable to the IP from the outside world, and ports 80/443 are open so that Let's Encrypt can register the 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
.
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.
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
.
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.
Below is a description of each of the images.
The Apache Guacamole proxy daemon, guacd, with support for native protocols such as RDP and SSH.
An instance of MySQL, automatically initialized with the Apache Guacamole database schema.
An instance of PostgreSQL, automatically initialized with the Apache Guacamole database schema.
An instance of NGINX which automatically provides SSL termination for Keeper Connection Manager.
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.
How to Use KCMThe next several sections of this installation guide provide detailed information about each specific Docker image, if you plan to customize or modify the environment.
Configuration of Keeper Connection Manager Authentication methods
Keeper Connection Manager supports multiple authentication mechanisms which can be enabled through installing additional packages.
If you wish to enable multi-factor authentication in front of Keeper Connection Manager, you may do so with Duo or TOTP.
Instructions for authenticating users with a SAML 2.0 / SSO Identity Provider
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.
Run the reconfigure
command listed below and press enter to accept all the pre-populated selections until you get to the SAML prompt.
Make sure you have transferred your metadata XML file onto the KCM server first.
Select Local metadata file (option 1). Enter the proper path where the XML file is located.
Remote metadata file (option 2) is easiest if you can get a URL that points to your idP's metadata XML file (Azure provides this).
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.
Microsoft AzureOktaGoogle WorkspaceOneLoginPingIdentityEnter 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!
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.
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:
This documentation will detail how to connect your Oracle Cloud environment to Keeper Security Connection Manager for the purpose of Single Sign-On.
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 SAML configuration with Microsoft Azure
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.
For hybrid environments, if the group originates from on-prem AD, you may need to change the display name of the security group.
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.
Azure Group to Keeper Connection Manager Group mapping is unique. KCM will not show a list of the members of a group, however, group member users will have access to any connections that are assigned to the group.
(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 SAML configuration with Okta
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.
Okta Group to Keeper Connection Manager Group mapping is through the Group Name. If the Keeper Connection Manager contains a Group that has the name corresponding to the Okta Group Name, the user will receive all Keeper connections assigned to that user group.
(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 SAML configuration with OneLogin
The first step regardless of installation method is to configure your SAML 2.0 identity provider.
You must have OneLogin developer account.
Configure OneLogin
Log in to the OneLogin Dashboard, and click Administration. Then Applications > Add App.
Search for SAML, and select SAML Test Connector (IdP).
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.
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.
Click on the More Actions dropped-down menu. Select SAML Metadata to download and save the .XML file.
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.
This page documents the process of integrating PingIdentity with Keeper Connection Manager, which is also known as KCM. We will be adding SAML 2.0 application connectors between the two platforms.
Login as an Administrator for PingIdentity. From the PingIdentity menu, click Applications > Add Application
Give the Application a name such as "KCM," select SAML and Save.
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
Then add the URL of your KCM server to the Entity ID box as follows: https://<YOUR DOMAIN> and press Save.
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.
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.
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.
Download the Metadata file from the Configuration tab, and ensure that it is named to metadata.xml.
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.
Keeper Connection Manager SAML configuration with Google Workspace
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.
Google Group to Keeper Connection Manager Group mapping is through the Group Name. If the Keeper Connection Manager contains a Group that has the name corresponding to the Google Group Name, the user will receive all Keeper connections assigned to that user group.
(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.
Login to Keeper Connection Manager with a PIV/CAC device
KCM allows authentication with the web application using the DoD's Common Access Cards (CAC), as well as with any smart card supported by the browser for SSL client auth such as Personal Identity Verification (PIV).
This feature allows users to authenticate to Keeper Connection Manager using CAC, this does not allow pass-through of CAC to the remote desktop.
This support depends on an SSL termination instance providing SSL/TLS authentication, a capability that was added to KCM version 2.12.0.
A typical configuration for PIV/CAC would be the following:
An SSL termination instance configured with two hostnames: one for normal access (such as kcm.example.net
) and another just for handling SSL client auth, which should ideally be a wildcard domain (such as *.login.kcm.example.net
). The SSL client auth configuration would include the certificate of the CA providing the PIV/CAC cards.
PIV/CAC support installed and configured to authenticate users against *.login.kcm.example.net
and redirect them back to kcm.example.net
once ready.
Database backend configured to automatically create user accounts for users coming from SSO.
User creation workflow configured to require approval for users that SSO from PIV/CAC.
Support for PIV/CAC is configured using Keeper's new support for SSL/TLS client authentication. This support is provided by the “guacamole-auth-sso-ssl” extension, which we package as kcm-guacamole-auth-sso-ssl
. Setting any SSL_*
variable will implicitly include the kcm-guacamole-auth-sso-ssl
package.
The following options will need to be set in the keeper/guacamole Docker container definition (or in guacamole.properties for linux distributions):
ssl-client-auth-uri
SSL_CLIENT_AUTH_URI
REQUIRED. A wildcard URI that points to this Guacamole instance and requests SSL/TLS client authentication.
ssl-primary-uri
SSL_PRIMARY_URI
REQUIRED. A non-wildcard URI that points to this Guacamole instance and DOES NOT request SSL/TLS client authentication.
ssl-subject-base-dn
SSL_SUBJECT_BASE_DN
The base DN containing all valid subject DNs. If specified, only certificates asserting subject DNs beneath this base DN will be accepted.
By default, all DNs are accepted.
ssl-subject-username-attribute
SSL_SUBJECT_USERNAME_ATTRIBUTE
The LDAP attribute or attributes that may be used to represent a username within the subject DN of a user's X.509 certificate. If the least-significant attribute of the subject DN is not one of these attributes, the certificate will be rejected.
By default, any attribute is accepted.
The following options are also available, though it would be unusual to need to set them:
ssl-client-certificate-header
SSL_CLIENT_CERTIFICATE_HEADER
The name of the header to use to retrieve the URL-encoded client certificate from an HTTP request received from an SSL termination service providing SSL/TLS client authentication.
This should not normally need to be set, as the defaults of the keeper/guacamole-ssl-nginx
image match the default value of this option.
X-Client-Certificate
ssl-client-verified-header
SSL_CLIENT_VERIFIED_HEADER
The name of the header to use to retrieve the verification status of the certificate an HTTP request received from an SSL termination service providing SSL/TLS client authentication. This value of this header must be "SUCCESS" (all uppercase) if the certificate was successfully verified.
This should not normally need to be set, as the defaults of the keeper/guacamole-ssl-nginx
image match the default value of this option.
X-Client-Verified
ssl-max-domain-validity
SSL_MAX_DOMAIN_VALIDITY
The amount of time that the temporary, unique subdomain generated for SSL/TLS authentication may remain valid, in minutes.
This subdomain is used to ensure each SSL/TLS authentication attempt is fresh and does not potentially reuse a previous authentication attempt that was cached by the browser or OS. This interval must be long enough to allow for network delays in authenticating the user with the SSL termination service that enforces SSL/TLS client authentication, but short enough that an unused domain does not consume unnecessary server resources and cannot potentially be guessed while that subdomain is still valid. These subdomains are 128-bit secure random values.
This should not normally need to be set, though it’s conceivable that an administrator may wish to reduce this value.
5
ssl-max-token-validity
SSL_MAX_TOKEN_VALIDITY
The amount of time that a temporary authentication token for SSL/TLS authentication may remain valid, in minutes.
This token is used to represent the user's asserted identity after it has been verified by the SSL termination service. This interval must be long enough to allow for network delays in receiving the token, but short enough that unused tokens do not consume unnecessary server resources and cannot potentially be guessed while the token is still valid. These tokens are 256-bit secure random values.
This should not normally need to be set, though it’s conceivable that an administrator may wish to reduce this value.
5
Authenticating with PIV/CAC (or any smart card) via the browser is using SSL/TLS client authentication. This capability was further enhanced for PIV/CAC by adding convenient configuration options for testing whether certificates have been revoked via OCSP or a CRL. For reference, the following are all options related to SSL/TLS client authentication currently supported by the keeper/guacamole-ssl-nginx Docker image:
ADDITIONAL_PROXY_CONFIG
Arbitrary, additional NGINX configuration statements that should be included within the location
block that configures NGINX to proxy Guacamole.
CLIENT_CERTIFICATE_FILE
The certificate that NGINX should use to verify the certificate presented by the SSL/TLS client.
CLIENT_CRL_FILE
Controls the certificate revocation list (CRL) file that NGINX should use to check whether a client’s certificate has been revoked, as provided by NGINX ssl_crl
directive. This file must be in PEM format and may contain multiple CRLs. If omitted, no CRL file will be used.
This variable will be ignored unless CLIENT_CERTIFICATE_FILE
is specified.
If available, OCSP is often preferable to using a CRL file.
CLIENT_OCSP
Controls whether NGINX will use OCSP to check whether a client’s certificate has been revoked, as provided by NGINX ssl_ocsp
directive. Setting this variable to on
will use OCSP to check client certificates.
This variable will be ignored unless CLIENT_CERTIFICATE_FILE
is specified.
If enabled, RESOLVER
must also be specified.
off
RESOLVER
The DNS server that NGINX should use to resolve domain names. This is only required if OCSP is enabled.
SSL_VERIFY_CLIENT
Controls how and whether NGINX requires and verifies the certificate presented by the client (browser), as provided by NGINX ssl_verify_client
directive.
on
SSL_VERIFY_DEPTH
Controls how deep NGINX will follow through the client’s certificate chain when attempting to validate their certificate, as provided by NGINX ssl_verify_depth
directive.
1
The example docker-compose.yml
below uses the following placeholders:
Placeholder
Description
PasswordForPostgresAdmin
Some reasonable password to assign to PostgreSQL’s postgres
user - the typical root user of a PostgreSQL database. This account is used only if an administrator needs to manually connect to the database using a tool like psql
.
guacamole_db
The name of the Guacamole database within PostgreSQL. This value is used automatically by kcm-setup.run
and is documented as a reasonable value both within Keeper’s docs and upstream, so it is uncommon to use any other value here.
guacamole_user
The limited-privilege PostgreSQL user that Guacamole should use to execute queries against its database. This value is used automatically by kcm-setup.run
and is documented as a reasonable value both within Keeper’s docs and upstream, so it is uncommon to use any other value here.
PasswordForGuacamole
Some reasonable password to assign to the PostgreSQL user that Guacamole will use to authenticate with the database as the limited-privilege account guacamole_user
and execute queries.
ou=test department,o=u.s. government,c=us
The base DN of the subject DNs that should be accepted when presented via SSL/TLS client authentication (smart card authentication via browser).
kcm.example.net
The domain that users will visit with their browsers to use KCM.
/path/to/pki
The path on the Docker host containing the certificates and private keys used for SSL, including for client authentication.
/pki
The path within the Docker container that /path/to/pki
should be mounted to, so that its files may be accessed by NGINX.
cac-certificate.pem
The filename of the PEM-format certificate that NGINX should use to validate the certificates it receives from users when they attempt to authenticate with smart cards.
In practice, these values will vary, as will whether the user chooses to use MySQL or PostgreSQL. The example below was written using PostgreSQL.
Prior to configuring the user workflow, make sure to set the REQUIRE_ACCOUNT_APPROVAL
key to the appropriate authentication method.
For PIV/CAC, you would set it to ssl
:
Once you have successfully configured, there will be a new "Use Certificate or Smart Card" link on the login screen of the application as seen below:
For additional details on user creation workflow, visit this page.
For each end-user client device that will need access to Keeper Connection Manager, you may need to install the internal CA as a trusted authority into the user's browser. The installation of CA trusted authority varies by platform.
The maximum amount of time to allow for any LDAP network operation, in milliseconds, including attempts to connect to the LDAP server. By default, LDAP network operations will time out after 30 seconds (30000 milliseconds). Note that this value is intentionally more granular than LDAP_OPERATION_TIMEOUT
, as failover to alternative LDAP servers may need to occur quickly
Remote connection protocols supported by Keeper Connection Manager
Keeper Connection Manager and Apache Guacamole support multiple protocols through a common, centralized gateway. The "guacd" service sits between the Guacamole web application and the remote desktops and dynamically translates between low-level remote desktop protocols and the Guacamole protocol, applying additional optimization and compression in the process.
Within Keeper Connection Manager, support for each protocol is provided via separate packages. Only the packages for protocols that you will be using need be installed:
kcm-libguac-client-http
kcm-libguac-client-vnc
kcm-libguac-client-rdp
kcm-libguac-client-ssh
kcm-libguac-client-telnet
kcm-libguac-client-kubernetes
kcm-libguac-client-mysql
kcm-libguac-client-postgres
kcm-libguac-client-sql-server
When using any particular connection, the package providing support for that connection's underlying protocol must already be installed on the server running the guacd service. If support for the underlying protocol has not been installed, users attempting to use the connection will see an error message, and system administrators will see a message like the following within the systemd journal:
If a needed package was not installed and a message like that above is logged, installing the needed package will solve the problem. If using the keeper/guacd Docker image, all protocol support is already installed. If using the @kcm-guacamole
package group, as described within the installation instructions, protocol support for HTTPS, VNC, RDP, and SSH is installed.
When using one of the supported databases, administrators can define new connections using Guacamole's web interface, selecting the protocol to be used for that connection from a dropdown menu labeled "Protocol":
If defining a connection through a mechanism which does not leverage one of the supported databases, such as via /etc/guacamole/user-mapping.xml
, LDAP schema modifications, or encrypted JSON, the protocol will must be specified using the unique, internal name for that protocol:
http
vnc
rdp
ssh
telnet
kubernetes
mysql
postgresql
sql-server
Advanced configuration of Kubernetes connection type
Keeper's Kubernetes support takes the form of a protocol implementation which allows Keeper to attach to the consoles of Kubernetes containers using Kubernetes' REST API. As with SSH and telnet, Keeper's Kubernetes support emulates a terminal on the server side which renders to the Keeper Connection Manager client's display.
This document is intended to cover all supported parameters, grouped in the same way they are grouped within the web interface. The field headings which would appear in the web interface are provided for each parameter, along with each parameter's internal name and a thorough description of the behavior and legal values for that parameter.
Connecting to a Kubernetes server in order to attach to a container involves establishing a WebSocket connection with that server, and requires the server's hostname or IP address. Depending on the Kubernetes server, SSL/TLS may also be required for the connection.
Attaching to a particular Kubernetes container naturally required the name of the pod containing the container in question. By default, Guacamole will attach to the first container in the pod. If there are multiple containers in the pod, you may wish to also specify the container name.
If enabled, Kubernetes uses SSL/TLS for both encryption and authentication. Standard SSL/TLS client authentication requires both a client certificate and client key, which Guacamole will use to identify itself to the Kubernetes server.
Keeper Connection Manager's Kubernetes support provides a display, but not in the same sense as a remote desktop protocol like VNC or RDP. The display is a terminal emulator, and thus provides options for configuring the font used and its size.
If selecting a different font for a Kubernetes connection, the chosen font must be installed on the server running guacd. It is the server that will handle rendering of characters to the terminal display, not the client.
Custom color schemes may be provided for the terminal emulator used by Kubernetes connections. Custom schemes mimic the format used by Xterm and consist of a semicolon-separated series of name-value pairs. Each name-value pair is separated by a colon and assigns a value to a color in the terminal emulator palette.
For example, to use blue text on white background by default, and change the red color to a purple shade, you would specify:
Legal color names are:
"foreground
" - the default foreground color.
"background
" - the default background color.
"colorN
" - the color at index N within the Xterm 256-color palette. For example, "color9" refers to the color at palette index 9, normally red.
Legal color values are:
"rgb:RR/GG/BB" - a color in RGB format, with each component in hexadecimal. For example, "rgb:ff/00/00
" specifies the color red. Each hexadecimal component may be one to four digits, but the effective values are always zero-extended or truncated to two digits; for example, "rgb:f/8/0
", "rgb:f0/80/00
", and "rgb:f0f/808/00f
" all refer to the same effective color.
"colorN
" - the color currently assigned to index N within the Xterm 256-color palette. For example, "color9
" specifies the color currently assigned to palette index 9. Note that the current color value is used rather than a reference to that color. If the referenced color is changed later in the color scheme configuration, that new color value will not be reflected in this assignment.
In most cases, the default behavior of the Guacamole terminal emulator works without modification. However, when connecting to certain systems, the terminal behavior may need to be tweaked to allow it to operate properly. Guacamole's Kubernetes support provides parameters for controlling the control code sent for backspace.
The full, raw text content of Kubernetes sessions, including timing information, can be recorded automatically to a specified directory. This recording, also known as a "typescript", will be written to two files within the directory specified: one file contains the raw text data, and the other contains timing information. Where "NAME
" is the value provided for the typescript name, these files will be named "NAME
" and "NAME.timing
" respectively.
This format is compatible with the format used by the standard UNIX script
command, and can be replayed using scriptreplay
(if installed). For example, to replay a typescript called "NAME
", you would run:
When using LDAP_SERVERS in your docker-compose.yml, don't volume mount the ldap-servers.yml file (since this will be handled automatically). For advanced or non-docker installations, .
Support for attaching to Kubernetes containers is controlled through the use of several parameters. When a database like MySQL or PostgreSQL is used, these parameters are presented in a convenient web interface. If defining connections through another mechanism, such as through or, parameters are specified using their internal parameter names.
"NAME
" - the color with human-readable name "NAME
", where "NAME
" is one of the . These names generally correspond to the names standardized by the W3C for CSS.
Kubernetes sessions can be recorded graphically. These recordings take the form of Apache Guacamole protocol dumps and are recorded automatically to a specified directory. Recordings can be subsequently played back using the hosted at (or using a local deployment of this application).
The player is a static web application, using only JavaScript to play back provided recordings. This functionality is implemented strictly locally; the recordings are not uploaded to a remote service for processing. If you would prefer to use your own deployment of this application, or would like to investigate the source, the full source of the Glyptodon Enterprise Session Recording Player can be found on GitHub, along with instructions for local deployment:
The latest version of Keeper Connection Manager supports on-screen playback of recorded sessions. See the documentation page.