Use HashiCorp Vault secrets

Use the $SECRET/$KEY syntax to reference secrets stored in HashiCorp Vault directly in Itential Platform configuration values, adapter and integration properties, system profiles, and properties files.

Secret reference format

$SECRET_<path> $KEY_<key-name>

The format includes:

$SECRET_ followed by the Vault path (the path within the kv-v2 secrets engine)
A space character
$KEY_ followed by the key name within that secret

Example: $SECRET_network/routers $KEY_password retrieves the value of the password key at the Vault path network/routers.

The path in a $SECRET reference is relative to your kv-v2 mount point. Do not include the mount point name or /data/ prefix in the reference.

You cannot use Vault secret references to configure the Itential Platform connection to Vault itself. The vaultProps block in properties.json does not support $SECRET/$KEY syntax.

Configure Platform properties

Platform 6 properties file

Reference secrets in platform.properties:

mongo_auth_enabled=true
mongo_user=$SECRET_platform/mongodb $KEY_username
mongo_password=$SECRET_platform/mongodb $KEY_password
mongo_url=$SECRET_platform/mongodb $KEY_uri

Server profile (properties.json)

Reference secrets in properties.json for Platform 2023.2:

{
  "mongoProps": {
    "credentials": {
      "dbAuth": true,
      "user": "$SECRET_platform/mongodb $KEY_username",
      "passwd": "$SECRET_platform/mongodb $KEY_password"
    },
    "url": "$SECRET_platform/mongodb $KEY_uri"
  }
}

Configure adapters, integrations, and applications

The following example uses an Adapter. The same steps apply to Integrations and Applications.

Using advanced view

Open Admin Essentials

Navigate to Admin Essentials and select Adapters.

Select an adapter

Select the adapter you want to configure.

Enable advanced view

Click the Advanced View toggle in the upper-right to access the JSON configuration.

Replace sensitive values

Replace sensitive values with Vault secret references.

Example:

{
  "properties": {
    "password": "$SECRET_adapters/servicenow $KEY_password"
  }
}

Save configuration

Click Save. The adapter restarts automatically and retrieves the secret from Vault.

Using the configuration form

Open Admin Essentials

Navigate to Admin Essentials and select Adapters.

Select an adapter

Select the adapter you want to configure.

Enter the secret reference

Enter the Vault secret reference using the $SECRET_<path> $KEY_<key-name> format in the property field.

Save configuration

Click Save. The adapter restarts automatically and retrieves the secret from Vault.

Configure system profiles

Open Admin Essentials

Navigate to Admin Essentials and select Profiles.

Select the active profile

Select the active profile from the list.

Open configuration

Click the Configure tab.

Select a property

Select a profile property to configure with a Vault reference.

Enter the secret reference

Replace the value with a Vault secret reference using the $SECRET_<path> $KEY_<key-name> format.

Save and restart

Save the configuration and restart Itential Platform for the changes to take effect.

What’s next

Automatically encrypt properties

Let Platform store sensitive properties in Vault.

Manually encrypt properties

Use the $SECRET syntax to encrypt specific properties.

Troubleshoot

Resolve common issues.