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

Login Screen

Login options and customization.

Home Screen

Selecting connections and user settings.

Launching Connections

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

Connection Screen

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

Creating Connections

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

File Transfer

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

Sharing Connections

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

Session Recording

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

AWS EC2 Discovery

Automatically discover your EC2 instances for dyanamic connections.

Credential Pass-Through

Pass through tokens from the login screen to the target connections.

Dynamic Connections

Launch connections using arbitrary parameters through signed JSON requests.

Custom Branding

Customize the look and feel of the Keeper Connection Manager instance.

About

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

Logging In

Username

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

Password

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

Other Login Methods

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

Login Attempt Limits

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

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

Overview

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

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

My Connections

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

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

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

User Menu

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

Home

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

Settings

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

Logout

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

About Connections

Connections specify the protocol and customizable parameters that define the authentication and customized behavior. Connections can be created from the Settings menu. Only users with "Create new connections" permission can create connections.

Administrators can define which connections are available for users and groups.

Use Cases

Connections can be created and utilized in several ways. Connections can be privileged (credentials hidden from the user) and the connections can support user-specified credentials. Additionally, the connections can pull credentials from one or more Keeper Vaults via the Keeper Secrets Manager integration.

Privileged Connections

When setting up a privileged connection, the authentication credentials to the target can be saved in the connection parameters, or in the designated Keeper Vault. When the credentials are stored directly to the connection or in the Keeper Vault, they are never exposed to the end-user. This allows you to create privileged sessions in which the user does not have access to the underlying credentials.

User-Specified Credentials

When setting up the connection, you can skip the authentication details parameters and Keeper Connection Manager will prompt the end-user for their authentication credentials on every login.

For example, with an RDP connection, simply remove the credentials from the connection parameters and the user will be prompted to authenticate.

Vault Credentials

KCM can connect to a Keeper Vault and search for the necessary credentials needed based on Host, User and Domain. See the Vault Integration section to learn more about this capability.

Create a New Connection

The New Connection form is separated into multiple sections each with multiple inputs. Connections have many different options and capabilities, depending on the protocol.

To begin, click Settings > Connections > New Connection which will open the new connection form.

Connection Details

Connection Name

The name of the connection, this is how it will appear in the connections list.

Location

The location of the new connection in the connections list. You can select "ROOT" to put the new connection at the top level of the connections list, or select a collection to place the new connection under an existing collection.

Protocol

Select the type of connection to create. The current available connection types are:

• RDP

• SSH

• Kubernetes

• Telnet

• VNC

• MySQL

• PostgreSQL

• Microsoft SQL Server

• Remote Browser Isolation

For more information about connection types, see the supported protocols section.

Batch Import for Connections

Create multiple connections via API or by uploading a CSV, JSON, or YAML file. Visit the following page for more information:

Concurrency Limits

Max # of Connections

The maximum allowed number of concurrent sessions for this connections. If the maximum number is sessions are already in use, other users will not be able to connect to this connection.

Max # of Connections per User

The maximum allowed number of concurrent sessions for this connection for each user. If the maximum number is sessions are already in use by a user, the user will not be able to open a new session for this connection.

Load Balancing

Keeper Connection Manager can use load balancing among connections in a group to give multiple concurrent users the best experience.

Connection Weight

Enter a number to use as a multiplier of connection assignment. For example, if one connection in a group has a weight of 1, and another has a weight of 2, the second connection will be assigned twice as many concurrent users as the first.

Use for Failover Only

If checked, this connection will only be used if all other connections in the group fail

Guacamole Proxy Parameters

If you are establishing a connect through a guacd service which is operating on a separate server (other than localhost), you would specify the proxy parameters here. In most default installations, this section is not needed and should be left empty. For more information see the guacd documentation.

Hostname and Port

Hostname and port of the proxy

Encryption

Choose if the connection traffic should be encrypted. You can choose unencrypted or TLS/SSL encryption.

RDP Protocol Parameters

Details to facilitate the new RDP connection. Set network and authentication details.

Network

Hostname and Port

Enter the hostname and port of the RDP connection

Authentication

Enter the following connection fields for you RDP connection:

• Username

• Password

• Domain

Security Mode

Select the security mode to use, the supported modes are:

• Any

• NLA (Network Level Authentication)

• RDP Encryption

• TLS Encryption

• Hyper-V / VMConnect

Disable Authentication

Choose to turn off authentication for this RDP connection

Ignore Server Certificate

Choose to ignore the server certificate. In most cases, this is required to establish a connection.

Remote Desktop Gateway

Fill in the following details about the remote desktop gateway:

• Hostname and Port

• Username

• Password

• Domain

Basic Settings

Initial Program

Start a program on connection. Enter the location of the program to run

Client Name

Set a name for the computer this connection is connecting to

Keyboard Layout

Choose the type of keyboard to use with this RDP connection

Time Zone

Use the dropdown menus to select the timezone to use with this connection

Enable Multi-touch

Choose to allow multi-touch input for this RDP connection

Administrator Console

Choose to allow access to the Administrator Console for users connecting to this RDP connection

Appearance

Choose settings that affect how the new connection will look.

Width, Height and Resolution

Choose the dimensions and resolution of the screen in pixels (pixels per inch for resolution).

Color Depth

Choose the color depth of the screen over the RDP connection.

Force Lossless Compression

Use lossless compression. Check this option for better visual quality, but it may impact performance.

Resize Method

Choose what the connection should do if the window is resized. Keeper Connection Manager supports "Display Update" Visual channel for RDP 8.1 or higher. For older versions of RDP, use the reconnect method.

Read-Only

If checked, the connection will not allow for any interaction from the user. The user will be able to view what is happening on the connected device, but make no interactions with it.

Clipboard

Disable Copying from Remote Desktop

If selected, users will not be able to copy from the connection

Disable Pasting from Client

If selected, users will not be able to paste values into the connection

Device Redirection

Choose options for connected devices

Support Audio in Console

Choose if audio is supported within the console

Disable Audio

Choose if audio from the connection should be disabled

Enable Audio Input (microphone)

Choose if the user's microphone can be used within the connection

Enable Printing

Choose if users can print from the connection

Redirected Printer Name

If allowing printing, choose the name of the printer to use

Enable Drive

If you would like to transfer files to this target with Drag and Drop, select this option. Along with this, make sure to fill out a "Drive Name", "Drive Path", and select "Automatically Create Drive".

Drive Name

If file transfer is enabled, the name of the drive to use. For example "My Drive".

Disable File Download

Choose if files can be downloaded to the connected drive

Drive Path

The path of the drive to use if enabled. A typical default Drive Path would be something like /var/lib/guacamole/drives/${GUAC_USERNAME}

Automatically Create Drive

If selected, Keeper Connection Manager will automatically create a drive to use with the connection

Static Channel Names

A comma-separated list of static channel names to open and expose as pipes. If you wish to communicate between an application running on the remote desktop and JavaScript, this is the best way to do it. KCM will open an outbound pipe with the name of the static channel. If JavaScript needs to communicate back in the other direction, it should respond by opening another pipe with the same name. KCM allows any number of static channels to be opened, but protocol restrictions of RDP limit the size of each channel name to 7 characters.

Performance

These options can be used to optimize the performance of the Windows Remote Desktop Connection.

Choose to enable or disable the following optional Windows features:

• Enable Wallpaper

• Enable Theming

• Enable Font Smoothing (ClearType)

• Enable Full-window Drag

• Enable Desktop Composition (Aero)

• Enable Menu Animations

• Disable Bitmap Caching

• Disable Off-screen Caching

• Disable Glyph Caching

RemoteApp

Recent versions of Windows provide a feature called RemoteApp which allows individual applications to be used over RDP, without providing access to the full desktop environment. If your RDP server has this feature enabled and configured, you can configure KCM connections to use those individual applications.

Program

Specifies the RemoteApp to start on the remote desktop. If supported by your remote desktop server, this application, and only this application, will be visible to the user.

Windows requires a special notation for the names of remote applications. The names of remote applications must be prefixed with two vertical bars. For example, if you have created a remote application on your server for notepad.exe and have assigned it the name “notepad”, you would set this parameter to: “||notepad”.

Working Directory

The working directory, if any, for the remote application. This parameter has no effect if RemoteApp is not in use.

Parameters

The command-line arguments, if any, for the remote application. This parameter has no effect if RemoteApp is not in use.

Load Balancing

Keeper Connection Manager can use load balancing among connections in a group to give multiple concurrent users the best experience.

Connection Weight

Enter a number to use as a multiplier of connection assignment. For example, if one connection in a group has a weight of 1, and another has a weight of 2, the second connection will be assigned twice as many concurrent users as the first.

Use for Failover Only

If checked, this connection will only be used if all other connections in the group fail

Screen Recording

Options for recording of the screen. See the Session Recording section for more information.

Recording Path

Enter the path to save the session recording. We recommend using the below value: ${HISTORY_PATH}/${HISTORY_UUID}

Recording Name

Enter the name of the recording file

Exclude Graphics/Streams

Choose to exclude graphics or streams from the recording

Exclude Mouse

Choose to exclude the mouse from the screen recording

Exclude Touch Events

Choose to exclude the touch events the user made from the recording

Include Key Events

If selected, include key events that would not otherwise be visible in the recording

Automatically Create Recording Path

If selected, Keeper Connection Manager will automatically create a path for the recording file

SFTP

Options for file transfers to the connection using SFTP. For more information see the File Transfer section.

Enable SFTP

Choose to enable SFTP file transfers

If enabled, enter the following information to connect to and authenticate connection to your SFTP server:

• Hostname Port

• Public Host Key (Base64)

• Username and Password

• Private Key

• Passphrase for the private key if applicable

File Browsing Root Directory

The root directory of the SFTP server to display within this connection

Default Upload Directory

If users upload a file from the connection, the directory that the file will go to by default

SFTP Keepalive Interval

Enter the keepalive interval as a number

Disable File Download

If SFTP is enabled, check this option to exclude users from downloading files from the server to this connection

Disable File Upload

If SFTP is enabled, check this option to exclude users from uploading files to the server from this connection

Wake-on-LAN (WoL)

Options to facilitate waking the connected device upon connection if supported.

Send WoL Packet

Enable Wake-on-Lan and send a signal from Keeper Connection Manager

Mac Address of the Remote Host

Identify the device to send the signal to by Mac Address

Broadcast Address for WoL Packet

Where to send the WoL signal

Host Boot Wait Time

How long to wait for the device to wake

SSH Protocol Parameters

Details to facilitate the new SSH connection. Set network and authentication details.

Network

Hostname and Port

Enter the hostname and port for the SSH connection

Public Host Key (Base64)

Enter the Public Key for this SSH connection in Base64 format

Authentication

Username and Password

The username and password (if required) for this SSH connection.

Private Key

The private key used for connecting to this SSH connection

Passphrase

The passphrase (if any) for the private key

Appearance

Choose settings that affect how the new connection will look.

Theme

Select a color theme for the terminal.

There are built in themes, and a custom theme option.

Font Name

Enter the name of a font for the terminal to use

Font Size

Select the pixel size of the font

Maximum Scroll back Size

Select how far back a user can scroll through past commands. Leave blank for unlimited.

Read-Only

If checked, the connection will not allow for any interaction from the user. The user will be able to view what is happening on the connected device, but make no interactions with it.

