Integrating with HashiCorp Vault

HashiCorp Vault is an application software that helps you to store and manage secrets securely, according to policies that your organization might require. HashiCorp Vault regards a secret as anything that you want to tightly control access to, such as API keys, passwords, or certificates. 

You can configure the integration with HashiCorp Vault by using the Vault Providers page in the BMC Discovery Outpost.

For information on integrating BMC Helix Discovery with HashiCorp Vault, see the following video (04:19):

 https://youtu.be/ARWQ-oNKTeQ

Before you begin

HashiCorp Vault Secrets Engine support

The integration with HashiCorp Vault only supports the kv v2 Secrets Engine and has been tested with HashiCorp Vault 1.7.3.

To integrate with HashiCorp Vault

1. From the main menu in the BMC Discovery Outpost, click Manage > Vault Providers.
   The Manage Vault page is displayed. 

2. Select HashiCorp Vault.

   

3. On the Vault Management page, specify the settings appropriate to your HashiCorp Vault.

   Field Name	Description
   Status	A read-only display showing the status of the integration with HashiCorp Vault. This can be one of: ACTIVE, DISABLED, or messages such as TEST OK, TEST ERROR, or ERROR and an explanatory message.
   Enabled	Select the check box to enable the integration with HashiCorp Vault.
   URL	The URL of HashiCorp Vault. Only HTTPS URLs are permitted. This field is required. You must obtain the URL, user name, and password to access HashiCorp Vault from your HashiCorp Vault administrator.
   Namespace	A Namespace that you have configured in your HashiCorp Vault. For example, if my/deep/company/subfolder is a namespace configured in HashiCorp vault, enter that value here. you can then access secrets using a relative path from the namespace. See Mount paths for more information. This field is only required if you use a Namespace to access your HashiCorp Vault.
   Access Method	Select one of the following access methods: • Token — The token authentication method is the only method available when a new HashiCorp Vault server is deployed. It is the default access method for BMC Helix Discovery. • Userpass — specify a username and password • Cert — A TLS certificate The access methods are described below:
   	Token	Token — The token policy should include at least the path auth/token/lookup-self with the read capability, so that BMC Helix Discovery checks can confirm the token's validity. The token field is required for this method.
   	Userpass	The fields are: Custom Mount Path - The default setting is userpass. If your HashiCorp Vault is configured to use a different mount path, enter that here. Username - The username for the HashiCorp Vault. This field is required. Set Password - Field in which you can enter the password. To make the field editable, select the check box and set the password. By default, the password is not displayed. (optional)
   	Cert	In the cert authentication method, you must use a restricted account, with an ACL policy to access the kv v2 Secrets Engine holding the BMC Helix Discovery credentials. The fields are: Custom Mount Path - The default setting is cert. If your HashiCorp Vault is configured to use a different mount path, enter that mount path here. TLS Certificate Bundle - The TLS certificate bundle must be in PEM format. The bundle must include the client certificate and the private key for the BMC Helix Discovery instance, and can optionally include the CA certificate of the vault. Set TLS Bundle Passphrase - If the TLS bundle is encrypted by using a passphrase (when generated by using OpenSSL), BMC Helix Discovery requires the passphrase to decrypt and use the bundle at runtime. If your bundle is not encrypted, a passphrase is not required. Select the check box and enter the passphrase. By default, the passphrase is not displayed. Role - A named certificate role to authenticate against. The default behavior is to try all certificate roles. This field is optional.
   Checkout Duration (in minutes)	The time (in minutes) for which the password will to remain valid. The default is 15 minutes and the minimum is one minute.
   Timeout (in seconds)	The timeout (in seconds) for requests sent to the provider. The default is 300 seconds.
   TLS Certificate Check	By default, BMC Discovery Outpost checks the TLS certificate against the HashiCorp Vault server. You can clear the check box to disable the TLS certificate check, but this should only be done in a test environment against the server. The result is reported in the Status message.

4. Click Test to test the connection. 

   Important

   The configuration is not saved until you click the Apply button.

5. Click Apply to save and apply the configuration.

How credentials are stored in HashiCorp Vault

Credentials are referred to as secrets in HashiCorp Vault, and are all named. You access the credentials from the BMC Helix Discovery credentials UI by using a path and key to uniquely identify the element of the credential to use.

Mount paths 

HashiCorp Vault uses mount paths as a pseudo file system. For example, you might choose to store a credential under kv/data/ssh/server74, where:

• kv is the default server engine root path.
• data is a fixed path that tells the kv v2 Secrets Engine that the request is for data.
• ssh/server74 is the folder in the kv v2 Secrets Engine where the data is stored. Inside the kv v2 engine, the ssh/server74 folder represents the full path.
  You can also define ssh as a namespace. Namespaces enable you to refer to server74 as the relative path from the namespace. For more information, see the HashiCorp Vault  product documentation .

A more complex example of using a different kv v2 Secrets Engine to store the credentials for a personal server:

• my-custom-kv is the custom root for a kv v2 Secrets Engine. More than one Secrets Engine can be defined with custom roots.
• data is a fixed path that tells the kv v2 Secrets Engine that the request is for data.
• my/deep/company/subfolder is a namespace.
• my-personal/server-name is your personal server.

In the BMC Helix Discovery UI, the expected format for locating a credential in HashiCorp Vault is <kv root>/data/<folders>, where:

• kv root is the default server engine root path
• folders is the folder in the kv v2 Secrets Engine

To access the secrets from BMC Helix Discovery, the path is: 
my-custom-kv/data/my/deep/company/subfolder/my-personal/server-name

However, be aware that in the HashiCorp admin console breadcrumb path, the path is shown without the data element: 
my-custom-kv/my/deep/company/subfolder/my-personal/server-name

Key/value pairs

In BMC Helix Discovery, you need login/password pairs to authenticate onto systems. Using a single path+key to retrieve a login/password pair simplifies the query. Where a credential needs just a key or certificate, use only the returned key value. Under the mount path, we store the credential by using key/value pairs: the key stores the username, and the value stores the password.

For example, for a server called "server74", the following details are configured in HashiCorp Vault, on the kv/ssh/server74 secret:

For information about configuring credentials in HashiCorp Vault, see the  product documentation .  

To use a credential from HashiCorp Vault in BMC Helix Discovery

In this example, in HashiCorp Vault, the credential name is stored under the /ssh/server74 mount path, the normal login username is discovery, and the privileged  login username is root. The HashiCorp kv path for both login usernames is kv/data/ssh/server74:

The following screenshot shows adding the credential for server74: