TLS Setup in Spring

1. Overview

Secure communication plays an important role in modern applications. Communication between client and server over plain HTTP is not secure. For a production-ready application, we should enable HTTPS via the TLS (Transport Layer Security) protocol in our application. In this tutorial, we'll discuss how to enable TLS technology in a Spring Boot application.

2. TLS Protocol

TLS provides protection for data in transit between client and server and is a key component of the HTTPS protocol. The Secure Sockets Layer (SSL) and TLS are often used interchangeably, but they aren’t the same. In fact, TLS is the successor of SSL. TLS can be implemented either one-way or two-way.

2.1. One-Way TLS

In one-way TLS, only the client verifies the server to ensure that it receives data from the trusted server. For implementing one-way TLS, the server shares its public certificate with the clients.

2.2. Two-Way TLS

In two-way TLS or Mutual TLS (mTLS), both the client and server authenticate each other to ensure that both parties involved in the communication are trusted. For implementing mTLS, both parties share their public certificates with each other.

3. Configuring TLS in Spring Boot

3.1. Generating a Key Pair

To enable TLS, we need to create a public/private key pair. For this, we use keytool. The keytool command comes with the default Java distribution. Let's use keytool to generate a key pair and store it in the keystore.p12 file:

keytool -genkeypair -alias baeldung -keyalg RSA -keysize 4096 \
  -validity 3650 -dname "CN=localhost" -keypass changeit -keystore keystore.p12 \
  -storeType PKCS12 -storepass changeit

The keystore file can be in different formats. The two most popular formats are Java KeyStore (JKS) and PKCS#12. JKS is specific to Java, while PKCS#12 is an industry-standard format belonging to the family of standards defined under Public Key Cryptography Standards (PKCS).

3.2. Configuring TLS in Spring

Let's start by configuring one-way TLS. We configure the TLS related properties in the application.properties file:

# enable/disable https
server.ssl.enabled=true
# keystore format
server.ssl.key-store-type=PKCS12
# keystore location
server.ssl.key-store=classpath:keystore/keystore.p12
# keystore password
server.ssl.key-store-password=changeit

When configuring the SSL protocol, we'll use TLS and tell the server to use TLS 1.2:

# SSL protocol to use
server.ssl.protocol=TLS
# Enabled SSL protocols
server.ssl.enabled-protocols=TLSv1.2

To validate that everything works fine, we just need to run the Spring Boot application:

3.3. Configuring mTLS in Spring

For enabling mTLS, we use the client-auth attribute with the need value:

server.ssl.client-auth=need

When we use the need value, client authentication is needed and mandatory. This means that both the client and server must share their public certificate. For storing the client's certificate in the Spring Boot application, we use the truststore file and configure it in the application.properties file:

#trust store location
server.ssl.trust-store=classpath:keystore/truststore.p12
#trust store password
server.ssl.trust-store-password=changeit

The path for the location to the truststore is the file that contains the list of certificate authorities that are trusted by the machine for SSL server authentication. The truststore password is the password to gain access to the truststore file.

4. Configuring TLS in Tomcat

By default, the HTTP protocol without any TLS capabilities is used when Tomcat is started. For enabling TLS in Tomcat, we config the server.xml file:

<Connector
  protocol="org.apache.coyote.http11.Http11NioProtocol"
  port="8443" maxThreads="200"
  scheme="https" secure="true" SSLEnabled="true"
  keystoreFile="${user.home}/.keystore" keystorePass="changeit"
  clientAuth="false" sslProtocol="TLS" sslEnabledProtocols="TLSv1.2"/>

For enabling mTLS, we'll set clientAuth=”true”.

5. Invoking an HTTPS API

For invoking the REST API, we'll use the curl tool:

curl -v http://localhost:8443/baeldung

Since we didn't specify https, it will output an error:

Bad Request
This combination of host and port requires TLS.

This issue is solved by using the https protocol:

curl -v https://localhost:8443/baeldung

However, this gives us another error:

SSL certificate problem: self signed certificate

This happens when we're using a self-signed certificate. To fix this, we must use the server certificate in the client request. First, we'll copy the server certificate baeldung.cer from the server keystore file. Then we'll use the server certificate in the curl request along with the –cacert option:

curl --cacert baeldung.cer https://localhost:8443/baeldung

6. Conclusion

For ensuring the security of the data being transferred between a client and server, TLS can be implemented either one-way or two-way. In this article, we describe how to configure TLS in a Spring Boot application in the application.properties file and in the Tomcat configuration file. As usual, all code samples used in this tutorial are available over on GitHub.