Clipboard

Disable Copying from Remote Desktop

If selected, users will not be able to copy from the connection

Disable Pasting from Client

If selected, users will not be able to paste values into the connection

Session/Environment

Settings for basic environment setup

Execute Command

Enter a command to execute on connection start

Language/Local($LANG)

Set the language/local for the connection, this sets the $LANG environment variable

Time Zone($TZ)

Set the time zone for the connection. This sets the $TZ environment variable

Server Keepalive Interval

Set an interval for a keepalive signal

Terminal Behavior

The Terminal Behavior section contains options about the terminal for applicable connections.

Backspace Key Sends

Choose what action is sent when you click the backspace key. The options are:

• Delete

• Backspace

Terminal Type

Choose the type of terminal to use. The options are:

• ansi

• linux

• vt100

• vt220

• vterm

• vterm-256color

Screen Recording

Options for recording of the screen. See the Session Recording section for more information.

Recording Path

Enter the path to save the session recording. We recommend setting this to ${HISTORY_PATH}/${HISTORY_UUID}

Recording Name

Enter the name of the recording file

Exclude Graphics/Streams

Choose to exclude graphics or streams from the recording

Exclude Mouse

Choose to exclude the mouse from the screen recording

Include Key Events

If selected, include key events that would not otherwise be visible in the recording

Automatically Create Recording Path

If selected, Keeper Connection Manager will automatically create a path for the recording file

SFTP

Options for file transfers to the connection using SFTP. For more information see the File Transfer section.

Enable SFTP

Choose to enable SFTP file transfers

File Browsing Root Directory

The root directory of the SFTP server to display within this connection

Disable File Download

If SFTP is enabled, check this option to exclude users from downloading files from the server to this connection

Disable File Upload

If SFTP is enabled, check this option to exclude users from uploading files to the server from this connection

Wake-on-LAN (WoL)

Options to facilitate waking the connected device upon connection if supported.

Send WoL Packet

Enable Wake-on-Lan and send a signal from Keeper Connection Manager

Mac Address of the Remote Host

Identify the device to send the signal to by Mac Address

Broadcast Address for WoL Packet

Where to send the WoL signal

Host Boot Wait Time

How long to wait for the device to wake

VNC Protocol Parameters

Details to facilitate the new VNC connection. Set network and authentication details.

Network

Hostname and Port

Hostname and port information for the VNC connection

Encryption

Choose encryption method for connection traffic. The options are:

• No Encryption

• TLS/SSL Encryption

Authentication

Username and Password

Login credentials for the VNC connection. If you would like to prompt users for the password, leave this field empty.

Appearance

Choose settings that affect how the new connection will look.

Read-Only

If checked, the connection will not allow for any interaction from the user. The user will be able to view what is happening on the connected device, but make no interactions with it.

Swap Red-Blue Channels

Choose if the red and blue channels should be swapped for this connection.

Cursor

Choose to use the cursor of the local machine, or of the remote machine.

Color Depth

Choose the color depth of the screen over the VNC connection.

Force Lossless Compression

Use lossless compression. Check this option for better visual quality, but it may impact performance.

Clipboard

Encoding

Choose which encoding to use when copying and pasting. The options are:

• CP1252

• ISO 8859-1

• UTF-16

• UTF-8

Disable Copying from Remote Desktop

If selected, users will not be able to copy from the connection

Disable Pasting from Client

If selected, users will not be able to paste values into the connection

VNC Repeater

There exist VNC repeaters, such as UltraVNC Repeater, which act as intermediaries or proxies, providing a single logical VNC connection which is then routed to another VNC server elsewhere. Additional parameters are required to select which VNC host behind the repeater will receive the connection.

Destination Host and Port

Set the host and port to use

Screen Recording

Options for recording of the screen. See the Session Recording section for more information.

Recording Path

Enter the path to save the session recording. We recommend setting this to ${HISTORY_PATH}/${HISTORY_UUID}

Recording Name

Enter the name of the recording file

Exclude Graphics/Streams

Choose to exclude graphics or streams from the recording

Exclude Mouse

Choose to exclude the mouse from the screen recording

Include Key Events

If selected, include key events that would not otherwise be visible in the recording

Automatically Create Recording Path

If selected, Keeper Connection Manager will automatically create a path for the recording file

SFTP

Options for file transfers to the connection using SFTP. For more information see the File Transfer section.

Enable SFTP

Choose to enable SFTP file transfers

If enabled, enter the following information to connect to and authenticate connection to your SFTP server:

• Hostname Port

• Public Host Key (Base64)

• Username and Password

• Private Key

• Passphrase for the private key if applicable

File Browsing Root Directory

The root directory of the SFTP server to display within this connection

Default Upload Directory

If users upload a file from the connection, the directory that the file will go to by default

SFTP Keepalive Interval

Enter the keepalive interval as a number

Disable File Download

If SFTP is enabled, check this option to exclude users from downloading files from the server to this connection

Disable File Upload

If SFTP is enabled, check this option to exclude users from uploading files to the server from this connection

Audio

Enable Audio

Choose to enable audio for the connection

Audio Server Name

Name of the audio server to use

Wake-on-LAN (WoL)

Options to facilitate waking the connected device upon connection if supported.

Send WoL Packet

Enable Wake-on-Lan and send a signal from Keeper Connection Manager

Mac Address of the Remote Host

Identify the device to send the signal to by Mac Address

Broadcast Address for WoL Packet

Where to send the WoL signal

Host Boot Wait Time

How long to wait for the device to wake

Telnet Protocol Parameters

Details to facilitate the new Telnet connection. Set network and authentication details.

Network

Hostname and Port

Hostname and port information for the Telnet connection.

Authentication

Username and Password

Authentication credentials for the Telnet connection. To prompt users for the password, leave this field empty.

Username Regular Expression

The regular expression to use when waiting for the username prompt. This parameter is optional. If not specified, a reasonable default built into KCM will be used. The regular expression must be written in the POSIX ERE dialect (the dialect typically used by egrep).

Password Regular Expression

The regular expression to use when waiting for the password prompt. This parameter is optional. If not specified, a reasonable default built into KCM will be used. The regular expression must be written in the POSIX ERE dialect (the dialect typically used by egrep).

Login Success Regular Expression

The regular expression to use when detecting that the login attempt has succeeded. This parameter is optional. If specified, the terminal display will not be shown to the user until text matching this regular expression has been received from the telnet server. The regular expression must be written in the POSIX ERE dialect (the dialect typically used by egrep).

Login Failure Regular Expression

The regular expression to use when detecting that the login attempt has failed. This parameter is optional. If specified, the connection will be closed with an explicit login failure error if text matching this regular expression has been received from the telnet server. The regular expression must be written in the POSIX ERE dialect (the dialect typically used by egrep).

Appearance

Choose settings that affect how the new connection will look.

Theme

Select a color theme for the terminal.

There are built in themes, and a custom theme option.

Font Name

Enter the name of a font for the terminal to use

Font Size

Select the pixel size of the font

Maximum Scroll back Size

Select how far back a user can scroll through past commands. Leave blank for unlimited.

Read-Only

If checked, the connection will not allow for any interaction from the user. The user will be able to view what is happening on the connected device, but make no interactions with it.

Clipboard

Disable Copying from Remote Desktop

If selected, users will not be able to copy from the connection

Disable Pasting from Client

If selected, users will not be able to paste values into the connection

Terminal Behavior

The Terminal Behavior section contains options about the terminal for applicable connections.

Backspace Key Sends

Choose what action is sent when you click the backspace key. The options are:

• Delete

• Backspace

Terminal Type

Choose the type of terminal to use. The options are:

• ansi

• linux

• vt100

• vt220

• vterm

• vterm-256color

Typescript (Text Session Recording)

Options for text recording. See the Session Recording section for more details about session recording.

Typescript Path

Enter a file path location to save text session recordings to.

Typescript Name

Enter a name for the text session recording file

Automatically Create Typescript Path

Have Keeper Connection Manager automatically create the path location for the text session recording

Screen Recording

Options for recording of the screen. See the Session Recording section for more information.

Recording Path

Enter the path to save the session recording. We recommend setting this to ${HISTORY_PATH}/${HISTORY_UUID}

Recording Name

Enter the name of the recording file

Exclude Graphics/Streams

Choose to exclude graphics or streams from the recording

Exclude Mouse

Choose to exclude the mouse from the screen recording

Include Key Events

If selected, include key events that would not otherwise be visible in the recording

Automatically Create Recording Path

If selected, Keeper Connection Manager will automatically create a path for the recording file

Wake-on-LAN (WoL)

Options to facilitate waking the connected device upon connection if supported.

Send WoL Packet

Enable Wake-on-Lan and send a signal from Keeper Connection Manager

Mac Address of the Remote Host

Identify the device to send the signal to by Mac Address

Broadcast Address for WoL Packet

Where to send the WoL signal

Host Boot Wait Time

How long to wait for the device to wake

Kubernetes Protocol Parameters

Details to facilitate the new connection. Set network and authentication details.

Network

Hostname and Port

The hostname and port of the Kubernetes connection

Use SSL/TLS

Choose to use SSL/TLS encryption

Ignore Server Certificate

Choose to ignore the server certificate

Certificate Authority Certificate

Paste the Certificate Authority Certificate into this text box

Container

Fill in the following information about the Kubernetes container:

• Namespace

• Pod Name

• Container Name

Authentication

Client Certificate

The certificate to use if performing SSL/TLS client authentication to authenticate with the Kubernetes server, in PEM format. This parameter is optional. If omitted, SSL client authentication will not be performed.

Client Key

The key to use if performing SSL/TLS client authentication to authenticate with the Kubernetes server, in PEM format. This parameter is optional. If omitted, SSL client authentication will not be performed.

Appearance

Choose settings that affect how the new connection will look.

Theme

Select a color theme for the terminal.

There are built in themes, and a custom theme option.

Font Name

Enter the name of a font for the terminal to use

Font Size

Select the pixel size of the font

Maximum Scroll back Size

Select how far back a user can scroll through past commands. Leave blank for unlimited.

Read-Only

If checked, the connection will not allow for any interaction from the user. The user will be able to view what is happening on the connected device, but make no interactions with it.

Terminal Behavior

The Terminal Behavior section contains options about the terminal for applicable connections.

Backspace Key Sends

Choose what action is sent when you click the backspace key. The options are:

• Delete

• Backspace

Typescript (Text Session Recording)

Options for text recording. See the Session Recording section for more details about session recording.

Recording Path

Enter a file path location to save text session recordings to. We recommend setting this to ${HISTORY_PATH}/${HISTORY_UUID}

Recording Name

Enter a name for the session recording file.

Exclude Graphics/Streams

Choose to exclude graphics and streams that may appear on the terminal from the recording.

Include Key Events

Choose to include keys that are clicked in the session recording. Events like ctrl+c will be recorded.

Automatically Create Recording Path

Have Keeper Connection Manager automatically create the path location for the session recording

MySQL Protocol Parameters

Details to facilitate the MySQL connection. Set network and authentication details.

Network

Hostname and Port

Enter the hostname and port for the MySQL connection

Unix Socket

Enter the socket name if a host is not present

Authentication

Username and Password

The username and password for this MySQL connection. To prompt users for the password, leave this field empty.

Database

Default Database

Specify the default database schema when establishing a connection.

