Hashicorp Vault

Use Keeper Secrets Manager with HashiCorp Vault as a Data Source

About

The Keeper Secrets Manager HashiCorp Vault integration allows you to use secrets from the Keeper Vault as a data store for HashiCorp Vault.

Features

• Use Secrets from the Keeper Vault with HashiCorp Vault scripts and commands

• Read secret information using HashiCorp Vault

• Update secret information from HashiCorp Vault

For a complete list of Keeper Secrets Manager features see the Overview

Prerequisites

This page documents the Secrets Manager HashiCorp Vault integration. In order to utilize this integration, you will need:

• Keeper Secrets Manager access (See the Quick Start Guide for more details)

  • Secrets Manager add-on enabled for your Keeper subscription

  • Membership in a Role with the Secrets Manager enforcement policy enabled

• A Keeper Secrets Manager Application with secrets shared to it

  • See the Quick Start Guide for instructions on creating an Application

• An initialized Keeper Secrets Manager Configuration

  • The HashiCorp Vault integration accepts our Base64 format configurations

• HashiCorp Vault command line, and a Vault server running

  • See the HashiCorp Vault documentation for how to install

Installation

1. Download the Secrets Manager Plugin

Download the latest integration release from the KSM GitHub page:

Releases · Keeper-Security/secrets-managerGitHub

Secrets Manager Releases

Look for a vault-plugin release in the list of releases that matched your platform.

Unzip the plugin and place it into your HashiCorp Vault plugins directory. In this example the folder is located at C:\vault\plugins (Windows) or /etc/vault/vault_plugins (MacOS/ Linux)

2. Register the Plugin with HashiCorp Vault

Development Mode

For testing the plugin or to allow quick development, development mode can be used to quickly get the HashiCorp Vault CLI up and running.

Windows

Start the HashiCorp Vault in dev mode

vault server -dev -dev-plugin-dir=C:\vault\plugins

Enable the Secrets Manager Plugin

vault secrets enable -path=ksm vault-plugin-secrets-ksm.exe

Linux / MacOS

Start the HashiCorp Vault in dev mode

vault server -dev -dev-plugin-dir=/etc/vault/vault_plugins

Enable the Secrets Manager Plugin

vault secrets enable -path=ksm vault-plugin-secrets-ksm

HashiCorp Vault CLI development mode utilizes volatile in-memory storage. Any actions taken on secrets in the Keeper Vault are immediate, but the plugin will need to be re-enabled each time the HashiCorp Vault is started in dev mode.

Production Mode

When ready to move to production, the plugin will need to be registered using a SHA256 hash of the plugin.

Windows

Register and Enable the Secrets Manager Plugin

vault plugin register -command=vault-plugin-secrets-ksm.exe -sha256=<SHA256> secret vault-plugin-secrets-ksm
vault secrets enable -path=ksm vault-plugin-secrets-ksm

Generating SHA256 Hash

You will need a hash of the plugin file to enable it with production HashiCorp Vault servers. This hash can be generated for the Secrets Manager plugin.

Windows 7 and later comes with a built-in tool called CertUtil that can be used to generate the SHA256 hash. This example will show how to generate a SHA hash using CertUtil, but any tool that can generate a file hash in SHA256 will work.

CertUtil -hashfile C:\vault\plugins\vault-plugin-secrets-ksm.exe SHA256

Linux / MacOS

Register and Enable the Secrets Manager Plugin

vault plugin register -sha256=<SHA256> secret vault-plugin-secrets-ksm
vault secrets enable -path=ksm vault-plugin-secrets-ksm

Generating SHA256 Hash

You will need a hash of the plugin file to enable it with production HashiCorp Vault servers. This hash can be generated for the Secrets Manager plugin.

Using the built-in shasum function this can be generated like this:

shasum -a 256 /etc/vault/vault_plugins/vault-plugin-secrets-ksm

Depending on your OS, you may use the sha256sum command instead

sha256sum /etc/vault/vault_plugins/vault-plugin-secrets-ksm

