Spring Vault 4.1 Release Notes

New and Noteworthy

• Introduction of VaultClient and ReactiveVaultClient

• ManagedSecret and ManagedCertificate abstractions

• CertificateContainer to leverage Vault’s certificate rotation and renewal capabilities

Third-party Library Upgrades

Spring Vault 4.1 builds on and requires Spring Framework 7.0.

Other Spring projects upgraded in this release include:

• Spring Data 2026.0

Numerous third-party dependencies have also been updated, some of the more noteworthy of which are the following:

• Reactor 2025.0.0

• Apache HTTP Client 5.5.1

• Apache HTTP Core 5.3.6

• Netty

Vault Client

Spring Vault’s HTTP client integration has evolved to address configuration and security concerns that emerged from the original implementation.

Background

Early versions of Spring Vault utilized RestTemplate for synchronous operations and WebClient for reactive applications. This approach required clients to be configured with an appropriate UriBuilderFactory to support relative path resolution across the Template API, Session Manager, and Client Authentication components.

A significant limitation arose when the same RestTemplate instance was shared between Vault operations and ClientAuthentication implementations that retrieved credentials from external services (such as metadata servers required for Vault authentication). This coupling prevented independent configuration of timeout values and SSL certificates for different service endpoints.

Security Considerations

The string-based path handling in VaultTemplate presented potential security risks. Methods that pass paths directly to the underlying HTTP client (read(), write(), delete(), and doInSession() client callbacks) could inadvertently send requests containing X-Vault-Token headers to non-Vault servers when paths were specified as absolute URIs. While applications should sanitize path inputs before passing them to VaultTemplate, the absence of simpler, built-in path validation meant that unintended external requests could occur without explicit detection.

New VaultClient API

Spring Vault now provides VaultClient and ReactiveVaultClient abstractions that adopt a design philosophy inspired by RestClient and WebClient, adapted specifically for Vault interactions. Key characteristics include:

• Path-based entry point: All operations require an explicit path() method call as the starting point

• Vault-aware response handling: Dedicated VaultResponse body() methods streamline response processing

• Separation of concerns: Distinct client instances can be configured for Vault operations versus external service requests

This dedicated client abstraction simplifies configuration management and enforces clearer boundaries between Vault API interactions and external HTTP requests, addressing both the configuration flexibility and security considerations identified in earlier implementations.

ManagedSecret API

The ManagedSecret API offers declarative secret lifecycle management. ManagedSecret is a higher-level abstraction that registers with SecretLeaseContainer and handles lease events on your behalf. As an implementation of SecretRegistrar, registrar beans are registered with the container before startup through AbstractVaultConfiguration.

@Configuration
class MyConfiguration {

  @Bean
  ManagedSecret mysqlCredentials(HikariDataSource dataSource) {
    return ManagedSecret.rotating("mysql/creds/my-role", secrets -> secrets.as(UsernamePassword::from)
          .applyTo((username, password) -> {
              connectionPool.setUsername(username);
              connectionPool.setPassword(password);
            }));
  }
}

CertificateContainer

CertificateContainer manages certificates issued by Vault’s PKI secrets engine. Certificates are typically not associated with a lease (in fact, avoiding leases is a performance optimization recommendation) and therefore, they do not require renewal, but they can be rotated when they expire. Certificate rotation is effectively a re-issuance.

// ideally, a bean
CertificateContainer container = new CertificateContainer(vaultOperations.opsForPki());
container.afterPropertiesSet();
container.start();


// later on, once CertificateContainer is active
RequestedCertificate cert = container
  .register(RequestedCertificate.trustAnchor("vault-ca"));

VaultCertificateRequest request = VaultCertificateRequest.builder()
            .commonName("www.example.com")
            .ttl(Duration.ofHours(12)).build();

ManagedCertificate managed = ManagedCertificate.issue("my-bundle", "my-role", request, bundle -> {
      bundles.register("my-bundle", bundle.createKeyStore("my-alias"));
   });

managed.register(container);