Disable CSV Export

Disable the ability for users to export data through "select .. into local infile"

Disable CSV Import

Disable the ability for users to import data through "load data local infile..."

Appearance

Choose settings that affect how the new connection will look.

Theme

Select a color theme for the terminal.

There are built in themes, and a custom theme option.

Font Name

Enter the name of a font for the terminal to use.

Font Size

Select the pixel size of the font.

Maximum Scroll back Size

Select how far back a user can scroll through past commands. Leave blank for unlimited.

Read-Only

If checked, the connection will not allow for any interaction from the user. The user will be able to view what is happening on the connected device, but make no interactions with it.

Clipboard

Disable Copying from Remote Desktop

If selected, users will not be able to copy from the connection

Disable Pasting from Client

If selected, users will not be able to paste values into the connection

Session/Environment

Settings for basic environment setup

Language/Local($LANG)

Set the language/local for the connection, this sets the $LANG environment variable

Time Zone($TZ)

Set the time zone for the connection. This sets the $TZ environment variable

Server Keepalive Interval

Set an interval for a keepalive signal

Screen Recording

Options for recording of the screen. See the Session Recording section for more information.

Recording Path

Enter the path to save the session recording. We recommend setting this to ${HISTORY_PATH}/${HISTORY_UUID}

Recording Name

Enter the name of the recording file.

Exclude Graphics/Streams

Choose to exclude graphics or streams from the recording.

Exclude Mouse

Choose to exclude the mouse from the screen recording.

Include Key Events

If selected, include key events that would not otherwise be visible in the recording.

Automatically Create Recording Path

If selected, Keeper Connection Manager will automatically create a path for the recording file.

SFTP

Options for file transfers to the connection using SFTP. For more information see the File Transfer section.

Enable SFTP

Choose to enable SFTP file transfers.

File Browsing Root Directory

The root directory of the SFTP server to display within this connection.

Disable File Download

If SFTP is enabled, check this option to exclude users from downloading files from the server to this connection.

Disable File Upload

If SFTP is enabled, check this option to exclude users from uploading files to the server from this connection.

Wake-on-LAN (WoL)

Options to facilitate waking the connected device upon connection if supported.

Send WoL Packet

Enable Wake-on-Lan and send a signal from Keeper Connection Manager.

Mac Address of the Remote Host

Identify the device to send the signal to by Mac Address.

Broadcast Address for WoL Packet

Where to send the WoL signal.

Host Boot Wait Time

How long to wait for the device to wake.

Creating a Custom Theme

Terminal based protocols (Kubernetes, SSH, MySQL and Telnet) allow for custom color themes. To use a custom theme first select "custom" from the Theme dropdown, this will open the custom theme builder.

To use the custom theme builder, click each color to select a new color to use in its place. The foreground and background colors are labeled, other colors represent the standard terminal colors.

For example: to replace all red highlighted text in the terminal with orange text, click the red color and choose orange in the color picker.

Remote Browser Isolation Protocol Parameters

Details to facilitate the RBI connection. Set network and authentication details.

Browser Settings

URL

Enter the hostname and port for the remote browser isolation connection

Allowed URL Patterns

Defines the allowed URLs to be loaded by the browser

Allowed Resource URL Patterns

Defines the page resources (such as Javascript, Images, etc) allowed to be loaded.

Browser Profile Storage Directory

Browser session data can be retained with the specified path in the container.

Example: /var/lib/guacamole/rbi-profiles/this-site/${GUAC_USERNAME}

Automatically Create Profile Directory

Creates the path on the container if it doesn't exist.

Browser Autofill Parameters

Username

Login value or reference to Keeper vault field for filling a username on a login form

Password

Password value or reference to Keeper vault field for filling a password on a login form

Autofill Targets

CSS selector for the page and field elements to autofill. More info here.

Example:

- page: "http://172.31.8.134:8080/login"
  username-field: "input[name='j_username']"
  password-field: "input[name='j_password']"

Audio Settings

Disable Audio

Channels

Bit Depth

Sample Rate

Clipboard Settings

Disable Copying from the Browser

Disable Pasting from Client

Display Settings

Read-only

Screen Recording

Options for recording of the screen. See the Session Recording section for more information.

Recording Path

Enter the path to save the session recording. We recommend setting this to ${HISTORY_PATH}/${HISTORY_UUID}

Recording Name

Enter the name of the recording file.

Exclude Graphics/Streams

Choose to exclude graphics or streams from the recording.

Exclude Mouse

Choose to exclude the mouse from the screen recording.

Include Key Events

If selected, include key events that would not otherwise be visible in the recording.

Automatically Create Recording Path

If selected, Keeper Connection Manager will automatically create a path for the recording file.

Allow Writing to Existing Recording File

Allows the connection to write the session recording to a file that already exists. Prior to this option, attempting to write to an existing file would result in a numeric suffix being appended to the new file to avoid overwriting.

Usage History

If you are editing an existing connection, the usage history of the connection is shown in this section

The usage history table displays the username, date, duration of connection and remote IP address of users connecting to this connection.

Establishing Connection through Firewalls

If you would like to establish a connection to a target server with restricted Ingres connections, check out the documentation on Creating Connections via reverse SSH tunnel.

Overview

Jump to the API Section

Importing Connections with CSV, JSON, or YAML

Keeper Connection Manager enables administrators to create connections and assign permissions to those connections by uploading a CSV, JSON, or YAML file.

Administrators can also update existing connections by checking the "Replace/Update existing connections" checkbox within the import UI:

Existing connections are identified by their name and parent connection group.

Importing Connections via API

Additionally, Keeper Connection Manager enables administrators to also create connections and assign permissions to those connections via API.

File Data in Supported File Types

The following file types are supported for connection import: CSV, JSON, and YAML.

In each of the file types, a connection is defined with the following data:

• Connection Name

• Connection Protocol

  • For a list of supported connection protocols visit this page

• Connection Parameters (optional)

• Connection Group Location (optional)

• List of Users to grant access (optional)

• List of User Groups to grant access (optional)

• Connection Attributes (optional)

Importing Connections with CSV

The connection import CSV file has one connection record per row where each column will specify a connection field.

The following sections will cover all the valid connection fields (columns) that are supported in the connection import CSV file:

Required Connection Fields - name & protocol

At minimum, the connection name and protocol must be specified.

KCM supports the following connections protocols, and the corresponding "Internal name" must be used:

Optional Connection Fields - connection parameters

The connection's parameters are dependent on your connection's protocol.

For more information on the available parameters for your connection protocol, refer to the table above and navigate to your protocol or visit this page

Optional Connection Fields - group or parentIdentifier

The connection group ID that the connection should be imported into may be directly specified with "parentIdentifier", or the path to the parent group may be specified using "group".

If a user or group identifier within the semicolon-separated list of users/groups needs to contain a semicolon, the semicolon can be escaped with a backslash. For example: "first\;last"

Optional Connection Fields - users and groups

Lists of user or user group identifiers must be semicolon-separated and defined in the users and groups connection fields

Optional Connection Fields - attributes

Additional connection characteristics for your connection

Examples

name,protocol,username,password,private-key,hostname,group,users,groups,guacd-encryption (attribute)
conn1,vnc,alice,pass1,,conn1.web.com,ROOT,guac user 1;guac user 2,Connection 1 Users,none
conn2,rdp,bob,pass2,,conn2.web.com,ROOT/Parent Group,guac user 1,,ssl
conn3,ssh,${KEEPER_SERVER_USERNAME},,${KEEPER_SERVER_KEY},conn3.web.com,ROOT/Parent Group/Child Group,guac user 2;guac user 3,,
conn4,kubernetes,,,,,,,,

Note: The first row in the above example specified the header

In most cases, there should be no conflict between fields, but if needed, an " (attribute)" or " (parameter)" suffix may be added to disambiguate.

Importing Connections with JSON

The connection import JSON file has a list of connection objects. Each connection object supports the following keys:

At minimum the connection name and protocol must be specified in each connection object.

Examples

[
  {
    "name": "conn1",
    "protocol": "vnc",
    "parameters": { "username": "alice", "password": "pass1", "hostname": "conn1.web.com" },
    "parentIdentifier": "ROOT",
    "users": [ "guac user 1", "guac user 2" ],
    "groups": [ "Connection 1 Users" ],
    "attributes": { "guacd-encryption": "none" }
  },
  {
    "name": "conn2",
    "protocol": "rdp",
    "parameters": { "username": "bob", "password": "pass2", "hostname": "conn2.web.com" },
    "group": "ROOT/Parent Group",
    "users": [ "guac user 1" ],
    "attributes": { "guacd-encryption": "none" }
  },
  {
    "name": "conn3",
    "protocol": "ssh",
    "parameters": { "username": "${KEEPER_SERVER_USERNAME}", "private-key": "${KEEPER_SERVER_KEY}", "hostname": "conn3.web.com" },
    "group": "ROOT/Parent Group/Child Group",
    "users": [ "guac user 2", "guac user 3" ]
  },
  {
    "name": "conn4",
    "protocol": "kubernetes"
  }
]

Importing Connections with YAML

A connection import YAML file is a list of connection objects with exactly the same structure as the JSON format.

---
  - name: conn1
    protocol: vnc
    parameters:
      username: alice
      password: pass1
      hostname: conn1.web.com
    group: ROOT
    users:
      - guac user 1
      - guac user 2
    groups:
      - Connection 1 Users
    attributes:
      guacd-encryption: none
  - name: conn2
    protocol: rdp
    parameters:
      username: bob
      password: pass2
      hostname: conn2.web.com
    group: ROOT/Parent Group
    users:
      - guac user 1
    attributes:
      guacd-encryption: none
  - name: conn3
    protocol: ssh
    parameters:
      username: ${KEEPER_SERVER_USERNAME}
      private-key: ${KEEPER_SERVER_KEY}
      hostname: conn3.web.com
    group: ROOT/Parent Group/Child Group
    users:
      - guac user 2
      - guac user 3
  - name: conn4
    protocol: kubernetes

Importing Connections via API

Keeper Connection Manager also enables administrators to batch import connections directly through the API by using the same endpoints that the Batch Import UI uses from the user interface.

To create or replace multiple connections, the HTTP PATCH method should be used on the connection directory resource, located at /api/session/data/{DATA_SOURCE}/connections. The data source specifies where the connections should be created, and will generally be the name of the database that was selected at install time i.e. mysql, postgres, or sqlserver. In the examples provided below, the mysql data source will be used.

See the KCM protocol documentation for more information on the possible parameters for any given connection protocol type.

Logging In - API Authentication Token

Before using any other API endpoints, you'll need an auth token (HEX value). This can be extracted by examining the requests of a logged in user on the web app, or by directly making a request to the tokens endpoint. For example:

curl 'https://kcm.example.com/api/tokens' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=kcm_admin&password=kcm_admin_pass123'

The response will include the auth token, as well as the data source that authorized the login:

{
  "authToken": "TG9YZW0GAXBZDW0GZG9SB3IGC2L0",
  "username": "kcm_admin",
  "dataSource": "mysql",
  "availableDataSources": [
    "mysql",
    "mysql-shared"
  ]
}

You can use your favorite API tool. If using Postman, when sending a GET or PATCH, set your authorization to "Inherit auth from parent", and set a header with the key Guacamole-Token with the value set to your token. Keep in mind the default expiration of tokens is 60 minutes.

