To connect KCM to your vault, we utilize Keeper Secrets Manager (KSM). KSM must first be enabled in the role policy enforcement settings of the role you are a member of (from the Admin Console). Then, you will see the tab "Secrets Manager" in your vault on the left side.

Network Configuration

This integration requires that your KCM server is able to communicate to the Keeper Secrets Manager (KSM) endpoint over TLS port 443 where your Keeper tenant is hosted.

US: keepersecurity.com EU: keepersecurity.eu AU: keepersecurity.com.au CA: keepersecurity.ca JP: keepersecurity.jp US_GOV: govcloud.keepersecurity.us

Vault Setup

Credentials for establishing connections are stored in Keeper shared folders. A Keeper Secrets Manager application is created and associated with the shared folder. A base64 device configuration is then created and added to your Keeper Connection Manager server.

Configuration Steps

(1) In the vault, create a shared folder and store credential records into this shared folder. For right now, the shared folder needs to be created and it can be populated later with credentials.

(2) From the Secrets Manager tab, create a Secrets Manager application and choose the shared folder which contains the credentials. A one-time access token is provided. You can use this one-time token, or go to Devices > Edit > Add Device > Method: Configuration File > Base64 and copy the base64 configuration string.

(3) If there have been no manual changes to your Docker Compose since original installation of KCM, you can run the reconfigure command to enter the Base64 configuration:

sudo ./kcm-setup.run reconfigure

If you have changed the Docker Compose since the original installation it is recommended to manually edit the file /etc/kcm-setup/docker-compose.yml and adding the Base64 configuration into the "environment" section. For example:

guacamole:
    image: keeper/guacamole:2
    restart: unless-stopped
    volumes:
        - common-storage:/var/lib/guacamole
    environment:
        ACCEPT_EULA: "Y"
        GUACD_HOSTNAME: "guacd"
        MYSQL_HOSTNAME: "db"
        MYSQL_DATABASE: "guacamole_db"
        MYSQL_USERNAME: "guacamole_user"
        MYSQL_PASSWORD: "xxxxxxx"
        KSM_CONFIG: "paste Base64 here"

(4) Save the file and run the upgrade command to bring in the changes.

sudo ./kcm-setup.run apply

(5) From the Keeper Connection Manager interface, create a new connection. Now, we can use dynamic tokens to pull in the credentials by matching the hostname/IP in KCM with the hostname/IP in your record in the shared folder that is tied to this KSM application.

There are many options including ${KEEPER_SERVER_USERNAME} and ${KEEPER_SERVER_PASSWORD}.

Setup complete! Other matching capabilities and available variables are documented on the dynamic tokens page.

Command Line Setup

If you wish to use the Keeper Commander CLI for establishing the integration between Keeper Connection Manager and Keeper Secrets Manager, follow the steps below.

(1) Set up your Keeper Vault

In your Keeper Vault, create a Shared Folder that is populated with credentials that will be used for making connections. In the example below you can see a shared folder called "Connection Manager Secrets" that includes a Windows 2022 Server password, SSH Key, MySQL Database, etc.

(2) Install Keeper Commander CLI

Our CLI tool will allow you to quickly set up the configuration.

There's a few ways to install Commander. We provide binary installers, pip3 packages or Python source code. The top level installation page is here:

(3) Login to Commander

After installation of Commander, login to the CLI:

$ keeper shell
...
...

Not Logged In> login you@company.com
...
...

My Vault> 

In the example screenshot below, I'm logging in with a Keeper admin account using a FIDO2 key and Master Password. Depending on your security settings, you may have to pass device verification, MFA and password entry.

(4) Get the Shared Folder UID

The command lsf will list the Shared Folders and display the UID.

In this example, the Shared Folder UID we're using is zyMiCn8596yvMln4YwdEdA

(5) Create an Application

A Secrets Manager application is created in the vault, which is assigned to the Shared Folder. An application is made up of one or more devices. Here we will create a Secrets Manager application and then retrieve the Application UID.

secrets-manager app create "Connection Manager Example"
secrets-manager app get "Connection Manager Example"

Secrets Manager Application
App Name: Connection Manager Example
App UID: YGHY7nWrvkzEzF0I2AuFfg

The resulting Secrets Manager App UID in this example is YGHY7nWrvkzEzF0I2AuFfg

(6) Assign the Shared Folder to the Application

In this step, we will assign our Shared Folder to the application.

secrets-manager share add --app "Connection Manager Example" --secret zyMiCn8596yvMln4YwdEdA

If successful, you will get the response "Successfully added secrets to app".

(7) Generate a Client Configuration

In this step, we will create a client device configuration. This client device configuration will be directly provided to the Connection Manager.

secrets-manager client add --app "Connection Manager Example" --config-init b64 --name "KCM Device" --unlock-ip

