Manage secrets using HashiCorp Vault

This topic provides information about integrating Deploy with external secrets management tools for secure management of passwords, keys, certificates, and other secrets. While you can choose to manage sensitive key/value pairs for environment-specific information using internal encrypted dictionaries, Deploy also supports integration with the HashiCorp Vault secrets management tool to manage and inject secrets into Deploy. The API-based integration with Vault enables you to define, manage, and use Vault as an external data source for secret storage. This API will support future integrations with other secrets management tools.

How it works

The HashiCorp Vault integration is a Deploy plugin that you install that lets you configure external dictionaries that can be used with your environments. You can also define a Vault-based lookup provider that can reference and resolve a key/value pair stored in Vault. Deploy does not save or cache the key/value information stored in Vault in the Deploy system.

Use external Vault-based dictionaries

Managing an external HashiCorp Vault dictionary is similar to how you currently manage internal dictionaries in Deploy.

• You assign a Vault-based dictionary to an environment.
• During deployment, key/value pairs stored in Vault will replace defined placeholders in the deployment to the environment.

To manage a Vault dictionary, you:

1. Define a connection to your Vault server and the paths to where secrets and values are stored.
2. Define an external dictionary using this connection.
3. Associate the external dictionary with an environment.
4. Create placeholder references to secrets and other values stored in Vault.

Use an external Vault lookup provider

For secrets and password fields used with certain CI's, you can establish a Vault-based lookup provider that will be used to look up a value based on a lookup provider key that you specify. See Create an external lookup value provider for details.

User access control

As with any security-related feature, controlling access to sensitive data needs to be managed as part of the integration. Deploy provides controls to limit access, ensuring that:

• Developers are authenticated and authorized to read secrets
• Role-based access to secrets is supported
• Policies are provided to control credentials and how they can be used

The integration with Vault is controlled by the connection to the Vault server itself and the specific list of keys (Secret paths) that the user can access.

Install the plugin

To install the plugin:

1. Download the Deploy HashiCorp Vault plugin from the distribution site.
2. Place the plugin inside the XL_DEPLOY_SERVER_HOME/plugins/ directory.
3. Restart Deploy.

For additional details on installing or removing a plugin, see Install or remove Deploy plugins

Create a HashiCorp Vault connection

Deploy supports the HashiCorp Vault secrets management tool using a Vault connection CI configuration type. The role of this type is to allow you to configure a connection to a HashiCorp Vault server and be able to read key values.

To create a new connection to a Vault server:

1. Hover over Configuration, click , and select New > vault > hashicorp > VaultServer.

2. In the Name field, enter a name for the Vault connection.

3. In the Server Address field, enter an address for the Vault server.

4. Complete optional fields as needed.

5. Click Save or Save and close.

   

Define Authentication Method with either Authentication AppRole or Authentication TokenId.

1. Authentication AppRole.
   1. In the App Role field, enter the approle name.
   2. In the Role Id field, enter the role Id.
   3. In the Secret Id field, enter the secret Id.
   4. In the path field, enter the path.
   5. To connect with AppRole, authentication policies should be defined in the Hashicorp vault.
   6. To test the connection with approle authentication the following capability should be added in the policy:

path "sys/auth" { capabilities = [ "read" ]}

1. Authentication TokenId
   1. In the Token field, enter the token.
   

Manage a Vault connection

Your Vault connection is listed under Configuration in the Deploy Library.

To edit properties:

1. Expand the Configuration node.
2. Hover over the Vault connection (e.g., MyCompanyVault), click , and select Edit Properties.

Enable a Secrets Engine

Secrets engines are mountable engines that store or generate secrets in your Vault. Deploy allows you to extend your HashiCorp Vault by enabling pluggable secret engines such as Consul, MySql, AWS, MongoDB, and more.

To enable secrets engine for your HashiCorp Vault from the CI Explorer:

1. Expand the Configuration node
2. Hover over the Vault connection (e.g., MyCompanyVault), click , and select New > secrets > hashicorp > vault > SecretEngine
3. In the Name field, enter a name for the secrets engine
4. In the Path field, enter the path of the mount point
5. Complete optional fields as needed
6. Click Save or Save and close

The newly created secrets engine should now be visible in the CI Explorer under your Vault connection.

Create an external dictionary

Once you have defined your external Vault server connection, you can create a dictionary that you can associate with your environments. To create an external dictionary:

1. Hover over Environments, click , and select New > secrets > hashicorp > vault > VaultDictionary.

2. In the Name field, enter a name for the Vault dictionary.

3. In the Vault server field, enter the name of the Vault server connection you created earlier (e.g., MyCompanyVault).

4. In the Secret paths field, type one or more secret paths to where key-value pairs are stored.

5. Click Save or Save and close.

   

Create an external lookup value provider

You can specify certain properties for a Configuration Item (CI) that should be looked up in an external source. This is useful for sensitive data that is not part of a deployment package such as hosts or cloud targets.

To support this, you can create a special CI type called a LookupValueProvider that references your Vault connection. Once this configuration is in place, you can select the LookupValueProvider and type a key/identifier for the value that you want to use.

To create Vault lookup provider:

1. Hover over Configuration, click , and select New > secrets > hashicorp > vault > lookup > VaultLookupValueProvider.

2. In the Name field, enter a name for the Vault lookup provider.

3. In the Vault server field, enter the name of the Vault server connection you created earlier (e.g., MyCompanyVault).

4. In the Secret paths field, type one or more secret paths to where key-value pairs are stored.

5. Click Save or Save and close.

   

Select an external lookup value provider and key

After creating an external lookup value provider, you can now select it and choose a key when configuring properties for certain CIs. For example, if you want to store and resolve a password for a host CI:

1. Hover over Infrastructure, click , and select New > overthere > SshHost.

2. Complete the required fields for the CI.

3. In the SU password field, click and select the VaultLookupProvider you created in Create an external lookup value provider.

4. In the Lookup provider key field, type the name of the key for the corresponding value that is stored in Vault.

   

5. Click Save or Save and close.