Creating New Connection

Each connection to be created must be represented by a separate PATCH in the request body, using the "add" operation. For example, to create a couple of new connections:

cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/connections' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Guacamole-Token: TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
  -d '@-'
[
  {
    "op": "add",
    "path": "/",
    "value": {
      "parentIdentifier": "ROOT",
      "name": "conn1 ssh",
      "protocol": "ssh",
      "parameters": {
        "hostname": "conn1.web.com",
        "color-scheme": "white-black",
        "username": "${KEEPER_SERVER_USERNAME}", 
        "private-key": "${KEEPER_SERVER_KEY}"
      },
      "attributes": {
        "guacd-encryption": "none"
      }
    }
  },
  {
    "op": "add",
    "path": "/",
    "value": {
      "parentIdentifier": "1",
      "name": "conn2 vnc",
      "protocol": "vnc",
      "parameters": {
        "hostname": "conn2.web.com",
        "username": "alice", 
        "password": "password123"
      },
      "attributes": {}
    }
  }
]

Users, user groups, connection groups, and sharing profiles can also be modified using the same PATCH semantics as connections. The API endpoints for each of these, respectively, are:

• /api/session/data/{DATA_SOURCE}/users

• /api/session/data/{DATA_SOURCE}/userGroups

• /api/session/data/{DATA_SOURCE}/connectionGroups

• /api/session/data/{DATA_SOURCE}/sharingProfiles

For a list of supported key-value pairs, visit this section of this document

The response will include the operation and ID for every connection, in the same order the patches were submitted:

{
  "patches": [
    {
      "op": "add",
      "identifier": "1",
      "path": "/"
    },
    {
      "op": "add",
      "identifier": "2",
      "path": "/"
    }
  ]
}

Updating Existing Connections

To replace an existing connection, the "replace" operation can be used. Note that the "replace" operation will completely replace any connection fields, but any existing user or user group permissions will be retained. For example, to replace the connections created above, submit a "replace" patch for each:

cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/connections' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Guacamole-Token: TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
  -d '@-'
[
  {
    "op": "replace",
    "path": "/1",
    "value": {
      "parentIdentifier": "ROOT",
      "name": "conn1 ssh (updated)",
      "protocol": "ssh",
      "parameters": {
        "hostname": "conn1-new.web.com",
        "color-scheme": "white-black",
        "username": "${KEEPER_SERVER_USERNAME}", 
        "private-key": "${KEEPER_SERVER_KEY}"
      },
      "attributes": {
        "guacd-encryption": "ssl"
      }
    }
  },
  {
    "op": "replace",
    "path": "/2",
    "value": {
      "parentIdentifier": "1",
      "name": "conn2 vnc (updated)",
      "protocol": "vnc",
      "parameters": {
        "hostname": "conn2-new.web.com",
        "username": "bob", 
        "password": "password12345"
      },
      "attributes": {}
    }
  }
]

Fully Replacing Existing Connections

To fully replace an existing connection, resetting all permissions granted for that connection, the connection should be deleted and recreated. This can be done using a pair of patches with the "remove" and "add" operations. For example, to fully replace the connections created earlier, submit a pair of patches for each:

cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/connections' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Guacamole-Token: TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
  -d '@-'
[
  {
    "op": "remove",
    "path": "/1"
  },
  {
    "op": "add",
    "path": "/",
    "value": {
      "parentIdentifier": "ROOT",
      "name": "conn1 ssh (completely replaced)",
      "protocol": "ssh",
      "parameters": {
        "hostname": "conn1-newest.web.com",
        "username": "${KEEPER_SERVER_USERNAME}", 
        "private-key": "${KEEPER_SERVER_KEY}"
      },
      "attributes": {}
    }
  },
  {
    "op": "remove",
    "path": "/2"
  },
  {
    "op": "add",
    "path": "/",
    "value": {
      "parentIdentifier": "1",
      "name": "conn2 vnc (completely replaced)",
      "protocol": "vnc",
      "parameters": {
        "hostname": "conn2-newest.web.com",
        "username": "carol", 
        "password": "password123456789"
      },
      "attributes": {}
    }
  }
]

Granting Access to Connections

To grant access to connections for a user or user group, submit a patch to grant access for each connection, by connection ID. For example, to grant access to the user "KCM_User_1", submit the following patches:

cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/users/KCM_User_1/permissions' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Guacamole-Token: TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
  -d '@-'
[
  {
    "op": "add",
    "path": "/connectionPermissions/1",
    "value": "READ"
  },
  {
    "op": "add",
    "path": "/connectionPermissions/2",
    "value": "READ"
  }
]

To grant permissions to a user group, use: /api/session/data/{DATA_SOURCE}/userGroups/{GROUP_ID}/permissions

e.g.:

/api/session/data/mysql/userGroups/KCM%20Administrators/permissions

Logging Out

Once you're done using the API, the auth token should be explicitly disabled:

curl 'https://kcm.example.com/api/session' \
  -X 'DELETE' \
  -H 'Guacamole-Token: TG9YZW0GAXBZDW0GZG9SB3IGC2L0'

Errors

If an error is encountered while submitting a list of patches, an overall error will be returned, including any patch-specific errors. For example, when attempting to create connections that already exist with the same name at the same connection group:

{
  "message": "The provided patches failed to apply.",
  "translatableMessage": {
    "key": "APP.TEXT_UNTRANSLATED",
    "variables": {
      "MESSAGE": "The provided patches failed to apply."
    }
  },
  "statusCode": null,
  "expected": null,
  "patches": [
    {
      "op": "add",
      "identifier": null,
      "path": "/",
      "error": {
        "key": "APP.TEXT_UNTRANSLATED",
        "variables": {
          "MESSAGE": "The connection \"KCM connection 1\" already exists."
        }
      }
    },
    {
      "op": "add",
      "identifier": null,
      "path": "/",
      "error": {
        "key": "APP.TEXT_UNTRANSLATED",
        "variables": {
          "MESSAGE": "The connection \"KCM connection 2\" already exists."
        }
      }
    }
  ],
  "type": "BAD_REQUEST"
}

Overview

A connection can be launched by either clicking "Launch" or clicking on item from the list.

Launching a Connection

When you launch a connection, you will be instantly connected to the remote display from your web browser. You can interact with this display as if your mouse and keyboard are connected directly to the remote machine.

The remote display will take up the entire browser window, with no buttons or menus to disturb the view. With the intent of providing a seamless experience, options specific to remote desktop are hidden within the Keeper Connection Manager menu, which can be opened as needed.

Sidebar Menu

The Keeper Connection Manager sidebar menu provides many features that you can use during your remote session.

To show or hide the menu, use the keystrokes below:

On Windows or Linux: Use Ctrl+Alt+Shift

On Mac: Use Ctrl+Option+Shift

If you are using a mobile or touchscreen device that lacks a keyboard, you can also show the menu by swiping right from the left edge of the screen.

The Keeper Connection Manager menu provides many features including:

• Reading to and from the clipboard on the remote device

• Switching between connections and joining multiple connections

• Navigating back to the Home Screen

• Disconnecting from the current connection

• Sharing the current connection (if external sharing is configured)

• Changing keyboard input method

• Zooming in and out of the remote display

• Selecting alternative mouse emulation methods

Clipboard Management

At the top of the Keeper Connection Manager menu is a text area labeled “Clipboard” along with some basic instructions:

Text copied/cut within Keeper Connection Manager will appear here. Changes to the text below will affect the remote clipboard.

The text area functions as an interface between the remote clipboard and the local clipboard. Text from the local clipboard can be pasted into the text area, causing that text to be sent to the clipboard of the remote desktop. Similarly, if you copy or cut text within the remote desktop, you will see that text within the text area, and can manually copy it into the local clipboard if desired.

Switching and Tiling connections

If you have access to more than one connection, clicking the current connection name at the top of the Keeper Connection Manager menu will open a drop-down menu containing a list of your other available connections. Clicking on the name of another connection in this drop-down menu will immediately switch to that connection.

The previous connection will remain running as a thumbnail within a panel attached to the lower-right corner of the screen. This panel updates in real-time and remains visible as long as you have multiple active connections, even if you navigate away to another part of the Keeper Connection Manager application:

Clicking on any connection within the panel will navigate back to that connection, while clicking the “X” icon in the upper-right corner of the connection thumbnail will immediately close the connection.

Tiling Connections

Multiple connections may also be opened simultaneously within the same view by clicking the checkboxes next to the names of those connections in the connection menu. All connections opened in this way are automatically arranged in equally-sized tiles to fill the available area.

With multiple connections displayed as tiles, keyboard interaction and the Keeper Connection Manager menu will only affect the currently focused connection, as indicated by the blue title and border. Clicking or tapping within another connection will change the focus and allow keyboard interaction with that connection.

Typing with Multiple Connections

By holding down Ctrl (to select an individual connection) or Shift (to select a rectangle of connections), multiple connection may be focused at the same time. While multiple connections are focused, each key pressed will be broadcast across each focused connection:

This is particularly useful for running the same series of commands on multiple computers. Further, since Keeper Connection Manager automatically translates between the user’s local keyboard layout and the keyboard layout of the remote server, this will work as expected even if the keyboard layouts of focused connections do not match.

Disconnecting and Navigation

When you are done using the current connection, or you wish to navigate elsewhere temporarily, options to do so are within the user menu inside the Keeper Connection Manager menu:

The user menu within the Keeper Connection Manager menu provides an additional “Disconnect” option that allows you to explicitly close the current connection only. Clicking “Logout” will also implicitly disconnect all active connections, including the current connection.

Navigating back to the home screen or to the settings screen will not disconnect you: your connection will continue running in the background while you change settings or initiate another connection, and you can resume any active connection by clicking on it within the home screen.

Transferring Files

You can transfer files back and forth between your local computer and the remote desktop if it is supported by the underlying protocol and enabled on the connection. Currently, Keeper Connection Manager supports file transfer for VNC, RDP, and SSH, using either the native file transfer support of the protocol or SFTP.

Files can be transferred to the remote computer by dragging and dropping the files into your browser window, or through using the file browser located in the Keeper Connection Manager menu.

While transferring files, a dialog on the lower right will display the status.

Using the File Browser

If file transfer is enabled on the connection, you will see one or more filesystem devices listed within the Keeper Connection Manager menu. Clicking on one of the filesystems opens a file browser which lists the files and directories within that filesystem.

Double-clicking on any directory will change the current location of the file browser to that directory, updating the list of files shown as well as the “breadcrumbs” at the top of the file browser. Clicking on any of the directory names listed in the breadcrumbs will bring you back to that directory, and clicking on the drive icon on the far left will bring you all the way back to the root level.

Downloads are initiated by double-clicking on any file shown, while uploads are initiated by clicking the “Upload Files” button. Clicking “Upload Files” will open a file browsing dialog where you can choose one or more files from your local computer, ultimately uploading the selected files to the directory currently displayed within the file browser.

The state of all file uploads can be observed within the notification dialog that appears once an upload begins, and can be cleared once completed by clicking the “Clear” button. Downloads are tracked through your browser’s own download notification system.

When you are done browsing the filesystem and transferring files, click “Back” to return to the Keeper Connection Manager menu.

The RDP Virtual Drive

