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 Management page in BMC Discovery.

For information on integrating BMC 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

For the BMC Discovery appliance to be able to access HashiCorp Vault, you must also perform the integration from the appliance. For a registered BMC Discovery Outpost to be able to access HashiCorp Vault, you must also perform the integration from the BMC Discovery Outpost.

1. To integrate the BMC Discovery appliance with HashiCorp Vault:
   1. From the main menu of the appliance UI, click the Administration icon.
      The Administration page is displayed. 
   2. In the Discovery section, click Vault Management.
   3. Select HashiCorp Vault.
      
      
   To integrate the BMC Discovery Outpost 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 the HashiCorp Vault tab.
      
      
   
   

2. 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.
   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 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 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. 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 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 Discovery appliance, 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 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 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, the system 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.

3. Click Test to test the connection. 

   Important

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

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