The "Initialized Config" section in green must now be added to the Keeper Connection Manager configuration file. The location of the configuration will depend on which method of installation, as described in the next section.

Auto Docker Install Method

If you installed Keeper Connection Manager using the Auto Docker Install method, you will need to modify the auto-generated Docker Compose file to include the integration token.

(1) On the local instance, it is a good idea to stop the containers. You can do this using kcm-setup or using docker-compose directly.

sudo ./kcm-setup.run stop

or...

sudo su
cd /etc/kcm-setup/
docker-compose -p kcm stop

Using the simple docker method creates a docker-compose.yml file that is preconfigured for you. One change to this file will be needed to add KSM support.

(2) Edit the /etc/kcm-setup/docker-compose.yml file. You can use your favorite editor on the linux system such as nano or vim.

Look for the "guacamole" docker image and the "environment" section which defines environment variables. A sample file is listed below. Paste the token from step 6 above.

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        volumes:
            - common-storage:/var/lib/guacamole
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            MYSQL_HOSTNAME: "db"
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            MYSQL_PASSWORD: "xxxxxxx"
            KSM_CONFIG: "paste token here"

(3) Save the File and Apply Changes

Once the file changes have been saved, simply run:

$ sudo ./kcm-setup.run apply

Test Login and Initialize Token

Now that the KSM integration is completed, please ensure that you're able to login normally to Keeper Connection Manager and open connections. If errors occur, please check the log files.

Custom Docker Install Method

If you installed Keeper Connection Manager using the Custom Docker Install method, you will need to modify your Docker Compose file to include the integration token. The instructions for activating the integration are below:

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

cd /path/to/docker-compose.yml
docker-compose stop

(2) Edit your docker-compose.yml file. Look for the "guacamole" docker image and the "environment" section which defines environmental variables. A sample file is listed below. Paste the token from step 6 above.

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        volumes:
            - common-storage:/var/lib/guacamole
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            MYSQL_HOSTNAME: "db"
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            MYSQL_PASSWORD: "xxxxxxx"
            KSM_CONFIG: "paste token here"

(3) Save the File and Update Containers

Once the file changes have been saved, simply update the containers:

sudo su
docker-compose up -d

Test Login and Initialize Token

Now that the KSM integration is completed, please ensure that you're able to login normally to Keeper Connection Manager and open connections. If errors occur, please check the log files.

Dynamic Tokens

When using the vault integration, specific tokens are replaced by the corresponding value from a Keeper record.

There are dynamic and static tokens. Dynamic tokens will search the Keeper vault for a matching record to extract the necessary secret fields. Static tokens can also be created that explicitly reference a particular Keeper record and field.

Hostname Matching

Keeper Records can be assigned to connections by the "Hostname" field in the connection and the "Hostname or IP Address" field in the vault record.

If these two values match, Connection Manager will fetch and replace tokens in other connection fields with values from the record, such as Username, Password, Domain, etc...

User Matching

Keeper Records can be assigned to connections by the "Username" field in the connection and the "Login" field in the vault record.

If these two values match, Connection Manager will fetch and replace tokens in other connection fields with secrets from the record.

As one example, this is useful for mapping a single SSH key to multiple servers. This way, you don't need to store one record per host in the vault. A single Keeper vault record can be used to authenticate any number of connections. Below is a Connection that is set up to match on Username.

The corresponding vault record is seen below. No hostname is specified in the vault record, so the match will occur based on the login field.

Domain Matching

Keeper Records can be retrieved for connections by matching on the "Domain" field in the connection and a custom field called "Domain" in the vault record.

If these two values match, Connection Manager will fetch and replace tokens in other connection fields with values from the record, such as Username, Password, etc...

As another example, if you are using SSH to a Linux machine with Active Directory credentials in the format of username@domain, you can store this value in the Login field.

Available Tokens

The built-in tokens each correspond to a record field. The table below lists each token and its corresponding record field. These tokens are applicable to all connection types.

Gateway Tokens

The tokens below are applicable only to connection types that have gateway support (RDP).

Active Directory Username/Domain Parsing

KCM will identify the Domain, Username and Password fields from the Keeper Vault record, as long as there is a field with the corresponding name. For example:

Automatic Parsing of Domain from Login Field

The Active Directory "Domain" and "Username" field can be parsed if the Login value in the Keeper Vault is supplied in the format of DOMAIN\Username or Username@Domain.

To activate automatic parsing, the environmental variable KSM_STRIP_WINDOWS_DOMAINS must be added to the Docker Config file. This allows matching to work if the username is combined with the domain.

Another property called KSM_MATCH_DOMAINS_FOR_USERS will force matching to occur only if both the username and domain match exactly.

For example:

In the record, the Login field can then contain

Overview

Keeper Connection Manager can pull secrets from different vaults or different shared folders of the Keeper Vault, via the Keeper Secrets Manager integration. There are two main ways which KCM can connect to multiple Keeper Vaults for retreiving secrets:

