How to enable HTTPS in a Spring Boot Java application

Setting up HTTPS for Spring Boot is very easy, all you need to do is performing   the following operations:

  1. Generate a key-pair using the RSA algorithm;
  2. Generate an X.509 certificate using the keys from the previous step;
  3. Import the certificate inside the JRE archive for certificates;
  4. Set up Spring Boot to enable HTTPS.

To perform the previous operations I’ll use these technologies and tools:

  • Java JDK 8 (1.8.0_72)
  • Spring Boot 1.5.3.RELEASE
  • keytool

The last tool is provided together with the JDK, so if you have the JDK installed  you have keytoolalready available. To check it, try running the command keytool --versionfrom your Terminal prompt. Note that if you are on Windows, you might need to launch it from the \bin folder. For more information about it, you can read the official documentation.

The approach described in this tutorial is just for development and testing purposes. Please, do not use it in a production environment!

1. Generate a key-pair using the RSA algorithm

First of all you need to generate a key-pair. Open your Terminal prompt and write the following command:

keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -keystore keystore.jks -validity 3650

You then will be asked to input several information (you are free to skip the most of it).

Enter keystore password:  
Re-enter new password: 
What is your first and last name?
  [Unknown]:  localhost
What is the name of your organizational unit?
  [Unknown]:  
What is the name of your organization?
  [Unknown]:  
What is the name of your City or Locality?
  [Unknown]:  
What is the name of your State or Province?
  [Unknown]:  
What is the two-letter country code for this unit?
  [Unknown]:  
Is CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
  [no]:  yes

Enter key password for <tomcat>
  (RETURN if same as keystore password):

In the place of first and last name you should insert the base name of your host (in my case it is localhost). Hit Return to skip an option.

2. Generate an X.509 certificate

Now that we have a pair of private and public keys, we are ready to generate an X.509 certificate. In your Terminal prompt write the following:

keytool -export -keystore keystore.jks -alias tomcat -file myCertificate.crt

To execute this command you will be asked for the keystore password. If you have never changed it, it is the default one: changeit or changeme, depending on the operating system.

3. Import the certificate inside the JRE archive for certificates

Before configuring Spring Boot in order to enable https, we still need to import the certificate inside cacerts: the JRE folder to hold certificates.

To do that, you’ll need to know the path to your JDK home. A quick way to find it, if you are using Eclipse or STS as your IDE, is by going to Preferences > Java > Installed JREs. Here you can read information about your JDK location. For example, on a Mac it could be something like /Library/Java/JavaVirtualMachines/jdk1.8.0_72.jdk/Contents/Home. In the following we’ll refer to this location by using the placeholder $JDK_HOME.

From your Terminal prompt insert the following command (you might need to run it with administrator privileges by prefixing it with sudo):

keytool -importcert -file myCertificate.crt -alias tomcat -keystore $JDK_HOME/jre/lib/security/cacerts

You’ll be asked to input the keystore password as in the previous step. Finally you’ll asked if you want to trust this certificate: say yes.

If everything went right, you’ll see the message Certificate was added to keystore.

4. Enable HTTPS in Spring Boot

Finally, we can set up Spring Boot to accept requests over HTTPS instead of HTTP, by using the certificate that we have just generated and configured.

All you need to do is open up your application.properties file (it works the same also on application.yaml) and define the following properties:

# Define a custom port instead of the default 8080
server.port = 8089
# Tell Spring Security to require requests over HTTPS
security.require-ssl=true
# The keystore containing the certificate keys
server.ssl.key-store=keystore.jks
# The password used to generate the keys
server.ssl.key-store-password=password
# The alias mapped to the certificate
server.ssl.keyAlias=tomcat

You can define a custom port using the server.port property (by default it is 8080). If your project is using Spring Security, you should set the security.require-ssl property to true in order to automatically block any requests coming over http, without explicitly touching your Spring Security configuration class.

Note that keystore.jks file defined as value of server.ssl.key-store is the same file generated during the step 1. The last thing you need to do is copying that file inside the root folder of the Spring Boot project in order to automatically make it available in the classpath.

Conclusion

In this tutorial we have seen how to generate an X.509 certificate and how to use it to enable HTTPS inside a Spring Boot application.

If your application is deployed on your localhost, you may need to do a further step from your browser: enabling insecure connections with localhost. In Chrome, you do that by writing the following url in the search bar: chrome://flags/#allow-insecure-localhost and enabling the relative option.

Leave a Reply

Your email address will not be published. Required fields are marked *