v8 v7 v6 v5 v4 v3
Edit Page

Configure TLS

Introduction

This section provides instructions on how to enable Transport Layer Security so that requests can be served over the HTTPS protocol.

Warning
 HTTP is not secure: credentials can be sniffed by a man-in-the-middle attack. It is paramount to use HTTPS
Note
 This section is about securing HTTP requests between Clients and RESTHeart. Read Secure connection to MongoDB for more information on how to secure the connection between RESTHeart and MongoDB.

The HTTPS listener

There are many ways of enabling HTTS; for instance you can setup a web server such as nginx as a reverse proxy in front of RESTHeart or you may rely on cloud services that provides load balancers that manages SSL for you (such are Amazon WS or Google Cloud).

In any case, restheart is able to expose directly the HTTS protocol and this is done configuring the https listener. This is the suggested configuration for small systems.

The following configuration file except shows the involved options:

https-listener:
    enabled: true
    host: 0.0.0.0
    port: 4443
    keystore-path: /path/to/keystore/file
    keystore-password: secret
    certificate-password: secret

Example:

$ http -d https://raw.githubusercontent.com/SoftInstigate/restheart/master/core/bin/generate-certauthority-and-keystore.sh # download the script generate-certauthority-and-keystore.sh
$ ./generate-certauthority-and-keystore.sh -d localhost -a /tmp -p secret # generate a test keystore and certificate authority
$ RHO='/https-listener->{ "enabled": true, "host": "localhost", "port": 4443, "keystore-path": "/tmp/localhost.jks", "keystore-password": "secret", "certificate-password": "secret" }' java -jar restheart.jar # run RESTHeart with TLS enabled
$ http -b --verify /tmp/devCA.pem https://restheart.local:4443/ping # execute a test TLS request
Greetings from RESTHeart!

To enable https configure the https listener using the following options:

  1. /https-listener/enabled true to enable it

  2. /https-listener/host the ip where to bind the listener

  3. /https-listener/port the port where to bind the listener

  4. /https-listener/keystore-path the path of the keystore

  5. /https-listener/keystore-password the password of the keystore

  6. /https-listener/certificate-password the password of the certificate

A SSL certificate must configured in order to enable the https listener.

Configure the SSL certificate

The SSL certificate must be added to the java keystore set by the keystore-file configuration property.

Two scripts are available to help configuring the keystore.

generate-certauthority-and-keystore.sh

This is useful for testing purposes. It generates a CA and uses it to issue a SSL certificate, finally generating the keystore file.

Download the script from generate-certauthority-and-keystore.sh

After having generated the keystore file and configured RESTHeart to use it, you need to install the CA root certificate into your OS.

For example, in OSX:

  1. Open up Keychain Access application by searching it on Spotlight

  2. Select File > Import Items. Navigate to CA root certificate file generated by the script. Select System as "Destination Keychain".

  3. Right click on the certificate in Keychain Access and select Get Info

    • Expand the Trust section

    • Under When using this certificate select Always Trust.

convert-letsencrypt-java-keystore.sh

Let’s Encrypt is a popular and nonprofit Certificate Authority providing free TLS certificates.

This script generates the java keystore from Let’s Encrypt certificate archive.

Download the script from convert-letsencrypt-java-keystore.sh

I’ll improve the documentation section with better structure, clearer instructions, and more helpful guidance:

Example: Generating SSL Certificates with Lego

Lego is a robust Let’s Encrypt client and ACME library written in Go that simplifies the process of generating SSL certificates through various verification methods.

This example demonstrates using Lego with the DNS route53 provider, assuming AWS credentials are already configured in your environment. The process can be adapted to use any of the supported DNS providers.

Step 1: Generate the Certificate

Replace restheart.org with your domain name throughout these examples.

$ lego --email andrea@restheart.org --dns route53 -d restheart.org run
2025/03/26 09:49:44 [INFO] [restheart.org] acme: Obtaining bundled SAN certificate
2025/03/26 09:49:45 [INFO] [restheart.org] AuthURL: https://acme-v02.api.letsencrypt.org/acme/authz/2302497476/495306646876
2025/03/26 09:49:45 [INFO] [restheart.org] acme: authorization already valid; skipping challenge
2025/03/26 09:49:45 [INFO] [restheart.org] acme: Validations succeeded; requesting certificates
2025/03/26 09:49:46 [INFO] [restheart.org] Server responded with a certificate

$ ls .lego/certificates
restheart.org.crt        restheart.org.issuer.crt restheart.org.json       restheart.org.key

After execution, Lego creates the certificate files in the .lego/certificates directory.

Step 2: Convert Certificates to Java Keystore

Use the provided script to convert the Let’s Encrypt certificates into a Java keystore format:

./convert-letsencrypt-java-keystore.sh \
  -d restheart.org \
  -c .lego/certificates/restheart.org.crt \
  -k .lego/certificates/restheart.org.key \
  -i .lego/certificates/restheart.org.issuer.crt \
  -p secret

Output:

Convert Let's Encrypt certificates to PKCS 12 archive
Import certificates into a keystore file.
Keystore import .lego/certificates/restheart.org.p12 in .lego/certificates/restheart.org.jks in corso...
Add the necessary Let's Encrypt intermediate certs.
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1826  100  1826    0     0  13977      0 --:--:-- --:--:-- --:--:-- 14046
The certificate has been added to the keystore

This creates a Java keystore file at .lego/certificates/restheart.org.jks with the password secret.

Step 3: Configure RESTHeart with HTTPS

Run RESTHeart with the HTTPS listener enabled using the generated keystore:

$ RHO='/https-listener->{
  "enabled": true,
  "host": "restheart.org",
  "port": 4443,
  "keystore-path": ".lego/certificates/restheart.org.jks",
  "keystore-password": "secret",
  "certificate-password": "secret"
}' java -jar restheart.jar
Tip

For production use, choose a strong password instead of "secret" and secure your keystore file with appropriate permissions.