Configuring HTTPS for the Gateway

Owned by Team Kolibri (Unlicensed)
Last updated: Oct 22, 2024 by Mr. Schmittberger
5 min read

This page describes how to configure the gateway (versions 3.x and 4.x) for encrypted communication in client applications such as a web browser, using a server-side certificate. Note that yuuvis® RAD agent cannot be used with a combination of a self-signed certificate and NTLM authentication. For productive systems, we recommend using CA-signed certificates with NTLM authentication.

Configuring yuuvis® RAD gateway

You can configure the following gateway parameters in the services\config\gateway-prod.yml directory.

Creating a Certificate with OpenSSL

You can use the free OpenSSL software to create a certificate.

After installing OpenSSL, execute the following commands to create a certificate. The first two commands define the certificate password as well as its parameters. You can customize these.

set pass=pass:optimal
set caSubj=/C=DE/ST=DE-DE/L=Berlin/CN=<hostname/dns-name> # replace <hostname/dns-name> with your hostname or desired dns-name

openssl genrsa -des3 -passout %pass% -out ca.key 4096
openssl req -new -x509 -days 365 -key ca.key -out ca.crt -subj %caSubj% -passin %pass%
openssl pkcs12 -inkey ca.key -in ca.crt -export -out ca.p12 -passin %pass% -passout %pass%

set pass=pass:optimal
set caSubj=/C=DE/ST=DE-DE/L=Berlin/CN=<hostname/dns-name> # replace <hostname/dns-name> with your hostname or desired dns-name

openssl genrsa -des3 -passout %pass% -out ca.key 4096
openssl req -new -x509 -days 365 -key ca.key -out ca.crt -subj %caSubj% -passin %pass%
openssl pkcs12 -inkey ca.key -in ca.crt -export -out ca.p12 -passin %pass% -passout %pass%

These commands create the files ca.crt, ca.key and ca.p12. The ca.p12 file is the certificate you will install in the gateway.

To Configure SSL, Follow these Steps

  1. Copy the certificate file into [service-manager]\certificates.

  2. Find the yuuvis® RAD gateway configuration section in the [service-manager]\config\servicewatcher-sw.yml file (search for "gateway"), and change the port from 80 to 443.

  3. Add the following lines to the [service-manager]\config\gateway-prod.yml file.

    server.ssl.key-store: '../../certificates/ca.p12' server.ssl.key-store-password: 'optimal' server.ssl.key-store-type: 'PKCS12' server.ssl.key-alias: '1' server.ssl.key-password: 'optimal' server.ssl.enabled-protocols: 'TLSv1.2,TLSv1.3' eureka.instance: prefer-ip-address: false non-secure-port-enabled: false secure-port-enabled: true secure-port: ${server.port} statusPageUrl: https://${eureka.instance.hostname}:${eureka.instance.secure-port}/manage/info healthCheckUrl: https://${eureka.instance.hostname}:${eureka.instance.secure-port}/manage/health secureHealthCheckUrl: https://${eureka.instance.hostname}:${eureka.instance.secure-port}/manage/health homePageUrl: https://${eureka.instance.hostname}:${eureka.instance.secure-port}/ hostname: <hostname/dns-name>

    Modify the settings to match those of the certificate you installed: 
    If the certificate is issued to a DNS alias of the server, then the gateway needs to bind against this alias as well and publish URLs that can be called by other services with this alias address. This includes the eureka.instance.hostname URL shown above. The same applies if your certificate is issued to the hostname of the server. In this case, the gateway needs to bind to the hostname. As a consequence, the eureka.instance.preferIpAddress parameter needs to be added and set to false.
    If desired, the passwords can be saved encrypted. To do so, execute "<service-manager>\tools\encode.bat <plaintext_password>" (omit the < >) in a command prompt (cmd.exe) and copy the return value (including the ENC( )) to the configuration file (replacing the plaintext password).
    If a custom context-path is configured, the line 'secure-port: ${server.port}' needs to be changed to 'secure-port: ${management.server.port}'

  4. Restart the yuuvis® RAD service-manager service.

Using a Self-Signed Certificate

Attention

The use of a self-signed certificate is only intended for development and testing purposes. For productive systems, we recommend the use of a certificate signed by a trusted certificate authority (CA).

Self-signed certificates are not considered trusted by Java. This is why the Java runtime might show error messages or refuse to work.
If, for example, a service such as the admin-service wants to call another service such as the gateway-service, which is configured to run SSL encrypted and with a self-signed certificate, then the admin-service will get a message from the Java runtime about the called service (gateway) running with an untrusted self-signed certificate. The call will be aborted and the admin-service has to assume that the gateway-service is not reachable.
To solve this problem on development and testing systems, the self-signed certificate of the called service (gateway) has to be imported in the Java runtime that runs the calling service (admin).
The following link shows how to do that: https://www.thomasvitale.com/https-spring-boot-ssl-certificate/

Configuring the viewer-service to accept self-signed certificates

If the gateway uses a self-signed certificate (SSL/HTTPS) the viewer-service must be configured to accept this certificate. To do this, follow the below steps:

  • Use the ca.crt file that was also created during the certificate creation

    • If you don’t have the ca.crt file (anymore), follow these steps to extract the public certificate in .cer file format from the existing .p12 certificate - either by using OpenSSL on the command line or by using the Keystore Explorer (with GUI) 

      • Command line:

        openssl pkcs12 -in yuuvis.p12 -clcerts -nokeys -out yuuvis.cer

        (replace yuuvis with the name of your certificate)

      • Keystore Explorer:

        • Open the .p12 certificate in the Keystore Explorer

        • Double click on the certificate entry to open the details of the certifcate

        • Click on the Export button at the bottom left.

        • Change the path of the export file to <service-manager>\certificates (create the folder if it doesn’t exist)

        • Click ok to export the .cer file

    • Open the file <service-manager>\config\servicewatcher-sw.yml

    • Navigate to the viewer-service section and add the following parameter at the bottom

      (replace yuuvis with the name or your certificate)

  • It should now look like this:

Calling the Services in the Browser

After having configured the gateway, call the services using the HTTPS schema, for example, https://<hostname/dns-name>/client/index.html. In case you created the certificates yourself, the browser lets the user decide whether or not the certificate is trustworthy.

Recommendation

Browsers usually do not support operating secured and unsecured URLs for a domain in parellel. It is therefore recommended that you set up different domains for http and https.

Notes:

  • If only one domain is used for both URLs during the test phase, the Site Data can be reset so that logging in via the other URL works again.

  • Use the URL https://gateway/rest-ws/ to access the REST API. Make sure to enter the trailing '/.'

Weblinks