RDP provides its own native support for file transfer called “drive redirection” or “RDPDR”. Keeper Connection Manager provides support for this mechanism by emulating a virtual drive. Typically, this virtual drive will appear as a network drive within the RDP session. Files uploaded and downloaded will be preserved within this drive, even after disconnecting.

Files can be downloaded from this drive using the file browser in the Keeper Connection Manager menu or using the special “Download” folder within the virtual drive. All files dropped into this folder will automatically begin uploading to the client, and thus downloading through the browser.

guacctl / guacget

In addition to using the traditional drag-and-drop and the file browser, Keeper Connection Manager SSH support can be used with the guacctl utility. The guacctl utility is a simple shell script included with Guacamole (and supported by Keeper Connection Manager) which allows you to use and configure file transfer directly from the command line within the SSH session:

$ guacctl
guacctl 0.8.0, Guacamole SSH session control utility.
Usage: guacctl [OPTION] [FILE]...

    -d, --download         download each of the files listed.
    -s, --set-directory    set the destination directory for future uploaded 
                           files.
$ guacctl -d FILENAME
$ guacctl -s DIRECTORY
$

For convenience, you may also create a symbolic link or alias to guacctl called guacget. When run as guacget, the utility behaves as if the --download option were supplied and initiates a download for each file specified on the command line.

On-screen Keyboard

Certain key combinations are impossible to press within a web application like Keeper Connection Manager because they are reserved by the operating system (Ctrl+Alt+Del or Alt+Tab, for example) or by the web browser. If you press one of these reserved combinations, the effect will be observed locally, not remotely, and the remote desktop will receive only some of the keys.

Keeper Connection Manager provides its own, built-in on-screen keyboard which allows keys to be sent to the remote desktop without affecting the local system. If the device you’re using does not have certain keys which the remote desktop depends on, such as the arrow keys or Ctrl, you can use the on-screen keyboard for this, too. You can show the on-screen keyboard by selecting the “On-screen keyboard” option from the menu.

Clicking (or tapping) the buttons of the on-screen keyboard has the same effect as pressing the same buttons on a real keyboard, except that the operating system and browser will not intercept these keypresses; they will only be sent to the remote desktop.

Scaling the display

Keeper Connection Manager will default to shrinking or expanding the remote display to fit the browser window exactly, but this is not necessarily ideal. If the remote display is much larger than your local display, the screen may be impossible to see or interact with. This is especially true for mobile phones, whose screens need to be small enough to fit in the average hand.

You can scale the display on touch devices by using the familiar pinch gesture. Place two fingers on the screen and bring them closer together to zoom out or further apart to zoom in.

If your device lacks a touch screen, you can also control the zoom level through the menu. The controls for zooming in and out are located at the bottom of the menu. The current zoom level is displayed between two “-” and “+” buttons which control the zoom level in 10% increments.

Mobile or touch devices

Keeper Connection Manager is designed to work equally well across all HTML5 browsers, including those of mobile devices. It will automatically handle input from a touch screen or a traditional mouse (or both, if you happen to have such a gifted computer), and provides alternative input methods for devices which lack a physical keyboard.

Mouse emulation

In the case that your device has a touchscreen and lacks a mouse, Keeper Connection Manager will emulate a mouse for the sake of interacting with remote desktops that expect mouse input. By default, Keeper Connection Manager uses “absolute” mouse emulation. This means that the mouse pointer is positioned at the location of each tap on the screen.

In both absolute and relative modes, you can click-and-drag by tapping the screen and then quickly placing your finger back down. This gesture only causes the mouse button to press down, but does not release it again until you lift your finger back up.

Absolute mode (touchscreen)

Absolute mouse emulation is the default as it tends to be what people expect when using a touch device to interact with applications designed for mouse input.

Each tap on the screen is translated into a left-click at that position. Right-clicking is accomplished through pressing and holding your finger on the screen. If parts of the remote display are off-screen, you can drag your finger around the screen to pan the off-screen parts back into view.

Although absolute mouse emulation works generally well, a finger makes for a very inaccurate pointing device. To address this, Keeper Connection Manager also provides “relative” mouse emulation. Relative mouse emulation provides a way to deal with the need for accurate pointer control, when a true pointer device is not present.

Relative mode (touchpad)

Keeper Connection Manager's relative mouse emulation behaves similarly to the touchpad present on most modern laptops. You drag your finger across the display to move the mouse pointer, and tap the display to left-click. The pointer moves relative to the motion of your finger. Right-clicking is accomplished with a two-finger tap, and middle-clicking with a three-finger tap. The mouse scroll wheel can be operated by dragging two fingers up or down.

Because the relative mouse emulation reserves so many gestures for the different mouse buttons and actions, common touch gestures like panning and pinch-to-zoom will not work while relative mouse emulation is enabled. Instead, the screen will automatically pan to keep the mouse pointer in view, and you can zoom through the buttons in the menu.

Typing without a physical keyboard

Many mobile devices lack a physical keyboard entirely, and instead provide their own on-screen keyboards. As these are not true keyboards per se and do not produce key presses, Keeper Connection Manager's text input mode is required for typing on these platforms.

“Text input” allows input of keystrokes based on the input of text. Choosing “Text input” tells Keeper Connection Manager to infer keystrokes by tracking text entered, rather than relying on actual key presses. Keeper Connection Manager will instead determine the combination of keypresses necessary to produce the same pattern of input, including deletions.

If you wish to type via an IME (input method editor), such as those required for Chinese, Japanese, or Korean, text input mode is required for this as well. Such IMEs function through the explicit insertion of text and do not send traditional key presses. Using text input mode within Keeper Connection Manager thus allows you to use a locally-installed IME, without requiring the IME to be installed on the remote desktop.

Changing preferences

User preferences can be changed within the settings screen under the "Preferences" tab. These preferences are stored locally within the browser, so if you use multiple computers to access Keeper Connection Manager, you can have different settings for each location. The settings screen allows users to change the language of the Keeper Connection Manager interface, to change the default input method used by Keeper Connection Manager connections, and to change the default mouse emulation mode for if a touch device is used. If you have sufficient permissions, you may also change your password, or administer the system.

Display language

The Keeper Connection Manager interface is currently available in English, Dutch, French, German, Italian, and Russian. By default, Keeper Connection Manager will attempt to determine the appropriate display language by checking the language preferences of the browser in use. If this fails, or the browser is using a language not yet available within Keeper Connection Manager, English will be used as a fallback.

If you wish to override the current display language, you can do so by selecting a different language within the “Display language” field. The change will take effect immediately.

Changing your password

System administrators can restrict the ability of individual users to change their own passwords, so this section may not always be available. If your account does have permission, the preferences screen will contain a “Change Password” section.

To change your password, you must provide your current password, enter the desired new password, and click “Update Password”. You will remain logged in, and the change will affect any future login attempt.

Default input settings

Keeper Connection Manager provides multiple keyboard input methods and multiple mouse emulation modes. Many of these settings are specifically useful for touch devices, while others are aimed mainly at traditional desktop use. By default, Keeper Connection Manager will use the keyboard and mouse modes most commonly preferred by users, but you can change these defaults if they do not fit your tastes or your current device.

The choices available mirror those within the Keeper Connection Manager menu discussed earlier in this chapter, and changing these settings will affect the default values selected within the Keeper Connection Manager menu of future connections.

Sharing Connections

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

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

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

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

Keeper Connection Manager support file transfers in both directions, with unique features available for the different connection types.

RDP

Files can be transferred between the local system and the remote connection through simple drag-and-drop.

SSH

Files can be transferred to the remote system through drag-and-drop. File transfer from remote system to local browser uses the guacctl tool.

VNC

Files can be transferred via sftp to the remote system through drag-and-drop. The sftp endpoint is configured in the Connection Edit screen.

MySQL

The new MySQL connection type supports transfer of CSV data into and out of the remote database through the browser interface using special "select" and "load" commands that have been built as extensions to the MySQL syntax.

RDP / Windows

The connection parameters used for File Transfer on Windows connections is displayed below. RDP connection types support two different methods of file transfer. The "Enable Drive" method uses the RDP protocol and maps file transfers to a mapped drive on the remote system.

Depending on the installation method, the "Drive Path" can be configured a few different ways.

On Docker Installation methods, there is a default volume mount to /var/lib/guacamole/

The Drive Path must include a base path of /var/lib/guacamole/drives which has the necessary permissions to write files. If the same Drive Path is specified on multiple connections, the files will be shared among those connections. If the Drive Path contains a token after /drives/ such as ${GUAC_USERNAME}, each user will see their own shared drive.

/var/lib/guacamole/drives/${GUAC_USERNAME}

In this example, the following parameters are set:

• Enable Drive: Check this to activate the file transfer capability

• Drive Path: Set this path according to the environment. The folder must be writable by the guacd user.

• Automatically Create Drive: If the permissions allow, the subfolders will be created on demand.

The mapped drive will show up on the remote system as seen below:

Windows connections can optionally use SFTP for file transfer. This can be activated in the SFTP section of the connection. This would require an SFTP client/server to be running on windows.

Transfer Files

To transfer a file from the local system to the remote connection, simply drag-and-drop the file into the window. A progress indicator will show up on the lower right.

After the file transfer is complete, it will appear in the Drive folder.

To transfer a file from the remote system to the local computer, simply drag and drop a file on the remote system into the mapped Drive and then drag into the "Download" folder of the mapped drive. The file will instantly download to the local system.

SSH / Linux

SSH Connection types provide SFTP file transfer, which conveniently allows you to drag and drop a file into the SSH connection screen. Files are transferred to the designated folder as specified in the SSH connection settings.

Transfer to Linux

Simply drag and drop a file into the SSH connection to transfer a file to the remote system. By default, the files will transfer to the home folder unless a different root directory path is specified.

Transfer from Linux

To transfer files from the SSH remote connection to the local filesystem, you can download a tool called guacctl into the remote system and use it for performing outbound transfers.

Download guacctl and set as executable:

sudo wget https://raw.githubusercontent.com/apache/guacamole-server/master/bin/guacctl
sudo chmod +x guacctl

Initiate the file download:

sudo ./guacctl -d <filename>

MySQL

Importing

Importing Data is accomplished through the web browser interface by using the standard "LOAD DATA LOCAL INFILE" SQL command. Keeper Connection Manager intercepts the response data and redirects it through the native file download facility of the web browser.

For example:

LOAD DATA LOCAL INFILE "input.csv" 
INTO TABLE products
FIELDS TERMINATED BY ','
ENCLOSED BY '"'
IGNORE 1 LINES

This SQL query will trigger a browser file upload and then import the provided data.

Details about the syntax can be found at the MySQL website.

Exporting

Exporting CSV data from SQL query using a new SELECT... INTO LOCAL OUTFILE command.

For example:

 SELECT * FROM products INTO LOCAL OUTFILE "products.csv";

File Transfer Upload Limit

The file upload limit is controlled through the client_max_body_size setting in the NGINX configuration file.

On Docker installations of Keeper Connection Manager, the default value of this setting is "0" which allows for an unlimited upload file size.

On Advanced Linux Installation method, the default file transfer limit might be set to 1MB and most likely, you will want to raise this limit. If you followed the typical installation instructions with NGINX, you should modify the configuration file, e.g. /etc/nginx/conf.d/guacamole.conf

Ensure the following parameter (client_max_body_size) is set with the preferred maximum file size limit. For example the below is set for 200MB size limit:

