waveware Server

Connection Establishment

In order to establish a connection from the client to the waveware server, information in the 'Server' field of the client login window is evaluated.

With the help of prefixes, you can activate various special features when establishing a connection directly via the client.

It is always recommended to establish an encrypted connection using "https". Further special features when setting up under 'Secure Client Connections'. If possible, avoid unencrypted connections ("http" and without a prefix).

Connection problems often occur because of the following reasons:

• Firewall or Reverse-Proxy does not support any HTTP/2
  • Try with the prefix "web+https" or "web+http".
• Proxy does not support any HTTP/2- or local connections
  • Try with the prefix "noproxy" or "noproxy+web+https" or "noproxy+web+http"

Setup

If you have a valid certificate (see also 'Certificate Creation with Let's Encrypt'), you have to make this known to the waveware server. To do this, open the waveware server settings via the menu ribbon 'Global settings' of the DataManagement and scroll to the 'GRPC settings' area.

You can make the settings for the certificate in two ways:

• Windows Certificate Store
  As an alternative to using PEM certificates, the Windows certificate store can be used.
  
  At this point you need to provide the certificate's fingerprint. You can also specify several certificates in the 'Thumbprint of the Certificate' field by separating them with a comma (comma-separated list). You do not have to specify a specific certificate store. The specified certificate is automatically searched for in the following certificate stores:

  Value	Description
  CertificateAuthority	Certificate stores of intermediate certification authorities.
  My	Certificate store for personal certificates.
  Root	Certificate store for trusted root certification authorities.

  It should be noted that the certificate selected in this way contains the private key and this can be exported. When importing the certificate into the certificate store, activate the import option 'Mark key as exportable'. After the import, the sentence "You have a private key for this certificate" appears in the certificate properties under 'General'.
• Direct Path Specification
  If a PEM (Privacy Enhanced Mail) certificate is to be used, the full path to the certificate and the full path to the private key file must be specified. Both paths are to be specified from the point of view of the waveware server. In addition, access rights to the paths are required for the user under which the waveware server service is running.
  

After saving the settings, you have to manually restart the waveware server service once so that the settings are applied.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    ...
    <userSettings>
          <LoyHutz.Server.Core.Lib.Properties.Settings>
              ...
              <setting name="GrpcCertificateSettings" serializeAs="String">
                  <value>CertFullPath=C:\Data\Cert\cert.pem;CertKeyPath=C:\Data\Cert\key.pem;CertStore=;CertThumbprint=</value>
              </setting>
             ...
         </LoyHutz.Server.Core.Lib.Properties.Settings>
     </userSettings>
</configuration>

<setting name="GrpcCertificateSettings" serializeAs="String">
   <value>CertFullPath=C:\Data\Cert\cert.pem;CertKeyPath=C:\Data\Cert\key.pem;CertStore=;CertThumbprint=</value>
</setting>

Secure Mobile Connections

The connection from the mobile client to the waveware server is also encrypted after certificates have been set up. To use the certificates, they must use a public certification authority (CA). Using certificates with local certification authorities is not possible and results in connection errors.

In addition, Android devices may have problems logging in via HTTPS with waveware MOBILE (1/2). In this case, the app displays "Login failed. Please try again later.". The error message “Trust anchor for certification path not found” is logged in the mobile log file. This error indicates an incomplete chain of trust.

As a rule, common root certificates such as “DigiCert Global Root G2” are installed on the devices. To complete the certificate chain, all intermediate certificates must be installed locally on the device.

The root certificate “DigiCert Global Root G2” is already present on the device as standard. However, the intermediate certificate “RapidSSL TLS RSA CA G1” is missing. After manually installing the intermediate certificate on the device, login with the app works over HTTPS.

The installation of the missing intermediate certificates can also be carried out centrally via an MDM (Mobile Device Management Software) in order to update all managed devices equally. Many MDM systems offer the ability to create configuration profiles. These profiles specify that intermediate certificates that were previously uploaded to the MDM should be installed on the target devices. Depending on the MDM system used and the device types (iOS, Android), additional settings can be made, e.g. whether the certificate is used for specific networks (WLAN or VPN) or whether it should be available globally on the device.

The configuration profiles containing the intermediate certificates are then distributed to the appropriate devices. After receiving the profile, the intermediate certificates are stored in the certificate store of the device. They are then available for waveware MOBILE (1/2).

Typically, you can use the MDM system to monitor the installation status on the devices and thus verify that the target devices have received the required intermediate certificates. If intermediate certificates expire or need to be updated, you can also control the exchange centrally via the MDM system.

Application Example 

The API authentication is illustrated in the following Javascript:

var salt = "";
// salt holen
$.ajax({
url: "Api/GetSalt",
dataType: "text",
success: function (result) {
    // salt auswerten
    salt = eval("(" + result + ")");
    // passwort hash generieren
    var pwHash = new jsSHA(unescape(encodeURIComponent(password)), "ASCII").getHash("SHA-256", "B64");
    var transportHash = new jsSHA(pwHash + salt, "ASCII").getHash("SHA-256", "B64");
    // authentifizierungs funktion aufrufen
    $.ajax({
        url: "Api/Authenticate",
        data: "installid=" + encodeURIComponent(installId) + "&username=" + encodeURIComponent(username) + "&password=" + encodeURIComponent(transportHash) + "&mandantid=" + encodeURIComponent(mandantId),
        dataType: "text",
        success: function (result) {
            result = checkForError(result);
            if (result === false)
            return;
}}));

The 'jsSHA' library is used to generate the hash (http://caligatio.github.io/jsSHA). The AJAX/REST requests are executes with the aid of jQuery.