Enabling the KV Secrets Engine

The Vault Secrets Engine must be enabled and configured in advance before it can manage and share secrets securely.

Vault KV-V2 Secrets Engine

To enable the KV Secrets Engine for Vault:

Run the command vault secrets enable kv-v2 to enable the KV Secrets Engine. V2 is the recommended version for Vault.

Figure 1: Enable KV Engine
Navigate to /opt/pronghorn/current and edit the properties.json file with the location of the token.txt file. More information on the token file can be found in the next section, Configure Vault Properties.

Figure 2: Edit Properties

Configure Vault Properties

To use Vault, there must be a vaultProps section within the properties.json file.

Property	Required	Default	Description
url	Yes	`http://localhost:8200`	The default URL to connect to Vault, including the hostname and port.
token	Yes	`/file/path/token.txt`	The file path to a document containing a token. The token is used for authentication to access Vault secrets.
endpoint	Yes	`secret/data`	The endpoint for the Secrets Engine type that is used.
readOnly	Yes	`false`	Used to manage how secret data is written to Vault. See the section below on how to configure the `readOnly` property.
authMethod	No	`token`	The authorization method to connect to Hashicorp Vault. Either `token` or `approle`.
role_id	No	`"`	Hashicorp Vault RoleId used for AppRole authentication.
secret_id	No	`"`	Hashicorp Vault SecretID used for AppRole login.

Token

Below is an example vaultProps configured for token-based authentication.

"vaultProps": {
    "url": "http://localhost:8200",
    "authMethod": "token",
    "token": "/opt/vault/token.txt",
    "endpoint": "kv-v2/data",
    "readOnly": false
  }

 An unspecified authMethod defaults to using token-based authentication, which maintains previous Itential Platform version properties.json configurations.

AppRole

Below is an example vaultProps for AppRole authentication to Vault, where role_id and secret_id are required if approle is specified. Note that setup of approle and generation of the UUID role_id and the secret_id created against the role_id must be done by the customer, including setting valid policies and TTL/usage limits.

"vaultProps": {
    "url": "http://localhost:8200",
    "authMethod": "approle",
    "role_id": "cfb83d9f-fd94-e046-71e2-dcd51147288d",
    "secret_id": "68df6e13-02b2-b60d-a39f-f8b879277d48",
    "endpoint": "kv-v2/data",
    "readOnly": false
  }

File Path

Since pathing to the Secrets Engine can be whatever you set as a unique endpoint, the following URL sample is presented with v1 as a hard-coded file path in Itential Platform where the actual vault token is stored.

Example: URL Structure

http://localhost:8200/v1/kv-v2/data

Configuring Read Only in Vault Props

Beginning with the 2021.2 release, a readOnly property was added to vaultProps in the properties.json file. This property allows developers to denote fields that contain sensitive data and manage how secret data is written to Vault. This configurable property defaults to false.

When set as readOnly: true, the following will occur:

Masking in the UI will be disabled (turned off).
Clear text will be shown.
All custom user decorations will be ignored.
Itential Platform will not write data to Vault.

⚠ WARNING: If there are passwords stored within Vault and the readOnly property is initially set to false, and then later changed to true, all passwords will be lost and have to be set manually.