All pages
Powered by GitBook
2 of 2

Creating Connections

Managing and creating connections to your infrastructure

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.

Privileged Connections

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.

User-Specified Credentials

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.

New Connection
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

Other options in the connection form are affected by the protocol selection

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:

Batch Import and API

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.

Set this value to 0 to allow unlimited concurrent sessions.

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.

Set this value to 0 to allow unlimited concurrent sessions.

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

If you would like users to be prompted for manual authentication, you may need to select "NLA" security mode and leave the authentication parameters empty.

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.

If you would like the user to be prompted for their password, leave the "password" field empty.

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.

Custom them 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

Usage History Table

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.

Batch Import and API

Create multiple connections via API or by uploading a CSV, JSON, or YAML file

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:

Protocol
Internal name

VNC

vnc

RDP

rdp

SSH

ssh

Telnet

telnet

Kubernetes

kubernetes

MySQL

mysql

PostgreSQL

postgresql

Microsoft SQL Server

sql-server

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:

Key
Description

name

Name of the connection

protocol

Connection's protocol. For a list of supported connection protocols visit this page

parameters

Connection's parameters to establish protocol connection. For required parameters visit this page. (Optional)

parentIdentifier or group

The connection group ID that the connection should be imported into may be directly specified with a parentIdentifier key, or the path to the parent group may be specified using a group key (Optional)

users

An array of user(s) to grant access to (Optional)

groups

An array of user group(s) to grant access to (Optional)

attributes

Connection's attributes

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.

Note that directory PATCH methods guarantee atomicity - the entire request must succeed; if any included patch fails, all changes in the batch will be rolled back.

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.

Example using Postman

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