Liquibase HashiCorp Vault Extension

You can natively read your application secrets in Liquibase with the Hashicorp Vault extension. If you connect to your vault using the liquibase.properties file, you can store sensitive Liquibase authentication details such as database url, username, and password attributes and your Liquibase Pro license key in your vault.

For more information, see HashiCorp Vault documentation.

Requirements

Installation

CLI

  1. Navigate to the liquibase-hashicorp-vault extension on Maven Central
  2. Download liquibase-hashicorp-vault-<version>.jar and move it to the liquibase/lib directory

Maven

If you use Maven, add the HashiCorp Vault extension dependency in your pom.xml file to download the JAR:

<dependency>
    <groupId>org.liquibase.ext.vaults</groupId>
    <artifactId>liquibase-hashicorp-vault</artifactId>
    <version>1.0.0</version>
</dependency>

Liquibase Package Manager

Alternatively, you can install the HashiCorp Vault extension with lpm (Liquibase Package Manager).

lpm update
lpm add liquibase-hashicorp-vault

Usage

You can store any Liquibase property in HashiCorp Vault.

  1. Set the VAULT_ADDR and VAULT_TOKEN attributes as environment variables, as -D Java system properties, or in your liquibase.properties file, OR as a command line attribute as shown in the command line section below.
  2. In HashiCorp Vault, configure sensitive properties like your database username, password, URL, and Liquibase Pro license key as secrets.
  3. Gather the Vault HTTP API path of each secret in your vault. For example, /v1/secret/data/test_secrets.

    4. Note: If you use kv secrets engine v1, your HTTP API path will look like /v1/secret/example. If you use kv secrets engine v2, the path uses an additional "data" prefix and will look like /v1/secret/data/example. (The version number at the beginning of the API path is from the Vault HTTP API and is not related to the version of kv you use.)

  4. In your liquibase.properties file or other valid configuration location, specify each of those API paths as Liquibase parameters, such as url. Omit the /v1/ at the beginning of the API path. Use the syntax VAULT,PATH,FIELD.

    5. Tip: If your PATH includes whitespace, you must surround it with quotes. For example: "secret/my path/".

The following example shows a liquibase.properties file configured to store secrets in a vault:

Token authentication

Tip: Token authentication is the recommended way to connect Liquibase to HashiCorp Vault.

Vault usage without namespace using token authentication:

# Enable Liquibase Pro functionality
liquibase.licenseKey= hashicorp,secret/data/liquibase/license,pro_key

# Properties to store in the vault
url= hashicorp,secret/data/liquibase/urlLocation,url
username= hashicorp,secret/data/liquibase/usernameLocation,username
password= hashicorp,secret/data/liquibase/passwordLocation,password

# Authentication
vault.addr= https://vault.example.com:8200
vault.token= -DvaultTokenExample

JSON web token (JWT) authentication

Tip: If you need to use JWT authentication, please email support@liquibase.com for configuration assistance.

Vault usage with namespace using JWT authentication:

Note: liquibase.licenseKey= OR liquibase.licenseKey: are valid ways to indicate the values in the liquibase.properties file. 

# Properties to store in the vault
liquibase.licenseKey= hashicorp,secret/data/liquibase/license,pro_key
url= hashicorp,secret/data/liquibase/urlLocation,url
username= hashicorp,secret/data/liquibase/usernameLocation,username
password= hashicorp,secret/data/liquibase/passwordLocation,password

# Authentication
vault.addr=https://vault.example.com:8200
vault.jwt=your-jwt-token
vault.namespace=your-vault-namespace
vault.role=your-vault-role

Command Line Attributes

Attribute Definition Requirement
--license-key

Your Liquibase Pro license key

 Required
--vault-addr URL for HashiCorp Vault Server Required
--vault-token Access Token for HashiCorp Vault Server Optional
--vault-namespace Namespace for HashiCorp Vault Requests Optional
--vault-jwt JSON Web Token (JWT) for HashiCorp Vault Server. Not recommended. Optional
--vault-role Role for JSON Web Token (JWT) for HashiCorp Vault Server. Not recommended. Optional