client_max_body_size 200m;

After updating this value, make sure to restart NGINX

systemctl restart nginx

Custom Network Drive

If you have an environment where you would like the file location path associated with an existing network drive, follow the steps below:

• Mount your network drive to the Keeper Connection Manager host filesystem

• Volume mount the network drive path in the Docker Compose for the guacd container

• Ensure that the guacd user can write the files in the docker container

The most important thing to keep in mind when doing this is that it's the "guacd" service that needs to be able to write files in the drive path. The guacd service operates as a reduced-privilege "guacd" user within the "guacd" container, and so you will need to set file permissions accordingly. This can be done either by modifying the files on the filesystem to have appropriate ownerships using the numerical UID/GID used by the container, or by using the GUACD_UID and GUACD_GID environment variables to configure the container to use the UID/GID already used by the files on the guacd container filesystem.

Overview

Keeper Connection Manager supports on-demand, shared, and collaborative access to sessions through a simple, shareable URL. This enables teams to easily grant access to server or application sessions—even to users without a Keeper Connection Manager account.

Key use cases include:

• Training or remote assistance with monitored access to a server or web app

• Collaborative sessions with multiple users in view-only or full-control mode

• Granting temporary access without consuming a user license

To enable this feature:

1. Create a Sharing Profile on the desired connection

2. Generate and distribute a Share URL

Create a Sharing Profile

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

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

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

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

Click "Save" to create the sharing profile.

Generate and distribute a Share URL

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

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

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

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

Join & Leave Notifications for Shared Connections

When joining a shared connection via a share link or the “Active Sessions” tab of the admin/settings area, the original user of that connection will now receive a notification in the upper-right corner of the connection view showing that a user has joined:

If the user that joined was authenticated with KCM at the time, the original user will also be able to see that user’s username. A similar notification will appear whenever a user leaves the connection.

An indicator showing the number of other users currently sharing the connection will remain visible to the original user for as long as there are other users on the connection. If the user hovers the mouse over the indicator, a tooltip appears showing the usernames of all other users and how many concurrent connections they have to the current shared connection:

If the user sharing the session has no associated username (common for share links), the user appears as “Anonymous”:

Overview

Keeper Connection Manager supports automatic screen recording of each connection session. Recordings can be graphical video recordings of the connection, or (for certain connection protocols) typescript recordings which record only the text sent to the the client machine.

Read below about how to setup, configure, and view each session recording type.

Graphical Session Recording

Sessions of all supported protocols can be recorded graphically. These recordings take the form of Guacamole protocol dumps and are recorded automatically to a specified directory.

In-Browser Session Recording and Playback

The simplest way to record user connection sessions and view them in the browser.

To configure connections for in-browser recording playback, enter the following special values in the "Screen Recording" section of the connection settings.

Recording Path / Typescript Path

${HISTORY_PATH}/${HISTORY_UUID}

These values tell the system to store recordings in a location and format that the in-browser viewer can play back.

Custom Session Recording Location and Local Playback

If desired, graphical session recordings can be named with custom values, or saved to any desired location. This will require recording playback using the Glyptodon Session Recording Player.

Configuring Graphical Session Recording

Recording Path

The directory in which screen recording files should be created.

This parameter is required for graphical session recording to function.

Recording Name

The filename to use for any created recordings. This parameter is optional. If omitted, the value “recording” will be used instead.

This parameter only has an effect if graphical recording is enabled. If the "Recording Path" is not specified, graphical session recording will be disabled, and this parameter will be ignored.

It is recommended to utilize Keeper Connection Manager's dynamic credential pass-through to add the date, time, and other unique information to the recording name.

For example:

RDP Recording ${GUAC_USERNAME} - ${GUAC_DATE} : ${GUAC_TIME}

Will create recording files with the user's username, the session date and time in the name.

Session Recording Playback

Keeper Connection Manager session recordings can be viewed from within the user interface in the History tab of the settings screen. To view a recording, click the play icon on the far right. Any session of a connection that was setup with the settings above will have the icon. When the icon is clicked, the recorded session will load in the browser, and you can start playback by clicking anywhere on the screen.

Note: For a recording to be visible within the UI, it must satisfy one of the following criteria:

• The recording is directly within the directory ${HISTORY_PATH} and has the filename ${HISTORY_UUID}.

• The recording is directly within the directory ${HISTORY_PATH}/${HISTORY_UUID} (and may have any filename).

Key Events in Session Recordings

If a session recording contains key events, those events can now be viewed within KCM’s session recording player. Administrators can view an approximation of what would have been typed based on those events and perform a text-based search to find particularly interesting parts of a recording.

Histograms on Session Recording

KCM session recordings display a histogram that shows the relative levels of activity within different parts of the recordings. The histogram shows the following levels of activities:

• Visible events such as when the screen changes

• keyboard events - user interactions with the keyboard

Exclude Graphics/Streams

If checked, graphical output and other data normally streamed from server to client will be excluded from the recording, producing a recording which contains only user input events.

This parameter is optional. If omitted, graphical output will be included in the recording.

Exclude Mouse

If checked, user mouse events will be excluded from the recording, producing a recording which lacks a visible mouse cursor.

This parameter is optional. If omitted, mouse events will be included in the recording.

Include Key Events

If checked, user key events will be included in the recording.

This parameter is optional. If omitted, key events will be not included in the recording.

Automatically Create Recording Path

If checked the directory specified by "Recording Path" will automatically be created if it does not yet exist. Only the final directory in the path will be created - if other directories earlier in the path do not exist, automatic creation will fail, and an error will be logged.

This parameter is optional. By default, the directory specified by the recording path parameter will not automatically be created, and attempts to create recordings within a non-existent directory will be logged as errors.

Replaying Custom Location Graphical Session Recordings

Keeper Connection Manager graphical session recordings that were saved to a custom location can be viewed using the Keeper Connection Manager Session Recording Player at https://player.glyptodon.com

To view session recordings, click "Browse..." and select the recording in your file system. The recording will play in the browser.

Text session recording (typescripts)

The full, raw text content of terminal 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 by the entered Typescript Path: NAME, which contains the raw text data, and NAME.timing, which contains timing information, where NAME is the value provided for Typescript Name.

This format is compatible with the format used by the standard UNIX script command, and can be replayed using compatible tools.

Configuring Typescript Session Recording

Typescript session recording can be configured for each connection in the Keeper Connection Manager connection settings

Typescript Path

The directory in which typescript files should be created.

This parameter is required. Specifying this parameter enables typescript recording. If this parameter is omitted, no typescript will be recorded.

Typescript Name

The base filename to use when determining the names for the data and timing files of the typescript.

This parameter is optional. If omitted, the value “typescript” will be used instead.

Each typescript consists of two files which are created within the directory specified by the Typescript Name: NAME, which contains the raw text data, and NAME.timing, which contains timing information, where NAME is the value provided for the Typescript Name parameter.

It is recommended to utilize Keeper Connection Manager's dynamic credential pass-through to add the date, time, and other unique information to the recording name.

For example:

SSH Typescript ${GUAC_USERNAME} - ${GUAC_DATE} : ${GUAC_TIME}

Will create recording files with the user's username, the session date and time in the name.

Automatically Create Typescript Path

If checked, the directory specified by "Typescript Path" will automatically be created if it does not yet exist. Only the final directory in the path will be created - if other directories earlier in the path do not exist, automatic creation will fail, and an error will be logged.

This parameter is optional. By default, the directory specified by "Typescript Path" will not automatically be created, and attempts to record typescripts in a non-existent directory will be logged as errors.

Replaying Text Session Replays

MacOs

Recordings can be replayed using script. For example, to replay a typescript called “NAME”, you would run:

$ script -p NAME

Linux

Recordings can be replayed using scriptreplay. For example, to replay a typescript called “NAME”, you would run:

$ scriptreplay NAME.timing NAME

Overview

Keeper Connection Manager integrates with Amazon AWS to perform automatic discovery and connection to EC2 instances. This makes it fast and easy to connect to any EC2 instance in your cloud environment without having to manually configure anything. Like other connections, the EC2 instance connections are privileged, which means that the end-user does not have access to the underlying credentials.

Once activated, the EC2 instances will appear on the home screen of Keeper Connection Manager as seen below.

Features of the Integration

• Instant discovery of EC2 instances in your AWS environment

• Restrict permissions to a defined User Group

• PEM files can be managed either on the filesystem or Keeper Vault

AWS Setup

In order to integrate Keeper Connection Manager with Amazon AWS, you'll need to create a user and assign a role policy that has permission to read instance information. A sample policy with minimal permissions is below:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeImages",
                "ec2:GetPasswordData",
                "ec2:DescribeInstances",
                "ec2:DescribeInstanceStatus"
            ],
            "Resource": "*"
        }
    ]
}

Assign the permission to a user and then create access keys.

Installation

Create Group

Before configuring the environment, ensure that you have a Group called "AWS EC2 Administrators" that are assigned to the users who will have access to discovered instances. The group name can also be customized through the AWS_DISCOVERY_ADMIN_GROUP environmental variable.

Auto Docker Method

To update your Keeper Connection Manager environment to support this feature, you'll need to edit the Docker Compose file located at /etc/kcm-setup/docker-compose.yml

(1) Stop the Containers

Before making changes on the local instance, it is a good idea to stop the containers.

sudo ./kcm-setup.run stop

(2) Edit the Docker Compose

Now, edit the docker compose file /etc/kcm-setup/docker-compose.yml and add the necessary required environmental variables and volume property. For example, see below.

 guacamole:
        image: keeper/guacamole:2
        environment:
            ....
            ....
            AWS_DISCOVERY_ACCESS_KEY_ID: XXXXXXXXXXXXXXX
            AWS_DISCOVERY_SECRET_KEY: XXXXXXXXXXXXXXXXXXXXXXX
            AWS_DISCOVERY_REGIONS: us-east-1
            AWS_DISCOVERY_ADMIN_GROUP: MyDevOpsGroup
            AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT: "true"
        volumes:
            ....
            - "/var/lib/guac_keys/:/etc/guacamole/cloud-connector-secrets/aws/:ro"

Store Credentials in the Keeper Vault (optional)

If you are using the Secrets Manager Vault connection with KCM, pem files or private keys can be pulled in dynamically from the Keeper Vault. If using this method, a volume mount for pem files does not need to be created. See the EC2 Cloud Connector documentation for more details.

Environmental Variables

AWS_DISCOVERY_ACCESS_KEY_ID

The access key ID for the AWS account that should be used to authenticate with AWS (Required).

AWS_DISCOVERY_SECRET_KEY

The secret key associated with the access key (Required).

AWS_DISCOVERY_REGIONS

Comma-separated list of regions to query for EC2 instances, such as us-west-1,us-east-1 (Required).

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“ (Optional).

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". This can also be assigned to a Group that has been provisioned from Azure AD or other directory integrations.

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 can be set to "true" or "false" to explicitly enable or disable connection recording.

AWS_DISCOVERY_KSM_CONFIG

This Keeper Secrets Manager configuration provides integration with the Keeper vault to store PEM files. See the EC2 Cloud Connector documentation for more details.

(3) Copy .pem files into the guac_keys folder