3. Configure a Secrets Manager Connection

Now that the HashiCorp Vault plugin is installed, a secure connection to the Keeper Vault needs to be established so that secret credentials can be accessed. To create this connection, a Secrets Manager configuration needs to be created and assigned to the plugin.

Create a Secrets Manager Configuration

A Secrets Manager configuration can be created using Keeper Commander or the Secrets Manager CLI. See the Configuration Documentation for more information on creating a configuration.

Once a configuration has been generated, set it to a variable to be used by the Vault Plugin.

vault write ksm/config ksm_config=<BASE64_CONFIG...>

Using the Plugin

List Secrets

vault list ksm/records

The records will be shown in the following format:

Keys
----
UID RECORDTYPE: RECORDTITLE

Example:

C:\Vault> vault list ksm/records
Keys
----
Hf6of4uo_2aD7IMjn4VPuA  login:  My Record
Lv3B9ObAjxdpdBl0IJ3oow  folder: 4 record(s)
Oq3fFu14hZY00d7sp3EYNA  MyCustomType:  My New Record (Custom record type)
YDx58Q94dE1k9B367ZVz1w  databaseCredentials:    MySQL Credentials
qe3EWYn840uR0bOMyZ2b0Q  login:  Dropbox Login

Get a Single Secret

vault read ksm/record uid=<UID>

Example:

C:\Vault> vault read ksm/record uid=Hf6r5Zuo_2aD7IMjn4VPuA
Key       Value
---       -----
fields    [map[type:login value:[[e-mail]]] map[type:password value:[Pd08fi@1]]]
notes     Example Login Record
title     Sample KSM Record
type      login

Read TOTP Code

vault read ksm/record/totp uid=<UID>

Example:

C:\Vault> vault read ksm/record/totp uid=32t82-oRu-79yplIAZ6jmA 
Key    Value
---    ---
TOTP   [map[token:392528 ttl:22 url:otpauth://totp/Generator:?secret=JBSWY3DPEZAK3PXP&issuer=Generator&algorithm=SHA1&digits=6&period=30]] 
UID    32t82-oRu-79yplIAZ6jmA

Update a Secret

To update an existing secret, use the following command, passing in JSON data that represents the updated secret's information. The corresponding record in the Keeper Vault will be updated to match the JSON data passed.

vault write -format=json ksm/record uid=<UID> data=@update.json

In this example, the updated data is passed in from a file, this is recommended for cleaner and more simple CLI commands. The JSON data can be passed in on the command line, but quotes will need to be escaped.

Example data file:

update.json

{
  "fields": [
    {
      "type": "login",
      "value": [
        "[e-mail]"
      ]
    },
    {
      "type": "password",
      "value": [
        "kjh4j3245DCD!d"
      ]
    }
  ],
  "notes": "\tThis record was updated with the Vault KSM plugin",
  "title": "Sample Updated Record",
  "type": "login"
}

TIP You can see the current values of a secret in JSON format with this command: vault read -field=data -format=json ksm/record uid=<UID>

Create a Secret

Similar to updating a secret, create a new secret by passing JSON data to the following command:

vault write -format=json ksm/record/create folder_uid=<UID> data=@data.json

In this example, the updated data is passed in from a file, this is recommended for cleaner and more simple CLI commands. The JSON data can be passed in on the command line, but quotes will need to be escaped.

Example data file:

data.json

{
      "fields": [
             {
      "type": "login",
      "value": [
       "[e-mail]"
      ]
    },
    {
      "type": "oneTimeCode",
      "value": [
        "otpauth://totp/Generator:?secret=JBSWY3JP9HPK3PXP\u0026issuer=Generator\u0026algorithm=SHA1\u0026digits=6\u0026period=30"
      ]
    }
  ],
  "notes": "\tExample Record wth TOTP",
  "title": "Sample TOTP SECRET",
  "type": "login"
}

Delete a Secret

vault delete ksm/record uid=Oq3fFu14hZY00d7sp3EYNA