Itential Automation Platform

On this page:

HashiCorp Vault Encryption

This guide explains how to install and configure HashiCorp Vault ("Vault"). This application is used for encrypting and decrypting properties within the Itential Automation Platform (IAP).

Install Vault

To install Vault:

  1. You must be logged in as root. Using sudo or a different account with the same access as root will not work.

    Figure 1: Root User

    Root user

  2. Install yum-config-manager to manage your repositories.

    yum install -y yum-utils

    Figure 2: Install Command

    Install command

  3. Use yum-config-manager to add the official HashiCorp Linux repo.

    yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

    Figure 3: Add Vault Repo

    Add Vault Repo

  4. Install Vault.

    yum -y install vault

    Figure 4: Install Vault

    Install Vault

  5. Verify installation.

    vault --version

    Figure 5: Verify Install

    Verify install

Configure Vault

To configure Vault:

  1. Navigate to /opt/vault.

    Figure 6: Change Directory

    Change directory

  2. Create a config file with an hcl file extension.

    Figure 7: Create Config File

    Create config

  3. Edit the config by adding the information below.

    ```storage "raft" {
    path = "/opt/vault/data"
    node_id = "node1"
    }

    listener "tcp" {
    address = "127.0.0.1:8200"
    tls_disable = "true"
    }

    api_addr = "http://127.0.0.1:8200"
    cluster_addr = "https://127.0.0.1:8201"
    ui = true
    ```

    Figure 8: Edit Config File

    Edit config

  4. Run Vault using the command vault server -config=/opt/vault/config.hcl. This will start the Vault Server using the newly created config file.

    vault server -config=/opt/vault/config.hcl

    Figure 9: Start Vault

    Start Vault

  5. Once the Vault Server is running, open a second terminal window. Do not close the first terminal window as this will stop the Vault Server.

    Figure 10: Vault Server is Running

    Vault is running

Unseal Vault Server

To unseal the Vault server:

  1. In the second terminal window run the following commands:

    export VAULT_ADDR='http://127.0.0.1:8200'
    vault operator init

    Figure 11: Run Commands Second Terminal Window

    Run commands

  2. Copy the outlined key information from the terminal window into a text file. You will need to use this information more than once.

    Figure 12: Copy Key Information

    Copy keys

  3. Run the unseal command vault operator unseal three (3) times using the unseal key information copied to the text file. You will need to use three (3) different unseals keys. It does not matter which three you use, but make sure each one is different.


    Note: By default there are five (5) keys with a threshold of three (3) keys. Once three (3) keys are entered the vault is unsealed. The progress of unsealing is outlined in the image below.


    Figure 13: Unseal Progress

    Unseal key progress

  4. Login to Vault using the initial root token (it should have been copied to the text file with the unseal keys). Use vault login <INITIAL_ROOT_TOKEN>.

    Figure 14: Login to Vault

    Login to Vault

  5. Run the vault operator generate-root -init to obtain a One Time Password (OTP).

    Figure 15: Get OTP

    Get OTP

  6. Run the command vault operator generate-root to obtain the encoded key. This step will need to be performed three (3) times using the unseal keys. You may use the same three keys from before. Copy the encoded key to your text file.

    Figure 16: Get Encoded Key

    Get encoded key

  7. Use the command vault operator generate-root -decode=$ENCODED_TOKEN -otp=$OTP to obtain a new root key. Remember to replace the variable with your encoded token and OTP.

    Figure 17: Get New Root Key

    Get new root key

  8. Once the new root key is generated (outlined in the image below), create a token.txt file for storage. The location of the token file should be in /opt/vault directory.

    Figure 18: Store New Root Key

    Store new root key

Enable KV Secrets Engine

To enable the KV Secrets Engine for Vault:

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

    Figure 19: Enable KV Engine

    Enable KV Engine

  2. 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 Vault properties section below.

    Figure 20: Edit Properties

    Edit properties

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 next section on Configuring the readOnly Property.

The vaultProps section is configured with the following properties:

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

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 IAP where the actual vault token is stored.

Example: URL Structure

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

For more information on using Vault:

Configuring the readOnly property

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

Creating a Secret Using the Vault UI

To create a secret within Vault:

  1. Go to the Vault Server UI connected with IAP and login.

    Figure 21: Vault UI

    Vault UI

  2. Click anywhere on the KV bar.

    Figure 22: Secrets Engine KV Bar

    Vault UI

  3. Click the Create secret + button.

    Figure 23: Create Secret

    Vault UI

  4. Choose a path from the dropdown or enter manually. This must be unique, and it will be important for future steps.

  5. Enter the number of versions to keep for the secret metadata.

  6. In the key filed in the secret data section, enter the secret data information. For this example test_pass was used.

  7. Click the eye icon (button) to make sure the information was added correctly. You can include multiple keys within one path, or use the Add button to enter additional secret data.

  8. Click the Save button when you are finished.

    Figure 24: Save Secret

    Vault UI

  9. Secrets may be entered using JSON. The Version 1 dropdown menu pertains to the iteration of the secret entered not the version of the KV Vault Engine.

    Figure 25: JSON Toggle Switch

    Vault UI

  10. The newly created secret will appear alphabetically in the list. From the dropdown menu a variety of functions maybe peformed, such as deleting and viewing details.

    Figure 26: Secrets List

    Vault UI

