An Intro to Spring Cloud Vault

1. Overview

In this tutorial, we’ll show how we can use Hashicorp’s Vault in Spring Boot applications to secure sensitive configuration data.

We assume here some Vault knowledge and that we have a test setup already up and running. If this isn’t the case, let’s take a moment to read our Vault Intro tutorial so we can get acquainted with its basics.

2. Spring Cloud Vault

Spring Cloud Vault is a relatively recent addition to the Spring Cloud stack that allows applications to access secrets stored in a Vault instance in a transparent way.

In general, migrating to Vault is a very simple process: just add the required libraries and add a few extra configuration properties to our project and we should be good to go. No code changes are required!

This is possible because it acts as a high priority PropertySource registered in the current Environment.

As such, Spring will use it whenever a property is required. Examples include DataSource properties, ConfigurationProperties, and so on.

3. Adding Spring Cloud Vault to a Spring Boot Project

In order to include the spring-cloud-vault library in a Maven-based Spring Boot project, we use the associated starter artifact, which will pull all required dependencies.

Besides the main starter, we’ll also include the spring-vault-config-databases, which adds support for dynamic database credentials:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-vault-config</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-vault-config-databases</artifactId>
</dependency>

The latest version of the Spring Cloud Vault starter can be downloaded from Maven Central.

3.1. Basic Configuration

In order to work properly, Spring Cloud Vault needs a way to determine where to contact the Vault server and how to authenticate itself against it.

We do this by providing the necessary information in the application.yml or application.properties:

spring:
  cloud:
    vault:
      uri: https://localhost:8200
      ssl:
        trust-store: classpath:/vault.jks
        trust-store-password: changeit
  config:
    import: vault:// 

The spring.cloud.vault.uri property points to Vault’s API address. Since our test environment uses HTTPS with a self-signed certificate, we also need to provide a keystore containing its public key. In case you face an error like ” “failed to verify certificate: x509: certificate relies on legacy Common Name field, use SANs instead” while importing the certificates, you can use the skip check option for certificate verification like below to get rid of the error:

vault read -tls-skip-verify  database/creds/fakebank-accounts-ro

Note that this configuration has no authentication data. For the simplest case, where we use a fixed token, we can pass it through the system property spring.cloud.vault.token or an environment variable. This approach works well in conjunction with standard cloud configuration mechanisms, such as Kubernetes’ ConfigMaps or Docker secrets.

Spring Vault also requires extra configuration for each type of secret that we want to use in our application. The following sections describe how we can add support to two common secret types: key/value and database credentials.

4. Using the Generic Secrets Backend

We use the Generic Secret backend to access unversioned secrets stored as Key-Value pairs in Vault.

Assuming we already have the spring-cloud-starter-vault-config dependency in our classpath, all we have to do is to add a few properties to the application.yml file:

spring:
  cloud:
    vault:
      # other vault properties omitted ...
      generic:
        enabled: true
        application-name: fakebank

The property application-name is optional in this case. If not specified, Spring will assume the value of the standard spring.application.name instead.

We now can use all key/value pairs stored at secret/fakebank as any other Environment property. The following snippet shows how we can read the value of the foo key stored under this path:

@Autowired Environment env;
public String getFoo() {
    return env.getProperty("foo");
}

As we can see, the code itself knows nothing about Vault, which is a good thing! We can still use fixed properties in local tests and switch to Vault as we please by just enabling a single property in the application.yml.

4.1. A Note on Spring Profiles

If available in the current Environment, Spring Cloud Vault will use the available profile names as a suffix appended to the specified base path where key/value pairs will be searched.

It will also look for properties under a configurable default application path (with and without a profile suffix) so we can have shared secrets in a single location. Use this feature with caution!

To summarize, if the production profile of out fakebank application is active, Spring Vault will look for properties stored under the following paths:

1. secret/fakebank/production (higher priority)
2. secret/fakebank
3. secret/application/production
4. secret/application (lower priority)

In the preceding list, application is the name that Spring uses as a default additional location for secrets. We can modify it using the spring.cloud.vault.generic.default-context property.

Properties stored under the most specific path will take precedence over the others. For instance, if the same property foo is available under paths above, then the precedence order would be:

5. Using the Database Secret Backend

The Database backend module allows Spring applications to use dynamically generated database credentials created by Vault. Spring Vault injects those credentials under the standard spring.datasource.username and spring.datasource.password properties so they can be picked by regular DataSources.

Please note that, before using this backend, we must create a database configuration and roles in Vault as described in our previous tutorial.

In order to use Vault generated database credentials in our Spring application, the spring-cloud-vault-config-databases must be present in the project’s classpath, along with the corresponding JDBC driver.

We also need to enable its use in our application by adding a few properties to our application.yml:

spring:
  cloud:
    vault:
      # ... other properties omitted
      database:
        enabled: true
        role: fakebank-accounts-rw

The most important property here is the role property, which holds a database role name stored in Vault. During startup, Spring will contact Vault and request that it creates new credentials with the corresponding privileges.

The vault will, by default, revoke the privileges associated with those credentials after the configured time-to-live.

Fortunately, Spring Vault will automatically renew the lease associated with the acquired credentials. By doing this, the credentials will stay valid as long our application is running.

Now, let´s see this integration in action. The following snippet gets a new database connection from a Spring-managed DataSource:

Connection c = datasource.getConnection();

Once again, we can see that there is no sign of Vault usage in our code. All integration happens at the Environment level, so our code can easily be unit-tested as usual.

6. Conclusion

In this tutorial, we’ve shown how to integrate Vault with Spring Boot using the Spring Vault library. We’ve covered two common use cases: generic key/value pairs and dynamic database credentials.