1. Connection Groups can be assigned to different secrets manager configurations. Any connection defined within a Connection Group will retrieve secrets from the group assignment.

2. Users can be assigned Secrets Manager configurations, and connections can retrieve secrets from configurations defined by each individual user profiles. This allows different users to connect to the same set of connections with their own set of secrets.

Connection Groups

Each Keeper Connection Manager "Connection Group" can use a Keeper Secrets Manager configuration for the connections in the group. When this is activated, each connection group will look for records in the corresponding Secrets Manager configuration to retrieve secrets and replace tokens in the connection settings.

In order to use a Keeper Secrets Manager with a Connection Group, enter a Keeper Secrets Manager One-Time Access Token, or Configuration into the "KSM Service Configuration" field of the connection group form.

All connections created within this Connection Group will then use the Secrets Manager configuration defined to retrieve secrets when establishing connections, instead of using the root level Secrets Manager configuration.

The Secrets Manager configuration can come from the same vault, or any other vault.

User-Specified Configuration

Each Keeper Connection Manager User profile can be assigned to a Keeper Secrets Manager configuration for any connection. When the connection is updated to allow user-specific vaults, Keeper Connection Manager will pull the secret from the user's corresponding configuration. This feature allows multiple users to share the same set of connections, using secrets that originate from the user's own vault.

In order to use user-specific secrets manager connections, the Keeper Connection Manager installation needs to have the feature enabled. It is disabled by default.

Docker Install Method

An additional environmental variable must be added to the keeper/guacamole Docker image in your docker-compose.yml file.

KSM_ALLOW_USER_CONFIG

For example:

In the Edit User screen, fill in the KSM Service Configuration that has been set up for that user. This is also available to each user to set up the KSM Service Configuration for themselves.

When creating or editing a connection, there is a field which appears called "Allow user-provided KSM configuration".

When this option is selected, Keeper Connection Manager will look for corresponding secrets in the user's vault corresponding to the Keeper Secrets Manager configuration.

Order of Precedence

Keeper Connection Manager will always use the base (or Connection Group) secrets if any are applicable. It will only use user-provided secrets if there isn't an admin-provided secret for the same, to ensure that users cannot override the intent of the admin.

Static Tokens

Connection Manager supports configuring custom static tokens which can correspond to a specific field of a specific Keeper Vault record contained within the Shared Folder. These static tokens must be specified in either the Docker compose or directly in the guacamole configuration file, depending on the installation method of the platform. In most cases, the Dynamic Tokens are a preferable method of integration.

Auto Docker Install Method

If you installed Keeper Connection Manager using the Auto Docker Install method, you will need to modify the auto-generated Docker Compose file to define your static tokens.

As root, edit the /etc/kcm-setup/docker-compose.yml file.

Edit the "environment" section underneath the "guacamole" docker image. Insert an environmental variable called KSM_TOKEN_MAPPING that includes a multi-line definition of your custom tokens. In the example below, there are 3 custom tokens for specific fields within the Keeper vault shared folder. The token syntax is using Keeper Notation.

    guacamole:
        image: xxx
        restart: unless-stopped
        volumes:
            - common-storage:/var/lib/guacamole
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            MYSQL_HOSTNAME: "db"
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            MYSQL_PASSWORD: "xxxxxxx"
            KSM_CONFIG: "xxxxxxx"
            KSM_TOKEN_MAPPING: |
                MY_CUSTOM_SECRET: keeper://cps2OgKHpFQ8Ye30L9587w/field/password
                MY_OTHER_CUSTOM_SECRET: keeper://sS6jDVv0HoM0yGMU4OaOAw/file/linuxssoconnect.pem
                RDP_INITIAL_PROGRAM: keeper://cps2OgKHpFQ8Ye30L9587w/custom_field/program

Once the file changes have been saved, update the containers:

$ sudo ./kcm.run upgrade

Docker Compose Install Method

Edit your docker-compose.yml file. Look for the "guacamole" docker image and the "environment" section which defines environmental variables.

Insert an environmental variable called KSM_TOKEN_MAPPING that includes a multi-line definition of your custom tokens. In the example below, there are 3 custom tokens for specific fields within the Keeper vault shared folder. The token syntax is using Keeper Notation.

    guacamole:
        image: xxx
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            MYSQL_HOSTNAME: "db"
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            MYSQL_PASSWORD: "xxxxxxx"
            KSM_CONFIG: "xxx"
            KSM_TOKEN_MAPPING: |
                MY_CUSTOM_SECRET: keeper://cps2OgKHpFQ8Ye30L9587w/field/password
                MY_OTHER_CUSTOM_SECRET: keeper://sS6jDVv0HoM0yGMU4OaOAw/file/linuxssoconnect.pem
                RDP_INITIAL_PROGRAM: keeper://cps2OgKHpFQ8Ye30L9587w/custom_field/program

