Connecting KCM to your Vault

Using the Keeper Vault to create privileged sessions

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.

Summary

With your server credentials in a shared folder in your vault, we will map the shared folder to a KSM application, and then put a Base64 token that we will generate into your docker-compose.yml file on your KCM instance to allow access.

Command Line

Configuration Steps

Below are the steps to establishing the integration between Keeper Connection Manager and Keeper Secrets Manager.

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

Shared Folder in the Keeper Vault

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

https://docs.keeper.io/secrets-manager/commander-cli/commander-installation-setup

(3) Login to Commander

After installation of Commander, login to the CLI:

$ keeper shell
...
...

Not Logged In> login [e-mail]
...
...

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.

Login to Keeper Commander

(3) Get the Shared Folder UID

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

List Shared Folders

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

(4) 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

(5) 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".

(6) 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

Generate Initialized Configuration

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.

Copy the token for the next section where it will be initialized

Advanced Linux Install Method

If you installed Keeper Connection Manager using the Advanced Linux Install method, you can install the Keeper Secrets Manager package as you would other Keeper Connection Manager plugins. The vault integration package is named "kcm-guacamole-vault-ksm"

$ sudo yum install kcm-guacamole-vault-ksm

To ensure that the linux machine is capable of generating enough entropy for random number generation, we recommend installing the haveged package.

These packages can be installed using the commands below:

sudo yum install epel-release
sudo yum install haveged
sudo systemctl start haveged
sudo systemctl enable haveged

To complete setup, simply add the base64 format configuration (from Step 6 above) to your /etc/guacamole/guacamole.properties file with the ksm-config value.

guacamole.properties

ksm-config: eyJob3N0bm[...]1IzRTN2UVNTNkhsb0NZQW9nUmlPVlY5cjhvUT0ifQ==

Then, restart the guacamole process as you typically would.

$ sudo systemctl restart guacamole

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.

If you are unable to login or launch connections, see the troubleshooting section to learn how to check the log files.

GUI

Configuration Steps

1) In your vault, create a shared folder and put your credential(s) records into this shared folder. We need the shared folder now, but we can add credentials to it later.

2) From the secrets manager tab, create a secrets manager application and choose the shared folder. Then go to Devices > Edit > Add Device > Method: Configuration File > Base64 and copy and/or download the base64 token.

3) On your KCM server itself, we will edit the file /etc/kcm-setup/docker-compose.yml and add the Base64 token into the guacamole section, under the environment section.

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"
        
        

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

sudo ./kcm-setup.run upgrade

5) From the KCM web interface, create a new connection (or clone an existing one). 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}.

You can continue to explore the capabilities on the dynamic tokens page https://docs.keeper.io/keeper-connection-manager/vault-integration/dynamic-tokens