VaultEncryption

This guide explains how to use Hashicorp Vault ("Vault") for encrypting and decrypting properties within the Itential Automation Platform (IAP).

Token File

Currently authenticating with Hashicorp Vault requires a token. This may be a root token, although this is not recommended, or a general-purpose token with access to read and write to a specific Secrets Engine within Vault. This token will look something like this: s.ydsFeHv6ntV3gLxvPKuMcyRW

Once you have the token, save it to the file system in a file named, for example, token.txt. This is needed for every server within a cluster.

Vault Configuration

All vault configuration should go within the vaultProps key inside the properties.json. An example configuration is included below.

Example: properties.json

   {
     "vaultProps": {
        "url": "http://example.vault.server",
        "token": "/file/path/token.txt",
        "endpoint": "kv/data"
     }
   }

The following properties are supported.

Creating a Secret within Vault

To create a secret within Vault:

1. Go to the Vault Server that will be connected with IAP, and open the user interface.
2. Open the KV Secrets Engine you have configured. If this does not exist, create one.
3. Click Create Secret.
4. Choose a path for this secret. This must be unique, and it will be important for future steps.
5. In the Version data there are two input boxes that require values.
6. In the key input box on the left, type the value you want to use as a key within that file path. You can include multiple keys within one path.
7. In the value input box, type the unencrypted value you would like to store as a secret within Vault. For example, if you wanted to store a value as a "default_password", and give it the value of "password":
   • Type "default_password" into the path.
   • Type "key" into the key.
   • Type "password" into the value input boxes.
8. Repeat for any additional secrets you would like to store in Vault.

Using a Secret within IAP

For each place where encryption can be used, the provided examples will revolve around a path of "default_password" and a secret of "password", and can be substituted for real data.

Services

To set encryption for Adapters:

1. Go to Admin Essentials, click the Adapters tab, and select an Adapter.
2. Within this Adapter, locate the value you would like to encrypt. This is likely within the properties.properties object. It may currently have a value of "$ENC..."
3. Remove the existing value. Replace it with "$SECRET_" and then the path within Vault to where that secret is stored, followed by " $KEY_" (HINT: there is a space before "$KEY") and the key within that path. An example would be "$SECRET_default_password $KEY_key" which will evaluate to "password".
4. Save the adapter, and it will automatically restart using Vault to decrypt the changed property.

Profiles

To set encryption for Profiles:

1. Go to Admin Essentials, click the Profiles tab, and select the currently running profile.
2. Within this profile, click Configure, and then select one of the profile properties, such as RabbitMQ. Choose a RabbitMQ property to encrypt, such as "password".
3. Remove the existing value. Replace it with "$SECRET_" and then the path within Vault to where that secret is stored, followed by " $KEY_" (HINT: there is a space before "$KEY") and the key within that path. An example would be "$SECRET_default_password $KEY_key" which will evaluate to "password".
4. Save the profile.
5. Restart IAP for these changes to take effect.

Properties.json

Note: It is not possible to encrypt any of the vaultProps within the properties.json.

1. Open the properties.json and select a property to encrypt, such as "mongoProps.credentials.passwd".
2. Remove the existing value. Replace it with "$SECRET_" and then the path within Vault to where that secret is stored, followed by " $KEY_" and the key within that path. An example would be "$SECRET_default_password $KEY_key" which will evaluate to "password".
3. Save the document.
4. Restart IAP for these changes to take effect.