Automatic Property Encryption

For most sensitive properties within IAP, it is no longer necessary to manually create secrets within Vault to handle encryption. Instead, if Vault is configured, these propertes will be automatically encrypted. For example, to create a Vault secret for an IAP profile with a rabbitmq.password property, all that is required is to call the API to create the profile, or create the profile in the UI, and ensure that the rabbitmq.password property is filled out in plaintext. This property will not be stored in the database, but instead stored in Vault. Likewise, to update that password, such as when key rotation is needed, simply calling the update API for profiles, or updating it via the UI, with the plaintext password included in the request body.

Using $ENC or $SECRET syntax for these properties is heavily discouraged, as no "double encryption" will ever be performed on those properties.

Adapters

If an adapter has a property that will be automatically encrypted, this property will display in the form view as a value that is starred out (*****).

Figure 27: Adapter Configuration

Adapter Configuration

If this property already exists, or is being edited, differently-styled stars will appear for the value. From this view it is not possible to see the value that is being typed.

Figure 28: Adapter Configuration Update

Adapter Configuration Update

In the advanced view, it is possible to see the value being typed, although it will never be starred if it already exists. Instead, it will display as an empty string regardless of the actual value. It will also appear with a different tooltip display indicating it has an encrypted property.

Figure 29: Adapter Configuration Advanced View

Adapter Configuration Advanced

Integrations

If an integration has a property that will be automatically encrypted, this property will display in the form view as a starred out value. These encrypted properties are standardized based on the type of authentication used by the integration.

Figure 30: Integrations Configuration

Integration Configuration

If this property already exists, or is being edited, differently-styled stars will appear for the value. From this view it is not possible to see the value that is being typed.

Figure 31: Integrations Configuration Update

Integration Configuration Update

In the advanced view, it is possible to see the value being typed, although it will never be starred if it already exists. Instead, it will always display as an empty string. It will also appear with a different tooltip indicating it has an encrypted property.

Figure 32: Integrations Configuration Advanced View

Integration Configuration Advanced

Applications

While most Itential applications do not have any properties that are configurable, thereby leading to no sensitive properties, it is possible for custom applications to have properties configured in the propertiesDecorators.json to always be encrypted. These will appear the same way as adapters and integrations in the Admin Essentials user interface.

Profiles

If a profile has a property that needs to be automatically encrypted, such as the rabbitmq password, it will display as a starred out value to indicate it is an encrypted property.

Figure 33: Profile Configuration

Profile Configuration

If this property already exists, or is being edited, differently-styled stars will appear for the value. The difference is subtle but is a visual indication between a pre-configured secret versus a field that hasn't yet been configured with a secret. Please note that from this view, it is not possible to see the value that is being typed.

Figure 34: Profile Configuration Update

Profile Configuration Update

Manual Property Encryption

It is still possible to have specific keys encrypted in Vault using the $SECRET syntax. Although this practice is an available option, property encryption should be performed automatically wherever possible.

Adapters

To set encryption for Adapters:

  1. Within Vault, create the path and key name for the item in question. HINT: Be sure to give it a path and key name that is easy to relate back to the targetted item.

  2. Go to Admin Essentials, click the Adapters menu, and select an Adapter.

    Figure 35: Select Adapter

    Select adapter

  3. Within the adapter you selected, locate the value you would like to encrypt. Click the Advanced View toggle switch to see the JSON, which may be easier to edit.

    Figure 36: Advanced Configuration View

    Advanced adapter view

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

    Figure 37: Edit Adapter

    Edit adapter

  5. Click Save and the adapter will automatically restart using Vault to decrypt the changed property.

  6. The adapter should appear in the list with a green status indicator and connection icons after restart.

    Figure 38: Adapter Connected

    Restart adapter

Profiles

To set encryption for Profiles:

  1. Within Vault, create the path and key name for the item in question. HINT: Be sure to give it a path and key name that is easy to relate back to the targetted item.

  2. Go to Admin Essentials, click the Profiles tab, and select the currently running profile.

  3. Within this profile, click Configure, and then select one of the profile properties, such as RabbitMQ.

    Figure 39: Edit Profile Properties

    Edit profile

  4. Choose a RabbitMQ property to encrypt, such as "password".

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

  6. Save the profile.

    Figure 40: Save Profile Properties

    Edit profile

  7. Restart IAP for these changes to take effect.

Properties.json

To set encryption for a property:

  1. Within Vault, create the path and key name for the item in question. HINT: Be sure to give it a path and key name that is easy to relate back to the targetted item.

  2. Open the properties.json and select a property to encrypt, such as "mongoProps.credentials.passwd".


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


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

  4. Save the document.

  5. Restart IAP for these changes to take effect.