In the Docker Compose example, you can see a volume mapping in the local file location /var/lib/guac_keys/. This is the folder in the KCM host where you must place all of the SSH key files required to establish a connection to the target instances. Windows instances must also copy the .pem file which is used to decrypt the Administrator password. KCM will select the proper file for establishing a connection based on the EC2 instance metadata.

See the Key File Permissions section below to review the file permissions and ensure that the key files are readable by the container.

(4) Upgrade the Container

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

sudo ./kcm-setup.run upgrade

This should automatically start the containers after the update.

Docker Compose Method

To update your Keeper Connection Manager environment to support this feature, you'll need to edit the "guacamole" section of your custom Docker Compose file.

(1) Stop the Containers

Before making changes on the local instance, it is a good idea to stop the containers, as you normally would do with docker-compose.

sudo docker-compose stop

(2) Edit the Docker Compose

Now, edit your docker compose file and add the necessary required environmental variables and volume property to the guacamole section. For example, see below.

 guacamole:
        image: keeper/guacamole:2
        environment:
            ....
            ....
            AWS_DISCOVERY_ACCESS_KEY_ID: XXXXXXXXXXXXXXX
            AWS_DISCOVERY_SECRET_KEY: XXXXXXXXXXXXXXXXXXXXXXX
            AWS_DISCOVERY_REGIONS: us-east-1
            AWS_DISCOVERY_ADMIN_GROUP: MyDevOpsGroup
            AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT: "true"
        volumes:
            ....
            - "/var/lib/guac_keys/:/etc/guacamole/cloud-connector-secrets/aws/:ro"

Environmental Variables

AWS_DISCOVERY_ACCESS_KEY_ID

The access key ID for the AWS account that should be used to authenticate with AWS (Required).

AWS_DISCOVERY_SECRET_KEY

The secret key associated with the access key (Required).

AWS_DISCOVERY_REGIONS

Comma-separated list of regions to query for EC2 instances, such as us-west-1,us-east-1 (Required).

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“ (Optional).

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". This can also be assigned to a Group that has been provisioned from Azure AD or other directory integrations.

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 can be set to "true" or "false" to explicitly enable or disable connection recording.

(3) Copy .pem files into the guac_keys folder

In the Docker Compose example, you can see a volume mapping in the local file location /var/lib/guac_keys/. This is the folder in the KCM host where you must place all of the SSH key files required to establish a connection to the target instances. Windows instances must also copy the .pem file which is used to decrypt the Administrator password. KCM will select the proper file for establishing a connection based on the EC2 instance metadata.

See the Key File Permissions section below to review the file permissions and ensure that the key files are readable by the container.

(4) Upgrade the Container

To update all of the underlying software when using the Custom Docker Install method, upgrade your containers (assuming docker-compose.yml is in the current directory):

sudo docker-compose up -d

This should automatically start the containers after the update.

Advanced Linux Method

If you have installed Keeper Connection Manager using the Advanced Linux Install method, follow the steps below to activate the AWS EC2 discovery feature.

(1) Install the KCM Cloud Connector package

If you are using the Advanced Linux Install method, you can use yum install to install the KCM Cloud Connector package:

sudo yum install kcm-cloud-connector-aws

(2) Edit the Guacamole Properties File

Edit /etc/guacamole/guacamole.properties to include the mandatory and optional properties for the AWS Cloud Connector feature.

Available Properties

aws-discovery-access-key-id

The access key ID for the AWS account that should be used to authenticate with AWS (Required).

aws-discovery-secret-key

The secret key associated with the access key (Required).

aws-discovery-regions

Comma-separated list of regions to query for EC2 instances, such as us-west-1,us-east-1 (Required).

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“ (Optional).

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". This can also be assigned to a Group that has been provisioned from Azure AD or other directory integrations (Optional).

aws-discovery-record-connections-by-default

If this property is set to "true", screen recording will be enabled by default on all connections (Optional).

Connection session recording can also be set at an individual machine level using the "kcm:record" EC2 instance tag, which can be set to "true" or "false" to explicitly enable or disable connection recording.

(3) Copy .pem files into the guac_keys folder

Add any required PEM files for private keys used to access Linux instances or decrypt Windows passwords to /etc/guacamole/cloud-connector-secrets/aws/

(4) Restart the Guacamole service

The new package will not take effect until the web application is restarted.

sudo systemctl restart guacamole

Instance Configuration with Tags

Connections can be configured using AWS EC2 tags assigned to each instance, in order to override and customize defaults and metadata.

Available Tags

kcm:username

The username that should be used when connecting to that instance.

This tag defines the login username for the instance, such as "centos" or "ec2-user". KCM attempts to select the correct username based on the AMI of the instance, but this can be used to correct a wrong assumption.

kcm:organize

The full path of the connection groups that should be used to organize the instance among other connections.

This tag Allows EC2 instances to be further organized beyond the connection group containing all instances. By default, all discovered instances will be placed within one top-level group of connections called "Amazon EC2", but will not be further organized. For example, if you set kcm:organize to something like "Databases", that instance will be located within a "Databases" connection group beneath "Amazon EC2". If you set kcm:organize to "Databases/MySQL", that instance will be within a "MySQL" connection group beneath "Databases", which itself would be beneath the main "Amazon EC2" group.

These connection groups do not need to already exist, and they actually exist only in memory (dynamically maintained by the EC2 support).

kcm:record

Flag to indicate if the instance connection sessions should be recorded.

This tag will override the default screen recording configuration of the KCM environment property aws-discovery-record-connections-by-default . If this tag exists with the value "true", the connection will be recorded, if "false", the connection will not be recorded. If the tag does not exist, or is set to any other value, the configured default recording behavior will be used.

Key File Permissions

Filename

• The key files must be named exactly as referenced in the EC2 console, e.g. MyServer

• The key files must be named with a .pem file extension, for example MyServer.pem

Permissions

The service in the "guacamole" docker container is run by the "guacamole" user. File permissions must be configured properly in the volume mount to ensure that the "guacamole" user has read access to the shared key files.

Example: On the host under /var/lib/guac_keys/ the files may be owned by ec2-user or whatever you have set up.

[root@xxx guac_keys]# ls -l
-rw------- 1 ec2-user ec2-user 1674 Jul 29 18:30 KCMDemoMac.pem
-rw------- 1 ec2-user ec2-user 1678 Jul 29 18:31 kcmdemo.pem
-rw------- 1 ec2-user ec2-user 1674 Jul 29 18:30 KCMDemoUbuntu.pem
-rw------- 1 ec2-user ec2-user 1674 Jul 29 18:30 KCMDemoWindows.pem
-rw------- 1 ec2-user ec2-user 1678 Jul 29 18:30 KCMKaliLinux.pem

In the container the files may show owned by "1000" or some other user ID.

[root@1dd8996db434 aws]# ls -l
-rw------- 1 1000 1000 1674 Jul 29 18:30 KCMDemoMac.pem
-rw------- 1 1000 1000 1674 Jul 29 18:30 KCMDemoUbuntu.pem
-rw------- 1 1000 1000 1674 Jul 29 18:30 KCMDemoWindows.pem
-rw------- 1 1000 1000 1678 Jul 29 18:30 KCMKaliLinux.pem
-rw------- 1 1000 1000 1678 Jul 29 18:31 kcmdemo.pem

There are two ways of solving the file permissions between the host and the guacamole container.

(1) You may use the environmental variables GUACAMOLE_UID and GUACAMOLE_GID in the guacamole docker definition to map the permission.

            GUACAMOLE_UID: 1000
            GUACAMOLE_GID: 1000

This change has the following result:

• Updates the ownerships of existing files from the old UID of the guacamole user to the specified value.

• Updates the UID of the guacamole user in the container to match that value.

(2) You can set wider group or world read permissions on the files from the host, but this is a decision based on your environment and security settings.

Key Files with Passphrases

If the .pem key is encrypted with a passphrase, you will be prompted for this when establishing the connection to the target.

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

Common uses for these tokens include:

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

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

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

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

Username/password pass-through

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

Client hostname/address information

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

Current date and time

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

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

Overview

Keeper Connection Manager can be configured to integrate with any custom software or 3rd party application using encrypted JSON files that simultaneously authenticate a user and grant them access to remote connections.

Installation

The Dynamic Connections feature requires installation of the Encrypted JSON Authentication module for Keeper Connection Manager. To activate this feature, update the JSON_* parameters in the Docker Compose file in the keeper/guacamole image.

JSON_SECRET_KEY

JSON_TRUSTED_NETWORKS

Activating these parameters loads an authentication extension for Keeper Connection Manager which authenticates users using JSON that have been signed using HMAC/SHA-256 and encrypted with AES-128 CBC. As this JSON contains all information describing the user being authenticated (including any connections they have access to), this extension can provide a simple means of integrating Keeper Connection Manager with external applications.

The JSON_SECRET_KEY must be 128 bits, specified as a 32-digit hexadecimal value, such as:

4c0b569e4c96df157eee1b65dd0e4d41

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

echo -n "SomeRandomizedPassword" | md5sum
4c0b569e4c96df157eee1b65dd0e4d41

or using openssl directly ...

echo -n "SomeRandomizedPassword" | openssl md5

If encrypted JSON will only ever be received from a known set of machines or private subnets, you may wish to further restrict acceptance of received JSON to only those trusted machines using the JSON_TRUSTED_NETWORKS property. This field is a comma-separated list of trusted IP addresses and/or CIDR subnets. For example:

127.0.0.0/8, 10.0.0.0/8

JSON format

The general format of the JSON (prior to being encrypted, signed, and sent to Keeper Connection Manager), is as follows:

{
    "username" : "someuser",
    "expires" : TIMESTAMP,
    "connections" : {
        "Connection Name" : {
            "protocol" : "PROTOCOL",
            "parameters" : {
                "name1" : "value1",
                "name2" : "value2",
                ...
            }
        },
        ...
    }
}

For example, if you want a JSON file that logs in as craig and instantly launches an SSH connection to a Linux server, the file might look like this:

{
    "username" : "craig",
    "expires" : "1740860895000",
    "connections" : {
        "Kali Linux Server" : {
            "protocol" : "ssh",
            "parameters" : {
                "hostname" : "192.168.1.2",
                "port" : "22",
                "username" : "kali",
                "private-key":"<contents of PEM encoded SSH key>"
            }
        }
    }
}

...where "expires" is a standard UNIX epoch timestamp with millisecond resolution (the number of milliseconds since midnight of January 1, 1970 UTC) and PROTOCOL is the internal name of any of Guacamole's supported protocols, such as vnc, rdp, or ssh.

As an example, to generate a timestamp that expires in 24 hours from now:

echo $(($(date -v+24H +%s) * 1000))

The top-level JSON object which must be submitted to Keeper Connection Manager has the following properties:

Each connection defined within each submitted JSON object has the following properties:

(*) A quick way to locate the name of a property is by inspecting the Keeper Connection Manager connection UI by right-clicking the field and inspecting the field DOM element "name":

Generating encrypted JSON

To authenticate a user with the above JSON format, the JSON must be both signed and encrypted using the same 128-bit secret key specified with the JSON_SECRET_KEY value in the Docker compose file.

1. Generate JSON in the format described above

2. Sign the JSON using the secret key (the same 128-bit key stored with the JSON_SECRET_KEY property) with HMAC/SHA-256. Prepend the binary result of the signing process to the plaintext JSON that was signed.

3. Encrypt the result of (2) above using AES in CBC mode, with the initial vector (IV) set to all zero bytes.

