# Connecting KCM to your Vault

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FeIlfYLj48ESGEa1tfQLw%2FConnecting-KCM.jpg?alt=media&#x26;token=c38f0eed-1710-4726-a5a2-faf3f72705c7" alt=""><figcaption></figcaption></figure>

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.](https://docs.keeper.io/en/keeper-connection-manager/installation/auto-docker-install#secrets-manager-integration)

{% hint style="warning" %}
Note: This integration works with the latest "typed" vault records such as Logins, SSH Keys, Databases, Servers, etc. The old Keeper "general" record types are not compatible with Keeper Secrets Manager or Keeper Connection Manager integrations. For more information on record types, [see this page](https://app.gitbook.com/s/-LO5CAzpxoaEquZJBpYz/record-types).
{% endhint %}

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

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2Fp97HC0tjUCUDgtdC62v2%2FScreenshot%202023-09-13%20at%208.39.00%20PM.jpg?alt=media&#x26;token=445e46be-5354-4915-a838-c1c8f60a47fc" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FF9BAxvZedtzEAeaOnXiS%2FScreenshot%202023-09-13%20at%208.38.17%20PM.jpg?alt=media&#x26;token=db5c305e-6ed6-4953-9171-8c0d01214a9c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2Fg2j1lfbrteAQpcnbnU21%2FScreenshot%202023-09-13%20at%208.43.28%20PM.jpg?alt=media&#x26;token=dd73a892-b470-4d39-9b35-68b73ec12b0f" alt=""><figcaption></figcaption></figure>

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

```bash
sudo ./kcm-setup.run reconfigure
```

{% hint style="warning" %}
Any changes made to your Docker Compose file will be lost when performing the "reconfigure" action
{% endhint %}

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.

```bash
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.&#x20;

There are many options including `${KEEPER_SERVER_USERNAME}` and  `${KEEPER_SERVER_PASSWORD}`.&#x20;

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FBma152eIWJYg6IYQO1lT%2FpHFoRVbz6U.png?alt=media&#x26;token=f5c66078-7c62-4cdc-9ba5-87bc664626d3" alt=""><figcaption></figcaption></figure>

Setup complete! Other matching capabilities and available variables are documented on the [dynamic tokens page](https://docs.keeper.io/en/keeper-connection-manager/vault-integration/dynamic-tokens).

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

![Shared Folder in the Keeper Vault](https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2Foi2fDBSEWV73o24Bg9Nm%2FScreen%20Shot%202022-04-23%20at%2012.12.31%20PM.png?alt=media\&token=9ab99e10-1b81-47b7-9dbf-e2eebc7db378)

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

{% embed url="<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 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.

![Login to Keeper Commander](https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2Fypc1WUvpHma9ytOqdEqB%2FScreen%20Shot%202022-04-23%20at%2012.21.43%20PM.png?alt=media\&token=019f7082-a233-40a6-8409-7ad1b8e507bd)

**(4) Get the Shared Folder UID**

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

![List Shared Folders](https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FVT3SMIYiu93GCJL8MTbO%2FScreen%20Shot%202022-04-23%20at%2012.25.33%20PM.png?alt=media\&token=41ff2d2c-a20a-4c10-83d4-f331443721b9)

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.

{% code overflow="wrap" %}

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

{% endcode %}

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.

{% code overflow="wrap" %}

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

{% endcode %}

![Generate Initialized Configuration](https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FHA3MhR7bxaZKaxsdgkmd%2FScreen%20Shot%202022-04-23%20at%2012.38.23%20PM.png?alt=media\&token=ed00bc55-2426-4f57-8b8f-5e3b610d2909)

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.

{% hint style="info" %}
Copy the token for the next section where it will be initialized
{% endhint %}

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

{% hint style="info" %}
If you are unable to login or launch connections, see the [troubleshooting](https://docs.keeper.io/en/keeper-connection-manager/troubleshooting) section to learn how to check the log files.
{% endhint %}

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

{% hint style="info" %}
If you are unable to login or launch connections, see the [troubleshooting](https://docs.keeper.io/en/keeper-connection-manager/troubleshooting) section to learn how to check the log files.
{% endhint %}
