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):
Before you begin
Tip
Credential broker performance testing
Credential brokers are designed with human interaction in mind. When BMC Helix Discovery is scanning, it can make many simultaneous API calls. Before putting an integration with any supported credential broker into production, you should perform scale and performance testing in your IT environment.
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
- From the main menu in the BMC Discovery Outpost, click Manage > Vault Providers.
The Manage Vault page is displayed. Select HashiCorp Vault.
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 certificateThe 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.
Click Test to test the connection.
Important
The configuration is not saved until you click the Apply button.
- 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:
Key | Value |
---|---|
discovery | password01 |
root | rootpassword01 |
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:
Comments
Log in or register to comment.