This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Vault 4.0.1!

Credentials Rotation

Vault’s comprehensive credential rotation allows for automatic renewal and rotation of secrets, such as database credentials. By binding secret validity to an application instance lifecycle, your applications maintain access to valid credentials without manual intervention. A compromised credential remains valid only for a limited time, with isolated impact to a single application instance.

When a secret carries a lease, Spring Vault renews that lease before expiration, keeping credentials valid throughout the application lifecycle.

The following sections cover the credential rotation infrastructure used by components such as Property Sources.

SecretLeaseContainer

SecretLeaseContainer manages the lifecycle of leased secrets. It renews leases before expiration and rotates credentials when necessary, listening for lease events and triggering appropriate actions.

As a Spring Lifecycle component, the container supports dynamic secret management during application runtime. It accepts RequestedSecret instances representing secrets under management.

Example 1. Setting up a SecretLeaseContainer
SecretLeaseContainer container = new SecretLeaseContainer(vaultOperations,       (1)
    taskScheduler);

RequestedSecret requestedSecret = container                                      (2)
    .requestRotatingSecret("mysql/creds/my-role");

container.addLeaseListener(new LeaseListenerAdapter() {                          (3)

  @Override
  public void onLeaseEvent(SecretLeaseEvent secretLeaseEvent) {
    if (requestedSecret.equals(secretLeaseEvent.getSource())) {
      if (secretLeaseEvent instanceof SecretLeaseCreatedEvent) {
        // …
      }
      if (secretLeaseEvent instanceof SecretLeaseExpiredEvent) {
        // …
      }
    }
  }
});
container.afterPropertiesSet();
container.start(); // events are triggered after starting the container
1 Initialize with VaultOperations and a TaskScheduler for renewal scheduling.
2 Request a rotating secret from a Vault path.
3 Register a LeaseListener for lease events. Registration order matters: Listeners added after container startup or secret requests may miss early events. Set up listeners before starting the container to capture all events.
A SecretLaseContainer is registered when your configuration class is a subclass of AbstractVaultConfiguration that is typically applicable for non-Spring Boot applications. When using Spring Boot, consider Spring Cloud Vault, which handles registration through auto-configuration.

Events

Regular Events

Error Events

Using SecretLeaseContainer directly with its listeners allows for fine-grained control over the lifecycle of secrets and handling of lease events. In typical application scenarios, you might want to use a higher-level abstraction that simplifies the management of secrets and their leases.

ManagedSecret and SecretRegistrar

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.

Example 2. Registering a ManagedSecret
@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);
            }));
  }
}

Managed Secrets allow a direct connection between the secret management and the application components that use the secrets making it easier to propagate credentials to the application components when secrets are requested or rotated. Note that the SecretLeaseContainers lifecycle nature typically defers the availability of secrets until the container is started and secrets are requested and that can be different from using components that require credentials during InitializingBean.afterPropertiesSet() or @PostConstruct phase. AbstractVaultConfiguration deliberately starts the container already during the bean creation to allow for early credentials access. You should in any case ensure dependency ordering of your components to ensure proper initialization and availability of secrets when needed.

TTL Tuning

Lease renewal and rotation are subject to TTL (Time To Live) and therefore directly related to timing. SecretLeaseContainer uses an expiry threshold (default 1 minute) to determine whether a lease is considered expired. The minimum renewal TTL (default 10 seconds) prevents excessive renewal requests in short succession. Renewal and rotation times are calculated based on lease TTL duration and the local system clock (specifically TaskScheduler clock).

You can configure a custom expiry Predicate<Lease> function for lease expiration determination.

Token Renewal and Session Management

Vault revokes leases associated with a session token when that token expires or is revoked. When your Vault session expires (hitting Max TTL), any leases issued within that session are also revoked. SessionLeaseContainer provides an AuthenticationListener through getAuthenticationListener() and getAuthenticationErrorListener() for registration with your SessionManager, allowing secret restart after successful re-login.

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.

Vault PKI serves several certificate types:

  • X.509 Certificate Bundles

    • TLS encryption

    • Client authentication

  • X.509 Certificates

    • Trust Anchors

The container is a Spring Lifecycle component that can be started and stopped, allowing for dynamic management of certificates during application runtime. It accepts RequestedCertificate instances, which represent the certificate that need to be managed. The following code example shows how to set up a CertificateContainer and listen for events:

Example 3. Setting up a CertificateContainer
CertificateContainer container = new CertificateContainer(vaultOperations.opsForPki());  (1)

RequestedCertificate cert = container
  .register(RequestedCertificate.trustAnchor("vault-ca"));                               (2)

RequestedCertificate bundle = RequestedCertificateBundle.issue("www.example.com",        (3)
      "testrole", VaultCertificateRequest.builder()
              .commonName("www.example.com")
              .ttl(Duration.ofHours(12)).build());

container.addCertificateListener(new CertificateListenerAdapter() {                      (4)
  @Override
  public void onCertificateEvent(CertificateEvent event) {
    if (cert.equals(event.getSource())) {
      if (event instanceof CertificateBundleIssuedEvent) {
        // Certificate bundle issued initially or rotated
      }
      if (event instanceof CertificateObtainedEvent) {
        // initial certificate obtained
      }
    }
  }
});

container.afterPropertiesSet();
container.start(); // events are triggered after starting the container
1 Initialize with VaultPkiOperations. Without a provided TaskScheduler, the container creates a default instance.
2 Request an issuer certificate through RequestedCertificate (Supports default or named issuers).
3 Request a managed certificate bundle through RequestedCertificateBundle with a certificate request.
4 Register a CertificateListener for certificate events. Registration order matters: listeners added after container startup or certificate requests may miss early events. Set up listeners before starting the container to capture all events.
A CertificateContainer is registered when your configuration class is a subclass of AbstractVaultConfiguration that is typically applicable for non-Spring Boot applications. When using Spring Boot, cconsider Spring Cloud Vault, which handles registration through auto-configuration.

Events

Regular Events

Error Events

Using CertificateContainer directly with its listeners allows for fine-grained control over the lifecycle of certificates and handling of events. In typical application scenarios, you might want to use a higher-level abstraction that simplifies the management of certificates.

ManagedCertificate and CertificateRegistrar

The ManagedCertificate API offers declarative certificate lifecycle management. ManagedCertificate is a higher-level abstraction that registers with CertificateContainer and handles certificate events on your behalf. It is an implementation of CertificateRegistrar. Registrar beans are detected by AbstractVaultConfiguration and registered with the CertificateContainer before container startup.

Example 4. Registering a ManagedCertificate
@Configuration
class MyConfiguration {

  @Bean
  ManagedCertificate serverCertificate(SslBundles bundles) {
    VaultCertificateRequest request = VaultCertificateRequest.builder()
            .commonName("www.example.com")
            .ttl(Duration.ofHours(12)).build();
    return ManagedCertificate.issue("my-bundle", "my-role", request, bundle -> {
      bundles.register("my-bundle", bundle.createKeyStore("my-alias"));
   });
  }
}

Managed Certificates allow a direct connection between the certificate management and the application components that use the certificates making it easier to propagate credentials to the application components. Note that the CertificateContainer lifecycle nature typically defers the availability of certificates until the container is started and certificates are requested and that can be different from using components that require credentials during InitializingBean.afterPropertiesSet() or @PostConstruct phase. AbstractVaultConfiguration deliberately starts the container already during the bean creation to allow for early certificate access. You should in any case ensure dependency ordering of your components to ensure proper initialization and availability of certificates when needed.