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

SSL

Spring Boot provides the ability to configure SSL trust material that can be applied to several types of connections in order to support secure communications. Configuration properties with the prefix spring.ssl.bundle can be used to specify named sets of trust material and associated information.

Configuring SSL With Java KeyStore Files

Configuration properties with the prefix spring.ssl.bundle.jks can be used to configure bundles of trust material created with the Java keytool utility and stored in Java KeyStore files in the JKS or PKCS12 format. Each bundle has a user-provided name that can be used to reference the bundle.

When used to secure an embedded web server, a keystore is typically configured with a Java KeyStore containing a certificate and private key as shown in this example:

  • Properties

  • YAML

spring.ssl.bundle.jks.mybundle.key.alias=application
spring.ssl.bundle.jks.mybundle.keystore.location=classpath:application.p12
spring.ssl.bundle.jks.mybundle.keystore.password=secret
spring.ssl.bundle.jks.mybundle.keystore.type=PKCS12
spring:
  ssl:
    bundle:
      jks:
        mybundle:
          key:
            alias: "application"
          keystore:
            location: "classpath:application.p12"
            password: "secret"
            type: "PKCS12"

When used to secure a client-side connection, a truststore is typically configured with a Java KeyStore containing the server certificate as shown in this example:

  • Properties

  • YAML

spring.ssl.bundle.jks.mybundle.truststore.location=classpath:server.p12
spring.ssl.bundle.jks.mybundle.truststore.password=secret
spring:
  ssl:
    bundle:
      jks:
        mybundle:
          truststore:
            location: "classpath:server.p12"
            password: "secret"

See JksSslBundleProperties for the full set of supported properties.

If you’re using environment variables to configure the bundle, the name of the bundle is always converted to lowercase.

Configuring SSL With PEM-encoded Certificates

Configuration properties with the prefix spring.ssl.bundle.pem can be used to configure bundles of trust material in the form of PEM-encoded text. Each bundle has a user-provided name that can be used to reference the bundle.

When used to secure an embedded web server, a keystore is typically configured with a certificate and private key as shown in this example:

  • Properties

  • YAML

spring.ssl.bundle.pem.mybundle.keystore.certificate=classpath:application.crt
spring.ssl.bundle.pem.mybundle.keystore.private-key=classpath:application.key
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          keystore:
            certificate: "classpath:application.crt"
            private-key: "classpath:application.key"

When used to secure a client-side connection, a truststore is typically configured with the server certificate as shown in this example:

  • Properties

  • YAML

spring.ssl.bundle.pem.mybundle.truststore.certificate=classpath:server.crt
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          truststore:
            certificate: "classpath:server.crt"

PEM content can be used directly for both the certificate and private-key properties. If the property values contain BEGIN and END markers then they will be treated as PEM content rather than a resource location.

The following example shows how a truststore certificate can be defined:

  • Properties

  • YAML

spring.ssl.bundle.pem.mybundle.truststore.certificate=-----BEGIN CERTIFICATE-----
MIID1zCCAr+gAwIBAgIUNM5QQv8IzVQsgSmmdPQNaqyzWs4wDQYJKoZIhvcNAQEL
BQAwezELMAkGA1UEBhMCWFgxEjAQBgNVBAgMCVN0YXRlTmFtZTERMA8GA1UEBwwI
...
V0IJjcmYjEZbTvpjFKznvaFiOUv+8L7jHQ1/Yf+9c3C8gSjdUfv88m17pqYXd+Ds
HEmfmNNjht130UyjNCITmLVXyy5p35vWmdf95U3uEbJSnNVtXH8qRmN9oK9mUpDb
ngX6JBJI7fw7tXoqWSLHNiBODM88fUlQSho8
-----END CERTIFICATE-----
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          truststore:
            certificate: |
              -----BEGIN CERTIFICATE-----
              MIID1zCCAr+gAwIBAgIUNM5QQv8IzVQsgSmmdPQNaqyzWs4wDQYJKoZIhvcNAQEL
              BQAwezELMAkGA1UEBhMCWFgxEjAQBgNVBAgMCVN0YXRlTmFtZTERMA8GA1UEBwwI
              ...
              V0IJjcmYjEZbTvpjFKznvaFiOUv+8L7jHQ1/Yf+9c3C8gSjdUfv88m17pqYXd+Ds
              HEmfmNNjht130UyjNCITmLVXyy5p35vWmdf95U3uEbJSnNVtXH8qRmN9oK9mUpDb
              ngX6JBJI7fw7tXoqWSLHNiBODM88fUlQSho8
              -----END CERTIFICATE-----

See PemSslBundleProperties for the full set of supported properties.

If you’re using environment variables to configure the bundle, the name of the bundle is always converted to lowercase.

Applying SSL Bundles

Once configured using properties, SSL bundles can be referred to by name in configuration properties for various types of connections that are auto-configured by Spring Boot. See the sections on embedded web servers, data technologies, and REST clients for further information.

Using SSL Bundles

Spring Boot auto-configures a bean of type SslBundles that provides access to each of the named bundles configured using the spring.ssl.bundle properties.

An SslBundle can be retrieved from the auto-configured SslBundles bean and used to create objects that are used to configure SSL connectivity in client libraries. The SslBundle provides a layered approach of obtaining these SSL objects:

In addition, the SslBundle provides details about the key being used, the protocol to use and any option that should be applied to the SSL engine.

The following example shows retrieving an SslBundle and using it to create an SSLContext:

  • Java

  • Kotlin

import javax.net.ssl.SSLContext;

import org.springframework.boot.ssl.SslBundle;
import org.springframework.boot.ssl.SslBundles;
import org.springframework.stereotype.Component;

@Component
public class MyComponent {

	public MyComponent(SslBundles sslBundles) {
		SslBundle sslBundle = sslBundles.getBundle("mybundle");
		SSLContext sslContext = sslBundle.createSslContext();
		// do something with the created sslContext
	}

}
import org.springframework.boot.ssl.SslBundles
import org.springframework.stereotype.Component

@Component
class MyComponent(sslBundles: SslBundles) {

    init {
        val sslBundle = sslBundles.getBundle("mybundle")
        val sslContext = sslBundle.createSslContext()
        // do something with the created sslContext
    }

}

Reloading SSL bundles

SSL bundles can be reloaded when the key material changes. The component consuming the bundle has to be compatible with reloadable SSL bundles. Currently the following components are compatible:

  • Tomcat web server

  • Netty web server

To enable reloading, you need to opt-in via a configuration property as shown in this example:

  • Properties

  • YAML

spring.ssl.bundle.pem.mybundle.reload-on-update=true
spring.ssl.bundle.pem.mybundle.keystore.certificate=file:/some/directory/application.crt
spring.ssl.bundle.pem.mybundle.keystore.private-key=file:/some/directory/application.key
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          reload-on-update: true
          keystore:
            certificate: "file:/some/directory/application.crt"
            private-key: "file:/some/directory/application.key"

A file watcher is then watching the files and if they change, the SSL bundle will be reloaded. This in turn triggers a reload in the consuming component, e.g. Tomcat rotates the certificates in the SSL enabled connectors.

You can configure the quiet period (to make sure that there are no more changes) of the file watcher with the spring.ssl.bundle.watch.file.quiet-period property.