How to setup configuration GUI endpoint to use https.

In production envirornment communication between ogamma Visual Logger’s web server which is used to provide configuration GUI, and web browsers must be secured (that is https protocol should be used).

To setup secured communication, first of all you will need a SSL certificate. In general, one of properties of a certificate is that it should have either host name or IP address where the web server is running, which must match with host name or IP address used by browsers to connect to the web server. Another requirement is that the issuer of the certificate (Certificate Authority) must be trusted by the web browser. In corporate environment usually there is internal certificates management system which can issue such a certificate. If you do not have existing certificates management system, then certificate can be generated using various tools, like openSSL command line utility, or XCA (https://hohnstaedt.de/xca/). But in this case browsers need to be configured to trust issuer certificate.

Next section describes steps how to generate SSL certificate using online tool at https://www.sslforfree.com/. Main advantage of using this tool is that the resulting certificate is generated using well known service Let's Encrypt (https://letsencrypt.org/). Therefore that certificate will be accepted by almost any web browser immediately without any additional configuration of trust, because the root CA certificate is pre-installed and trusted by majority of PCs.

How to generate and install SSL certificate issued by Let’s Encrypt.

In order to get a certificate from Let's Encrypt, there is a requirement to demonstrate control over the domain. If the instance of ogamma Visual Logger runs in a host machine which is accessible from the Internet, under publicly registered domain name, it is easy to prove ownership. In case if ogamma Visual Logger runs in a machine, not accessible from the Internet, as a workaround, publicly registered domain name can be assigned as its host name. In our case we are using ogamma.io domain name as example, which is registered by One-Way Automation. To prove ownership of this domain name, some text field should be added in domain registration records. Then that domain name is used in local network to access ogamma Visual Logger’s configuration GUI, by adding a record in the local host name resolution file (in Windows its location is C:\Windows\System32\drivers\etc\hosts.) in a PC where web browser is running. In real network local DNS server can be configured to resolve domain name (ogamma.io) to the IP address of the machine where ogamma Visual Logger is running.

  • Navigate to the web site https://www.sslforfree.com/.

  • Enter desired domain name and click on the button Create Free SSL Certificate.

    _images/https-1.png
  • On the next page click on the big button Manual Verification (DNS).

  • _images/https-2.png
  • Next page will provide instructions how to create new fields for the domain:

    _images/https-3.png
  • In essence, 2 fields, each type of TXT need to tbe created: one with field name _acme-challenge, and another with name _acme-challenge.www.

    _images/https-4.png
  • Go to the domain registrar web page and enter TXT records for the domain. In our case domain registrar is GoDaddy:

    _images/tls-2.png _images/tls-3.png
  • After adding TXT fields into domain record, wait until these records become accessible. It might take some time, usually about 1 minute will be enough. Then click on button Download SSL Certificate.

  • In the next page, click on button Download All SSL Certificate Files and download file sslforfree.zip into ogamma Visual Logger installation folder’s sub-folder ./data/[InstanceId], (here [InstanceId] is ogamma Visual Logger instance id).

  • Extract zip file in the same folder. As a result, 3 files will be un-zipped:

    • ca_bundle.crt - file containing chain of issuer Certificate Authority certificates;

    • certificate.crt - public key part of the SSL certificate, which will be used by the web server to support https protocol;

    • private.key - private key part of the SSL certificate.

      Tip

      Make sure this file is protected from un-authorized access.

    _images/https-6.png

Requirements for SSL certificate files generated by third-party tools.

In this case you will need 2 files:

  • certificate.crt - X.509 SSL certificate’s public key part, Base-64 encoded, and plus chain of issuer CA certificates (first, intermediate certificates, with the root CA certificate at the end of the file).

    _images/https-7.png
    • private.key - private key part of the SSL certificate, in Base-64 encoded PEM format. The first line in it should be -----BEGIN RSA PRIVATE KEY-----.

Configuring of the instance to use https.

Once certificate files are installed as described in sections above, you can change protocol to https in the instance settings:

  • Open list of instances via menu Settings/Instances.

  • Select desired instance record and click on edit icon;

  • In the opened Instance Settings dialog window:

    • Change value of the field Protocol to https.
    • Modify value of the field Host name if actual host name does not match with domain name used in the SSL certificate. This might be case, for example, if ogamma Visual Logger is running in Docker container: by default host name would be ogamma-logger, which might be not resolvable from remote machines anyway and cannot be used as domain name in the SSL certificate.
  • If required, change port number too.

  • Click on Save button.

    _images/https-8.png
  • After this, you will need to change URL in the browser to use https instead of http, and use exactly the same domain name used to generate SSL certificate. In our example case the URL will be https://ogamma.io:4880.

  • When the instance is switched to use https protocol very first time, it will generate so called DH Parameters file, which takes relatively long time (30 seconds or longer depending on hardware). Therefore it will take some time to open the configuration GUI page with https protocol in the URL very first time. If browser issues timeout error, you can refresh the page until it is rendered.

  • In case of any SSL certificate related errors, a message with error details will be logged in the application log file.

Note

If you are using Grafana SimpleJson data source to visualize data, after switching to use https, you will need to update URL in the data source settings to use https with domain name matching domain name of the SSL certificate.