Securing Spring Boot Apps with SSL Bundles: A Practical Guide

If you've ever had to configure SSL/TLS in a Spring Boot app the old way—scattering server.ssl.key-store, server.ssl.key-password, server.ssl.trust-store across application.properties—you know the pain. It's error-prone, hard to maintain, and a nightmare when certificates expire. I've debugged countless production incidents where a misconfigured truststore brought down an entire microservice mesh.

Spring Boot 3.1 introduced SSL Bundles, a game-changer for TLS configuration. Instead of juggling half a dozen properties per connector, you define a named bundle once and reference it everywhere: embedded server, HTTP clients, messaging, whatever. It's cleaner, more consistent, and supports hot-reload of certificates.

This guide walks you through setting up SSL Bundles with real-world examples, common pitfalls, and a production debugging guide. By the end, you'll never go back to the old way.

What Are SSL Bundles?

SSL Bundles, introduced in Spring Boot 3.1, let you define TLS/SSL configuration in a centralized, reusable way. Instead of scattering keystore and truststore properties across your application, you create a named bundle in application.properties or application.yml and reference it wherever needed—embedded server, WebClient, RestTemplate, or messaging connectors.

You can define multiple bundles for different purposes: one for server-side TLS, another for outgoing HTTP calls, yet another for database connections. The bundle abstraction handles reloading when files change, so you can rotate certificates without restarting the JVM.

Here's the minimal setup for a server-side bundle using PKCS12 files:

spring:
  ssl:
    bundle:
      jks:
        server:
          keystore:
            location: classpath:server-keystore.p12
            password: secret
            type: PKCS12
          truststore:
            location: classpath:truststore.p12
            password: secret
            type: PKCS12
server:
  ssl:
    bundle: server

Configuring SSL Bundles for the Embedded Server

The most common use case is securing your embedded Tomcat, Jetty, or Undertow server. With SSL Bundles, it's a two-step process: define the bundle, then reference it in server.ssl.bundle.

Let's create a bundle named server that uses a PKCS12 keystore and a separate truststore:

spring:
  ssl:
    bundle:
      jks:
        server:
          keystore:
            location: file:/etc/ssl/server-keystore.p12
            password: ${KEYSTORE_PASSWORD}
            type: PKCS12
          truststore:
            location: file:/etc/ssl/truststore.p12
            password: ${TRUSTSTORE_PASSWORD}
            type: PKCS12
server:
  ssl:
    bundle: server
  port: 8443

Using SSL Bundles with WebClient and RestTemplate

Outgoing HTTPS calls also benefit from bundles. Instead of configuring SSLContext manually, you can inject a WebClient or RestTemplate that uses a bundle.

First, define a bundle for client-side TLS (often the same truststore but different keystore if mutual TLS is needed):

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.netty.http.client.HttpClient;
import io.netty.handler.ssl.SslContext;
import org.springframework.boot.ssl.SslBundles;

@Configuration
public class WebClientConfig {

    @Bean
    public WebClient webClient(SslBundles sslBundles) {
        SslContext sslContext = sslBundles.getBundle("client")
                .createSslContext();
        HttpClient httpClient = HttpClient.create()
                .secure(sslContextSpec -> sslContextSpec.sslContext(sslContext));
        return WebClient.builder()
                .clientConnector(new ReactorClientHttpConnector(httpClient))
                .build();
    }
}

Hot-Reloading Certificates with Reloadable Bundles

One of the killer features of SSL Bundles is the ability to reload certificates without restarting the JVM. This is critical for zero-downtime certificate rotation.

To enable reloading, use the reloadable bundle type and set spring.ssl.bundle.reload-on-update=true. Then, you can trigger a reload by calling the Actuator endpoint POST /actuator/ssl or by updating the bundle files.

Example configuration:

spring:
  ssl:
    bundle:
      reloadable:
        server:
          keystore:
            location: file:/etc/ssl/server-keystore.p12
            password: ${KEYSTORE_PASSWORD}
          truststore:
            location: file:/etc/ssl/truststore.p12
            password: ${TRUSTSTORE_PASSWORD}
    reload-on-update: true
management:
  endpoint:
    ssl:
      enabled: true
  endpoints:
    web:
      exposure:
        include: ssl

What the Official Docs Won't Tell You

After deploying SSL Bundles across dozens of microservices, here are the gotchas that bit us:

1. Bundle names are case-sensitive and must match exactly. We once had server in properties but referenced Server in code—silent fallback to no SSL, and the app started on HTTP. No error, just no HTTPS.

2. The reloadable bundle type only supports PKCS12, not JKS. If you use JKS, you can't hot-reload. The docs mention this, but it's easy to miss. Convert to PKCS12 with keytool -importkeystore -srckeystore old.jks -destkeystore new.p12 -deststoretype PKCS12.

3. PEM bundles require the private key to be unencrypted. If your PEM key has a password, Spring Boot will fail to load it. Use openssl rsa -in encrypted.key -out decrypted.key to remove the password (but secure the file accordingly).

4. Truststore reload doesn't affect already-established connections. Only new connections will use the updated truststore. For long-lived connections (like database pools), you may need to restart the pool or the app.

5. The Actuator SSL endpoint only shows bundles after they've been loaded. If the bundle fails to load (e.g., wrong password), the endpoint returns an empty list. Check logs for SslBundleException.

6. Multiple bundles can't share the same keystore/truststore file if they require different reload triggers. Each bundle has its own file watcher. If two bundles point to the same file, only one watcher will fire. Use separate files or trigger reloads manually.

Migrating from Legacy SSL Properties

If you're already using server.ssl.key-store and friends, migration is straightforward but requires care. The old properties are deprecated in Spring Boot 3.1 and will be removed in a future version.

Steps: 1. Define a bundle with the same keystore/truststore settings. 2. Replace server.ssl.key-store etc. with server.ssl.bundle. 3. Remove all legacy server.ssl.* properties. 4. Test thoroughly—especially if you have multiple connectors (e.g., HTTP/2).

Here's a before/after example:

# Before (legacy)
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-password=secret
server.ssl.key-store-type=PKCS12
server.ssl.trust-store=classpath:truststore.p12
server.ssl.trust-store-password=secret
server.ssl.trust-store-type=PKCS12
server.ssl.enabled=true

# After (bundle)
spring.ssl.bundle.jks.server.keystore.location=classpath:keystore.p12
spring.ssl.bundle.jks.server.keystore.password=secret
spring.ssl.bundle.jks.server.keystore.type=PKCS12
spring.ssl.bundle.jks.server.truststore.location=classpath:truststore.p12
spring.ssl.bundle.jks.server.truststore.password=secret
spring.ssl.bundle.jks.server.truststore.type=PKCS12
server.ssl.bundle=server

Testing SSL Bundle Configuration

Don't wait for production to discover your SSL config is broken. Write integration tests that verify bundles load correctly.

Spring Boot provides @SpringBootTest with auto-configured SslBundles. You can inject it and assert on bundle details:

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.ssl.SslBundles;
import org.springframework.boot.ssl.SslBundle;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest
class SslBundleTest {

    @Autowired
    private SslBundles sslBundles;

    @Test
    void serverBundleShouldBeLoaded() {
        SslBundle bundle = sslBundles.getBundle("server");
        assertThat(bundle).isNotNull();
        assertThat(bundle.getKeyStore()).isNotNull();
        assertThat(bundle.getTrustStore()).isNotNull();
    }

    @Test
    void clientBundleShouldHaveTruststoreOnly() {
        SslBundle bundle = sslBundles.getBundle("client");
        assertThat(bundle).isNotNull();
        assertThat(bundle.getKeyStore()).isNull(); // no keystore
        assertThat(bundle.getTrustStore()).isNotNull();
    }
}