The private/public key pairs used by Blackbox can be stored in and retrieved from a key vault, preventing the need to store the keys locally.

This page details how to set up and configure a Hashicorp Vault for use with Blackbox.

The Hashicorp Vault Getting Started documentation provides much of the information needed to get started. The following section goes over some additional considerations when running Blackbox with Vault.

↳ Configuring the vault

↳ TLS

When running in production situations it is advised to configure the Vault server for 2-way (mutual) TLS communication. Blackbox also supports 1-way TLS and unsecured (no TLS) communications with a Vault server.

An example configuration for the Vault listener to use 2-way TLS is shown below. This can be included as part of the .hcl used when starting the Vault server:

listener "tcp" {
        tls_min_version = "tls12"
        tls_cert_file = "/path/to/server.crt"
        tls_key_file = "/path/to/server.key"
        tls_require_and_verify_client_cert = "true"
        tls_client_ca_file = "/path/to/client-ca.crt"
}

↳ Auth methods

Blackbox directly supports the AppRole auth method. If required, other auth methods can be used by logging in outside of Blackbox (e.g. using the HTTP API) and providing the resulting vault token to Blackbox. See the Enabling Blackbox to use the vault section below for more information.

When using AppRole, Blackbox assumes the default auth path to be approle, however this value can be overwritten. See Keys for more information.

↳ Policies

To be able to carry out all possible interactions with a Vault, Blackbox requires the following policy capabilities: ["create", "update", "read"]. A subset of these capabilities can be configured if not all functionality is required.

↳ Secret engines

Blackbox can read and write keys to the following secret engine type:

• K/V Version 2

The K/V Version 2 secret engine supports versioning of secrets, however only a limited number of versions are retained. This number can be changed as part of the Vault configuration process.

↳ Enabling Blackbox to use the vault

↳ Environment Variables

If using a Hashicorp Vault, Blackbox requires certain environment variables to be set depending on the auth method being used.

• If using the AppRole auth method, set:

  1. HASHICORP_ROLE_ID
  2. HASHICORP_SECRET_ID

  These credentials are obtained as outlined in the AppRole documentation. Blackbox will use these credentials to authenticate with Vault.

• If using the root token or you already have a token due to authorising with an alternative method, set:

  1. HASHICORP_TOKEN

!!! note If using TLS additional environment variables must be set. See Keys for more information as well as details of the Blackbox configuration required to retrieve keys from a Vault.

↳ Dependencies

The Hashicorp dependencies are included in the Blackbox-app-<version>-app.jar. If using the Blackbox-simple-<version>-app.jar then hashicorp-key-vault-<version>-all.jar must be added to the classpath.