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.

Using Keeper Secrets Manager, Keeper Connection Manager can securely access RDP, SSH, MySQL, VNC and other credentials from the Keeper Vault. With this integration, connection credentials are protected in the encrypted Keeper vault and never stored in plain text. In the connection properties, you can simply reference the hostname or specified Vault record identifier and Keeper will pull the necessary credentials at runtime. Access credentials are never exposed to the user.

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

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

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

Copy

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

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

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

Copy

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.

Copy

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.

Copy

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.

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"

Copy

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

Copy

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

Copy

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

Then, restart the guacamole process as you typically would.

Copy

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

Copy

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"
        

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

Copy

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

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 hostname to extract the necessary fields. Static tokens can 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 values 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.

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.

Standard Tokens

Domain and Username Splitting

Some username fields are of the format: Domain\Username or Username@Domain but the connection details need only the domain or username. Use these tokens to automatically split these fields and use the corresponding field:

Alternatively you can set KSM_STRIP_WINDOWS_DOMAINS to true in guacamole.properties to automatically strip all login fields into separate 'USERNAME' and 'DOMAIN' fields accessible by tokens

Gateway Tokens

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

Windows 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 Windows "Domain" and "Username" field can be parsed if the Login value in the Keeper Vault is supplied in the format of DOMAIN\Username or Domain@Username.

To activate automatic parsing, the environmental variable KSM_STRIP_WINDOWS_DOMAINS must be added to the Docker Config file.

For example:

            ....
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            KSM_CONFIG: "XXX"
            ....
            ....
            KSM_STRIP_WINDOWS_DOMAINS: "true"
            ....

In the record, the Login field can then contain

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

Advanced Linux Install Method

To configure custom tokens, add this YAML file to your guacamole configuration files: /etc/guacamole/ksm-token-mapping.yml

In this file, create the tokens that you would like to use and identify what secrets each token corresponds to using Keeper Notation.

Example mapping file:

MY_CUSTOM_SECRET: keeper://cps2OgKHpFQ8Ye30L9587w/field/password
MY_OTHER_CUSTOM_SECRET: keeper://sS6jDVv0HoM0yGMU4OaOAw/file/linuxssoconnect.pem
RDP_INITIAL_PROGRAM: keeper://cps2OgKHpFQ8Ye30L9587w/custom_field/program

Then, restart the guacamole process as you typically would.

$ sudo systemctl restart guacamole

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:

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.

See the Dynamic Tokens documentation for more information on the available tokens and how to use them.

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.

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:

            ....
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            KSM_CONFIG: "XXX"
            ....
            ....
            KSM_ALLOW_USER_CONFIG: "true"
            ....

Advanced Linux Install Method

You must set the setting in the guacamole.properties file, or set the associate environment variable for the keeper/guacamole docker image.

guacamole.properties

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.

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.

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:

MYSQL_HOSTNAME: "db"
MYSQL_DATABASE: "guacamole_db"
MYSQL_USERNAME: "guacamole_user"
MYSQL_PASSWORD: "your_mysql_database_password"

AFTER:

MYSQL_HOSTNAME: "db"
MYSQL_DATABASE: "guacamole_db"
MYSQL_USERNAME: "guacamole_user"
MYSQL_PASSWORD_KSM_SECRET: keeper://2ZlOFQAYi4DubJWBtSbRxw/field/password

The token syntax is using Keeper Notation. The name of the parameter must follow the format of *_KSM_SECRET. In this example, the MySQL database password is pulled directly from a Keeper record in the Shared Folder.

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:

$ sudo ./kcm-setup.run upgrade

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:

MYSQL_HOSTNAME: "db"
MYSQL_DATABASE: "guacamole_db"
MYSQL_USERNAME: "guacamole_user"
MYSQL_PASSWORD_KSM_SECRET: keeper://2ZlOFQAYi4DubJWBtSbRxw/field/password

The token syntax is using Keeper Notation. In this example, the MySQL database password is pulled directly from a Keeper record in the Shared Folder as seen below:

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:

sudo su
docker-compose up -d

Advanced Linux Install Method

To utilize Keeper Vault storage of Guacamole properties, create a file guacamole.properties.ksm in the same location as your guacamole.properties file (/etc/guacamole/ by default).

In the new file, add any properties that you would like to store in the Keeper vault, and set the value to a Keeper Notation query of the record field to use for that property. Note that the guacamole.properties file must still contain the ksm-config property to identify the Keeper Secrets Manager configuration.

Example Setup

guacamole.properties:

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

guacamole.properties.ksm:

mysql-hostname: keeper://tqd1F9zHRKokN44Xso8PkQ/field/host[hostname]
mysql-port: keeper://tqd1F9zHRKokN44Xso8PkQ/field/host[port]
mysql-password: keeper://tqd1F9zHRKokN44Xso8PkQ/field/password

The token syntax is using Keeper Notation. In this example, the MySQL database password is pulled directly from a Keeper record with the specified UID tqd1F9zHRKokN44Xso8PkQ.

Then, restart the guacamole process as you typically would.

$ sudo systemctl restart guacamole

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.