Once the file changes have been saved, update the containers:

sudo su
docker-compose up -d

Custom Token Usage

When using custom tokens, the records can be setup in any way. Keeper notation in the mapping file can identify any specified field.

The tokens can then be used with the ${XXX} format within the Connection Manager parameters screen. A couple of examples are seen below:

About

You can store SSH Keys and Windows passwords in your Keeper vault for connecting to EC2 instances alongside the KCM Cloud Connector.

See the AWS EC2 Discovery documentation for more details on connecting KCM with AWS EC2 instances.

Setup

Enable

The feature must first be enabled using either the Docker environment variable or the guacamole properties.

Docker Environment Variable

For Auto Docker Install and Docker Compose Install methods, in the keeper/guacamole-db-mysql image, a new environmental variable must be defined:

AWS_DISCOVERY_KSM_CONFIG

This must contain a Keeper Secrets Manager configuration. It can be the same config used with the KSM_CONFIG variable.

For example:

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        ......
        AWS_DISCOVERY_KSM_CONFIG: "eyJob3N0bmFtZSI6ICJrZWVwZX.....=="

For Advanced Linux Install method, update the guacamole.properties file.

Remove volume mount for PEM key files

If you are using Keeper to store the PEM key files, you can remove the volume mount in the Docker Compose file that references the location /var/lib/guac_keys/ as this will not be used.

Configure a Record for use with Cloud Connect

The EC2 cloud connector recognizes Keeper records with specific fields automatically.

To create a record for use with the EC2 Cloud connector, you can either create a record that contains a pem file attachment containing your key, or a record that contains the key as text.

PEM File Record

Create a new record which will contain the pem file. The File Attachment record type is a good match, but any type other than General will work.

The record can have any title, In this example we're using "AWS key: my-machine"

With the record created, attach the pem file.

Lastly, ensure that the new record is in a shared folder that is accessible to KCM via the Secrets Manager vault connection.

Private Key Record

Create a new record which will contain your machine's private key. The record is required to have a "private key" field. The SSH standard record type can be used for this.

The record can have any title.

The new record will need a custom text field named "Instance ID". Add a "Text" type custom field from the Custom Field menu, click "Edit Label" and enter "Instance ID".

With the record ready, enter your machine's private key into the Private Key field, and your AWS instance ID in the new custom field.

Lastly, make sure that the record is in a shared folder that is accessible to KCM via Secrets Manager integration.

Overview

Keeper Secrets Manager integrates with Keeper Connection Manager to provide dynamic retrieval of credentials that are stored in the Keeper Vault. This integration allows the Admin to provide privileged sessions with credentials that are stored and protected in the encrypted Keeper vault.

Integration Features

• Securely store connection secrets like SSH keys and Admin passwords in your Keeper Vault

• Dynamically pull credentials from Keeper on-demand when establishing connections

• Eliminate hard-coded credentials and secrets

• Securely store guacamole properties in the Keeper Vault such as MySQL passwords

• Manage integrations with multiple vaults or folders with connection groups

Config Parameter Protection

The Keeper Vault can be utilized to protect and store configuration secrets that would normally be hard-coded into the guacamole.properties or Docker Compose file.

Auto Docker Install Method

If you installed Keeper Connection Manager using the Auto Docker Install method, configuration secrets are protected in the auto-generated Docker Compose file.

As root, edit the /etc/kcm-setup/docker-compose.yml file.

For each configuration secret that you want to protect, you can replace the entry with a direct lookup in the Keeper vault. A good example of this is replacing the hard-coded MySQL database password with a vault record.

BEFORE:

AFTER:

The value of each *_KSM_SECRET variable should be the Keeper notation of the secret that should be used to pull the necessary configuration value. For example, if SOME_VARIABLE_KSM_SECRET were set to valid Keeper notation, then the value of the Guacamole property normally associated with SOME_VARIABLE will be pulled from that secret in KSM.

Once the file changes have been saved, update the containers:

Docker Compose Install Method

Edit your docker-compose.yml file.

For each configuration secret that you want to protect, you can replace the entry with a direct lookup in the Keeper vault. A good example of this is replacing the hard-coded MySQL database password with a vault record:

The value of each *_KSM_SECRET variable should be the Keeper notation of the secret that should be used to pull the necessary configuration value. For example, if SOME_VARIABLE_KSM_SECRET were set to valid Keeper notation, then the value of the Guacamole property normally associated with SOME_VARIABLE will be pulled from that secret in KSM.

Once the file changes have been saved, update the containers:

Other configuration options

In docker installations, the parameter ADDITIONAL_GUACAMOLE_PROPERTIES_KSM can be used to move parameters from the guacamole.properties file into guacamole.properties.ksm.