This section provides instructions on how to enable Transport Layer Security so that requests can be served over the HTTPS protocol.
HTTP is not secure: credentials can be sniffed by a man-in-the-middle attack. It is paramount to use HTTPS
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:
#### listeners https-listener: true https-host: 0.0.0.0 https-port: 4443 #### SSL configuration keystore-file: /path/to/keystore/file keystore-password: secret certpassword: secret
To enable https configure the https listener using the following options:
- https-listener true to enable it
- https-host the ip where to bind the listener
- https-port the port where to bind the listener:
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.
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:
- Open up
Keychain Accessapplication by searching it on
File > Import Items. Navigate to CA root certificate file generated by the script. Select
Systemas “Destination Keychain”.
- Right click on the certificate in Keychain Access and select
- Expand the Trust section
- Under When using this certificate select
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