4. Encode the encrypted result using base64.

5. POST the encrypted result to the /api/tokens REST endpoint as the value of an HTTP parameter named data (or include it in the URL of any Keeper Connection Manager page as a query parameter named data).

For example, if Keeper is running on kcm.example.com and BASE64_RESULT is the result of the above process, the equivalent run of the "curl" utility would be:

$ curl --data-urlencode "data=BASE64_RESULT" https://kcm.example.com/api/tokens

If the data is invalid in any way, if the signature does not match, if decryption or signature verification fails, or if the submitted data has expired, the REST service will return an invalid credentials error and fail without user-visible explanation. Details describing the error that occurred will be in the KCM logs.

Reference implementation

The Apache Guacamole source code includes a shell script, doc/encrypt-json.sh, which uses the OpenSSL command-line utility to encrypt and sign JSON in the manner that guacamole-auth-json requires. It is thoroughly commented and should work well as a reference implementation, for testing, and as a point of comparison for development. The script is run as:

$ ./encrypt-json.sh <secret key> file-to-sign-and-encrypt.json

For example, if you have a file called auth.json containing the following:

{
    "username" : "test",
    "expires" : "1446323765000",
    "connections" : {
        "My Connection" : {
            "protocol" : "rdp",
            "parameters" : {
                "hostname" : "10.10.209.63",
                "port" : "3389",
                "ignore-cert": "true",
                "recording-path": "/recordings",
                "recording-name": "My-Connection-${GUAC_USERNAME}-${GUAC_DATE}-${GUAC_TIME}"
            }
        },
        "My OTHER Connection" : {
            "protocol" : "rdp",
            "parameters" : {
                "hostname" : "10.10.209.64",
                "port" : "3389",
                "ignore-cert": "true",
                "recording-path": "/recordings",
                "recording-name": "My-OTHER-Connection-${GUAC_USERNAME}-${GUAC_DATE}-${GUAC_TIME}"
            }
        }
    }
}

and you run:

$ ./encrypt-json.sh 4C0B569E4C96DF157EEE1B65DD0E4D41 auth.json

You will receive the following output:

A2Pf5Kpmm97I2DT1PifIrfU6q3yzoGcIbNXEd60WNangT8DAVjAl6luaqwhBJnCK
uqcf9ZZlRo3uDxTHvUM3eq1YvdghL0GbosOn8Mn38j2ydOMk+Cd15a8ggb4/ddt/
yIBK4DxrN7MNbouZ091KYtXC6m20E6sGzLy676BlMSg1cmsENRIihOynsSLSCvo0
diif6H7T+ZuIqF7B5SW+adGfMaHlfknlIvSpLGHhrIP4aMYE/ZU2vYNg8ez27sCS
wDBWu5lERtfCYFyU4ysjRU5Hyov+yKa+O7jcRYpw3N+fHbCg7/dxVNW07qNOKssv
pzUciGvDPUCPpa02WmPJNEBowwQireO1952/MNAI77cW2UepbljD/bwOiZl2THJz
LrENo7K5acimBa+EjWEesgn7lx/WTCF3zxR6TH1CWrQM8Et1aUK1Nf8K11xEQbTy
klyaNtCmTfyahRZ/fUPxDNrdJVpPOSELkf7RJO5tOdK/FFIFIbze3ZUyXgRq+pHY
owpgOmudDBTBlxhXiONdutRI/RZbFM/7GBMdmI8AR/401OCV3nsI4jLhukjMXH3V
f3pQg+xKMhi/QExHhDk8VTNYk7GurK4vgehn7HQ0oSGh8pGcmxB6W43cz+hyn6VQ
On6i90cSnIhRO8SysZt332LwJCDm7I+lBLaI8NVHU6bnAY1Axx5oH3YTKc4qzHls
HEAFYLkD6aHMvHkF3b798CMravjxiJV3m7hsXDbaFN6AFhn8GIkMRRrjuevfZ+q9
enWN14s24vt5OVg69DljzALobUNKUXFx69SR8EpSBvUcKq8s/OgbDpFvKbwsDY57
HGT4T0CuRIA0TGUI075uerKBNApVhuBA1BmWJIrI4JXw5MuX6pdBe+MYccO3vfo+
/frazj8rHdkDa/IbueMbvq+1ozV2+UuxrbaTrV2i4jSRgd74U0QzOh9e8Q0i7vOi
l3hnIfOfg+v1oULmZmJSeiAYWxeGvPptp+n7rNFqHGM=

The resulting base64 data above is the encrypted payload which will authenticate the user for the defined connections. If a single connection in the JSON is defined, the user will launch straight into the connection. If multiple connections are defined, or if the user is assigned connections, they will be provided with a list of choices.

There are two ways of launching into the connection manager using this encrypted base64 data.

HTTP Post

If you are generating the request through an HTTP POST:

curl --data-urlencode "data=BASE64_RESULT" https://kcm.example.com/api/tokens

In Postman, you can test this through a POST request having x-www-form-urlencoded data:

HTTP Get

If you are trying to generate a URL for loading the connection in a browser through an HTTP GET request:

Strip the newlines and convert the base64 payload to a URL encoded string. The key transformations you need are:

• + becomes %2B

• / becomes %2F

• = becomes %3D

This can be converted through Python:

python3 -c "import urllib.parse; print(urllib.parse.quote('XXXX', safe=''))"

Then provide the URL encoded string as a data parameter in the URL for your server. For example: https://my.kcmserver.com/?data=URL_ENCODED_BASE64_STRING

When opening this in a browser, the connection is immediately authenticated and opened:

Keeper Connection Manager supports customization of the front-end user interface CSS and injection of custom Javascript. In this guide, we will demonstrate how to modify the web application to display customized branding and execute custom Javascript code.

Overview

Keeper Connection Manager provides the ability to develop "Extensions" which can add custom enhancements to the overall platform. This page covers a basic example which can be easily modified for branding and UI changes.

Extensions to Keeper Connection Manager can:

1. Provide alternative authentication methods and sources of connection/user data.

2. Provide event listeners that will be notified as Guacamole performs tasks such as authentication and tunnel connection.

3. Theme or brand the user interface through additional CSS files and static resources.

4. Extend KCM's JavaScript code by providing JavaScript that will be loaded automatically.

5. Add additional display languages, or alter the translation strings of existing languages.

Extension format

KCM extensions are standard Java .jar files (this is essentially a .zip file) which contain all classes and resources required by the extension, as well as the KCM extension manifest. There is no set structure to an extension except that the manifest must be in the root of the archive. Java classes and packages, if any, will be read from the .jar relative to the root, as well.

Example Branding Extension

Modifying your existing KCM installation with custom branding is easy, please follow the below steps as an example.

(1) On the instance running Keeper Connection Manager or your workstation, retrieve the example repository or download as a zip file. Example:

git clone https://github.com/Keeper-Security/kcm-branding.git
cd kcm-branding

(2) Zip up the contents of the branding folder into a file called kcm-branding.jar. The name of the file is arbitrary, as long as it is a unique name. KCM will load any extension that is placed into the target folder.

zip -r kcm-branding.jar guac-manifest.json css/ html/ js/ resources/ translations/

(3) Copy the file into the /etc/kcm-setup folder or any path on the server.

sudo cp kcm-branding.jar /etc/kcm-setup/

(4) In your docker-compose.yml file (e.g. /etc/kcm-setup/docker-compose.yml) there are 2 changes needed:

• In the "guacamole" section add a reference to the Jar file which volume mounts the file directly from the host into the guacamole instance. The name of the file does not matter, as KCM will pull all jar files and process them.

• Add the environment variable USE_DEFAULT_BRANDING with a value of "N".

Here's an example section:

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ...
            USE_DEFAULT_BRANDING: "N"
        volumes:
            ...
            - "/etc/kcm-setup/kcm-branding.jar:/etc/guacamole/extensions/kcm-branding.jar:ro"

(5) Restart the container

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

That's it. After the service starts up, the branding on your KCM page will be all new, and there will be a popup alert when you load the page.

For iterating on more changes, simply edit the resources, zip up the file, copy the zip file to the target folder and restart your KCM container.

Technical Details

CSS

The CSS files referenced in guac-manifest.json are appended to the application CSS when loaded, therefore they will override the CSS properties.

Javascript

The Javascript files referenced in guac-manifest.json are appended to the application Javascript when loaded.

HTML modification

The existing HTML structure of KCM's interface can be modified through special "patch" HTML files declared by the html property in guac-manifest.json. These files are HTML fragments and are identical to any other HTML file except that they contain KCM-specific meta tags that instruct KCM to modify its own HTML in a particular way. Each meta tag takes the following form:

<meta name="NAME" content="SELECTOR">

where SELECTOR is a CSS selector that matches the elements within the KCM interface that serve as a basis for the modification, and NAME is any one of the following defined modifications:

before

Inserts the specified HTML immediately before any element matching the CSS selector.

after

Inserts the specified HTML immediately after any element matching the CSS selector.

replace

Replaces any element matching the CSS selector with the specified HTML.

before-children

Inserts the specified HTML immediately before the first child (if any) of any element matching the CSS selector. If a matching element has no children, the HTML simply becomes the entire contents of the matching element.

after-children

Inserts the specified HTML immediately after the last child (if any) of any element matching the CSS selector. If a matching element has no children, the HTML simply becomes the entire contents of the matching element.

replace-children

Replaces the entire contents of any element matching the CSS selector with the specified HTML.

For example, to add a welcome message and link to some corporate privacy policy (a fairly common need), you would add an HTML file like the following:

<meta name="after" content=".login-ui .login-dialog">

<div class="welcome">
    <h2>Welcome to our Keeper Connection Manager Demo</h2>
    <p>
        Please be sure to read our <a href="#">privacy
        policy</a> before continuing.
    </p>
</div>

After the extension is installed and KCM is restarted, the "welcome" div and its contents will automatically be inserted directly below the login dialog (the only element that would match .login-ui .login-dialog) as if they were part of KCM's HTML in the first place.

Troubleshooting

If the page loads blank after applying the extension, check the logs. For example:

sudo ./kcm-setup.run logs -f guacamole

If you see a null pointer exception, it's probably because one of the resources referenced in guac-manifest.json cannot be found in the .jar archive. Ensure that all files and folders are zipped up properly.

Adding your logo to KCM

1. Download the zip file above and extract everything to a folder.

2. Replace /resources/images/logo.png with your logo.png file.

3. Open /translations/en.json and replace "Custom Title" with your text for the title of the webpage.

4. (Optional) Replace the favicon icons in /resources/images/, bothsmall.png and large.pngwith yours. (you can use the same one for both if needed)

5. From inside the folder, select all of the files and folders and create a new zip file.

1. Make sure that you are viewing file extensions, and change your zip file name and extension to kcm-branding.jar

2. Transfer the kcm-branding.jar file to your KCM server into/etc/kcm-setup/

3. In your docker-compose.yml guacamole section, within environment, add USE_DEFAULT_BRANDING: "N" and in volumes add the following line:

- "/etc/kcm-setup/kcm-branding.jar:/etc/guacamole/extensions/kcm-branding.jar:ro"

1. Run these commands:

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

Complete! Now you will see your logo on your Keeper Connections Manager.

To refresh the favicons press Ctrl/Cmd + F5 for a hard reload.