Configuring apps for HashiCorp Vault

HashiCorp Vault is an identity-based secrets and encryption management system that is used to manage and protect access to sensitive data. You can configure IBM® SOAR apps to reference credentials that are stored in Vault's key-value secret engine.
Important: IBM SOAR supports only the key-value secret engine.

Vault setup

To allow the SOAR app client to authenticate to Vault and interact with the SOAR Platform, you must create an AppRole in the Vault instance. For more information about creating AppRoles, see AppRole Pull Authentication on the HashiCorp Vault website.

The app must have read access to the secret engine and to the paths of the specific secrets that you want to share with the app. Do not grant access to any secret engines or paths that the app does not need. For better control and visibility into how the apps use the credentials in Vault, create a different app role for each SOAR app.

After you create the AppRole, note the role_id and the secret_id for the role. This information must be stored as a protected secret on the SOAR Platform so that each app can connect to Vault. If the secret_id is configured to expire frequently, an administrator must manually retrieve the value and reset it in the SOAR Platform app.

HashiCorp Vault configuration in the SOAR app

After the application is configured in CCP and the client you have the role_id and secret_id values, install the SOAR app on the SOAR Platform.

When you configure the app, use the following values to configure the connection to Vault.
Table 1. HashiCorp Vault connection settings
Configuration parameter Value

PAM_TYPE

HashiCorpVault

PAM_ADDRESS

Specify the address where your HashiCorp server can be reached. If applicable, include the port.

This value is typically the same as what you would set for VAULT_ADDR when you use the Vault command-line interface. For example, the address might look like https://my_vault.cloud.hashicorp.com:8200.

PAM_APP_ID

Set this parameter to the role_id value for the AppRole.

PAM_SECRET_ID

Set this parameter to the secret_id value for the AppRole.

PAM_VERIFY_SERVER_CERT

This parameter is optional, depending on your Vault configuration.

If your configuration requires this parameter, the accepted values are True, False, or the path to a certificate chain that authenticates a self-signed certificate on a self-hosted Vault server. The recommendation is to accept the default value of True.

Important: Do not use this parameter in a production environment.

Referencing a Vault secret

The app.config file structure that you must follow for each secret that you want to reference is restrictive. The app fails if the proper structure is not used.

Each configuration that you want to pull from Vault must be prefixed with the caret (^) symbol.

Each secret that you want to pull from Vault requires the following three values, with a period (.) separating each one.
  • The name of the secrets engine in Vault.
  • The path to the secret within the engine.
  • The name of the specific key that you want to get the value for.
The IBM SOAR app.config entry follows this format:
[SOAR_app_name]
<configuration_name>=^<secret_name>.<path/to/the/secret>.<secret_password>
For example, assume that you have a secret that is named secret1 and stored in the key-value engine. The path to the secret is test/soarapp, and the secret credential is named secret_password. You are installing the fn_my_app app and the configuration is called my_secret_config. In this example, the app.config file includes the following entry:
[fn_my_app]
my_secret_config=^secret1.test/soarapp.secret_password
If the app calls secrets by using an SQL type statement, use the following syntax to dynamically insert values that are retrieved from the Vault within a configuration string. 
[fn_my_app]
sql_query=FROM table SELECT ^{secret1.test/soarapp.value_to_select}

Testing the configuration

After both the vault and the app are configured, you can test the configuration to ensure that the vault connection works and that the app is configured correctly. To test the configuration, go to the app's Configuration page and click Test configuration.