So richten Sie HTTPS und das Zertifikat ein

Arbeitsplätze erreichen den Dienst nur über HTTPS. Dafür braucht der Server ein Zertifikat. Diese Anleitung führt Schritt für Schritt von der Zertifikatsdatei bis zur ersten erfolgreichen Verbindung.

Ein Zertifikat weist den Server gegenüber den Arbeitsplätzen aus, ähnlich einem Ausweis. Es besteht aus zwei Teilen:

• dem öffentlichen Teil mit dem Namen des Servers, dem Aussteller und der Gültigkeit;
• dem privaten Schlüssel, der den Server nicht verlassen darf.

Eine Datei mit der Endung .pfx (auch .p12) enthält beide Teile und ist mit einem Kennwort geschützt. Eine Datei mit der Endung .cer oder .crt enthält meist nur den öffentlichen Teil; damit allein kann der Dienst kein HTTPS anbieten.

Der Dienst sucht das Zertifikat unter dem Namen, den Sie in der Konfiguration angeben, im Zertifikatsspeicher des Computers (LocalMachine\My, in der Zertifikatsverwaltung “Eigene Zertifikate”). Er nimmt nur ein Zertifikat, das gerade gültig ist und einen privaten Schlüssel hat. Ein erneuertes Zertifikat mit demselben Namen übernimmt er ohne Neustart, spätestens nach 30 Sekunden.

Es gibt zwei Wege:

• Weg A, empfohlen: Sie importieren und prüfen das Zertifikat (Schritte 1 und 2), den Rest erledigt das Installationsprogramm: Berechtigung, Konfiguration, Firewall, Neustart.
• Weg B, von Hand: Sie erledigen auch diese Schritte selbst.

• Rechte eines Administrators auf dem Server.
• Der Dienst ist installiert, siehe Installation.
• Der Name des Servers, wie ihn die Arbeitsplätze aufrufen, etwa daten.example.com. Dieser Name muss im Zertifikat stehen, im Feld Alternativer Antragstellername als DNS-Name. Ein Arbeitsplatz, der den Server über einen anderen Namen oder über die IP-Adresse anspricht, lehnt das Zertifikat ab. Fragen Sie den Aussteller deshalb nach einem Zertifikat für genau diesen Namen.
• Ein Serverzertifikat mit privatem Schlüssel für diesen Namen, mit dem Verwendungszweck “Serverauthentifizierung”. Woher es kommt:
  • von der Zertifizierungsstelle Ihrer Firma (etwa Active Directory-Zertifikatdienste), für interne Namen wie srv01.firma.local;
  • von Let's Encrypt, nur für öffentliche Namen wie daten.firma.de; für interne Namen wie ….local stellt Let's Encrypt keine Zertifikate aus. Das Installationsprogramm bestellt es für Sie, siehe Installation, Schritt “Zertifikat”;
  • von einem gewerblichen Anbieter.
• Ein Zertifikat der Firmen-CA muss auf jedem Arbeitsplatz als vertrauenswürdig gelten. In einer Domäne verteilt die Gruppenrichtlinie das Stammzertifikat der Firmen-CA meist schon. Ein Zertifikat von Let's Encrypt oder einem gewerblichen Anbieter braucht auf den Arbeitsplätzen nichts.

Liegt das Zertifikat schon im Speicher, etwa weil die Firmen-CA es dort abgelegt hat, weiter mit Schritt 2.

Mit der Zertifikatsverwaltung:

1. Kopieren Sie die .pfx-Datei auf den Server, etwa nach C:\Temp.
2. Drücken Sie Windows-Taste + R, geben Sie certlm.msc ein und wählen Sie OK. Bestätigen Sie die Benutzerkontensteuerung. Es öffnet sich “Zertifikate - Lokaler Computer”. Nicht certmgr.msc: Das ist der Speicher Ihres eigenen Kontos, den der Dienst nicht liest.
3. Klicken Sie links mit der rechten Maustaste auf Eigene Zertifikate und wählen Sie Alle Aufgaben > Importieren.
4. Speicherort: “Lokaler Computer” ist vorgewählt. Weiter.
5. Zu importierende Datei: Wählen Sie Durchsuchen. Stellen Sie unten rechts im Dateifenster den Dateityp auf Privater Informationsaustausch (*.pfx;*.p12) um; sonst zeigt das Fenster die .pfx-Datei nicht an. Wählen Sie die Datei aus. Weiter.
6. Kennwort: Geben Sie das Kennwort der .pfx-Datei ein. Die übrigen Optionen bleiben, wie sie sind. Weiter.
7. Zertifikatspeicher: “Alle Zertifikate in folgendem Speicher speichern” mit Eigene Zertifikate. Weiter, Fertig stellen.
8. Löschen Sie die .pfx-Datei aus C:\Temp, wenn Sie sie nicht mehr brauchen. Sie enthält den privaten Schlüssel.

Oder mit PowerShell (als Administrator):

$kennwort = Read-Host -AsSecureString 'Kennwort der PFX-Datei'
Import-PfxCertificate -FilePath 'C:\Temp\daten.pfx' -CertStoreLocation 'Cert:\LocalMachine\My' -Password $kennwort

Haben Sie zwei Dateien (.crt und .key) statt einer .pfx, können Sie den Speicher überspringen und die Dateien direkt angeben, siehe Zertifikat aus einer Datei.

Führen Sie in PowerShell auf dem Server aus:

Get-ChildItem Cert:\LocalMachine\My |
    Format-List Subject, DnsNameList, NotAfter, HasPrivateKey, EnhancedKeyUsageList, Thumbprint

Beim richtigen Zertifikat gilt:

• Weg A: weiter mit Weg A: mit dem Installationsprogramm.
• Weg B: weiter mit Weg B: von Hand.

4. Starten Sie das Installationsprogramm erneut, oder öffnen Sie in Windows Apps & Features, wählen Sie WKL Database Gateway und dann Ändern (Windows 11 und Windows Server 2025: Einstellungen > Apps > Installierte Apps). Wählen Sie im Installationsprogramm Ändern.
5. Wählen Sie im Schritt Zertifikat die Option Vorhandenes Zertifikat und in der Liste das Zertifikat aus Schritt 2. Die Liste zeigt nur Zertifikate, die der Dienst verwenden kann. Fehlt Ihres, ist eine Bedingung aus Schritt 2 nicht erfüllt.
6. Gehen Sie die übrigen Schritte durch und wählen Sie auf der letzten Seite Ändern. Das Programm gibt dem Dienstkonto das Leserecht auf den privaten Schlüssel, trägt Zertifikat und HTTPS-Port in die Konfiguration ein, legt die Firewall-Regel an und startet den Dienst neu.
7. Weiter mit Prüfung.

4. Leserecht auf den privaten Schlüssel geben. Der Dienst läuft unter einem eigenen Konto, dem virtuellen Dienstkonto NT SERVICE\Wkl.Data.Gateway (oder dem gruppenverwalteten Dienstkonto, das Sie bei der Installation gewählt haben). Ohne Leserecht kann dieses Konto den Schlüssel nicht benutzen, und Verbindungen brechen ab.
   1. Klicken Sie in certlm.msc unter Eigene Zertifikate > Zertifikate mit der rechten Maustaste auf das Zertifikat und wählen Sie Alle Aufgaben > Private Schlüssel verwalten.
   2. Wählen Sie Hinzufügen. Stellen Sie unter Pfade den Namen dieses Computers ein (nicht die Domäne).
   3. Geben Sie NT SERVICE\Wkl.Data.Gateway ein und wählen Sie Namen überprüfen, dann OK.
   4. Haken Sie für dieses Konto Lesen an, nicht “Vollzugriff”. OK.

5. Konfiguration eintragen. Öffnen Sie im Programmordner (C:\Program Files\Wkl\Data Gateway) die Datei appsettings.Local.json mit dem Editor als Administrator. Gibt es sie nicht, legen Sie sie an. Werte in dieser Datei gelten vor denen, die das Installationsprogramm schreibt, und bleiben bei einem Update erhalten. Wählen Sie das Zertifikat später doch über das Installationsprogramm (Weg A), entfernen Sie die Einträge hier wieder, sonst gelten weiter diese. Tragen Sie ein, mit Ihrem Namen statt daten.example.com:

   {
     "Gateway": {
       "Certificate": { "Subject": "daten.example.com" }
     },
     "Kestrel": {
       "Endpoints": {
         "Https": { "Url": "https://0.0.0.0:8433" }
       }
     }
   }

   • Subject ist der Name aus DnsNameList in Schritt 2. Groß- und Kleinschreibung spielen keine Rolle.
   • 0.0.0.0 heißt: auf allen Netzwerkadressen des Servers. 8433 ist der HTTPS-Port; haben Sie bei der Installation einen anderen gewählt, tragen Sie diesen ein.
   • Steht in der Datei schon etwas, fügen Sie die Abschnitte ein, statt die Datei zu ersetzen. Die Datei muss gültiges JSON bleiben: Kommas zwischen den Einträgen, alle Klammern geschlossen.

6. Firewall öffnen. Das Installationsprogramm legt die Regel meist schon an. Prüfen Sie in PowerShell:

   Get-NetFirewallPortFilter -Protocol TCP | Where-Object LocalPort -eq 8433 | Get-NetFirewallRule |
       Format-Table DisplayName, Enabled, Direction, Action

   Fehlt eine Zeile mit Enabled True, Inbound, Allow, legen Sie die Regel an. Unter -RemoteAddress stehen die Netze Ihrer Arbeitsplätze; ohne die Angabe ist der Port aus jedem Netz erreichbar, das den Server erreicht:

   New-NetFirewallRule -DisplayName 'Wkl.Data.Gateway HTTPS' -Direction Inbound -Protocol TCP `
       -LocalPort 8433 -RemoteAddress 10.0.0.0/8 -Action Allow

7. Dienst neu starten (PowerShell als Administrator):

   Restart-Service Wkl.Data.Gateway

   Spätere Erneuerungen des Zertifikats brauchen keinen Neustart.

8. Weiter mit Prüfung.

Statt des Speichers kann der Dienst das Zertifikat aus einer Datei lesen, auch unter Linux. Tragen Sie in Schritt 5 statt "Subject" die Datei ein:

"Certificate": { "File": "zertifikat/gateway.pfx", "Password": "env:WKL_GW_CERT_PASSWORD" }

• Ein relativer Pfad gilt ab dem Programmordner.
• Das Kennwort steht nicht in der Datei, sondern in einer Umgebungsvariablen (env:Name) oder einer Datei (file:Pfad).
• Für zwei Dateien: "File": "zertifikat/gateway.crt", "KeyFile": "zertifikat/gateway.key".
• Das Dienstkonto braucht Leserecht auf die Dateien. Eine neue Datei an derselben Stelle übernimmt der Dienst ohne Neustart.

Alle Einstellungen: Konfiguration: Gateway:Certificate.

1. Auf dem Server (PowerShell): Der Dienst lauscht auf dem HTTPS-Port.

   Get-NetTCPConnection -LocalPort 8433 -State Listen

   Es erscheint mindestens eine Zeile. Erscheint keine, fehlt der HTTPS-Eintrag aus Schritt 5, oder der Dienst läuft nicht.

2. Auf einem Arbeitsplatz (PowerShell): Der Port ist erreichbar.

   Test-NetConnection daten.example.com -Port 8433

   Erwartet: TcpTestSucceeded : True.

3. Auf einem Arbeitsplatz im Browser Edge: https://daten.example.com:8433/health/live. Erwartet: Die Seite zeigt Healthy, ohne Warnung zum Zertifikat, mit Schloss in der Adresszeile. Geben Sie die Adresse genau mit dem Namen aus dem Zertifikat ein, mit https:// und dem Port.

Danach zeigt die Menge ServiceStatus der Verwaltungsschnittstelle Inhaber, Ablauf und Resttage des Zertifikats; 14 Tage vor dem Ablauf meldet sie warn (Gateway:Certificate:WarnDays).

Schlägt ein Schritt fehl: HTTPS antwortet nicht.

Führen Sie als Administrator auf dem Server und auf den Arbeitsplätzen aus:

Enable-TlsEccCurve -Name 'X25519_MLKEM768' -Position 0   # an erster Stelle, sonst gewinnt X25519

Dienst und Treiber vereinbaren dann TLS 1.3 mit X25519MLKEM768; fehlt die Einstellung auf einer Seite, fallen beide auf X25519 zurück. Voraussetzung ist auf beiden Seiten eine Windows-Version, die die Kurve kennt; fehlt sie, meldet der Befehl einen Fehler. Die Einstellung gilt für den ganzen Rechner, also für jedes Programm, das die TLS-Bibliothek von Windows nutzt. Rückweg: Disable-TlsEccCurve -Name 'X25519_MLKEM768'; Get-TlsEccCurve zeigt die Liste vor und nach der Änderung (Microsoft: Enable-TlsEccCurve).

• Nur HTTPS von außen. Unverschlüsseltes HTTP (Port 8434) antwortet nur auf dem Server selbst und dient Test und Gesundheitsprobe. Binden Sie es nie an eine Adresse, die andere Rechner erreichen: Schlüssel und Kennwörter gingen im Klartext.
• Die Prüfung des Zertifikats lässt sich nicht abschalten. Treiber, WklGatewayClient und Power Query lehnen ein Zertifikat ab, dem der Arbeitsplatz nicht vertraut oder dessen Name nicht passt.
• Findet der Dienst kein gültiges neues Zertifikat, bleibt das bisherige in Kraft, solange es gilt. Die Ereignisanzeige nennt den Grund als Warnung der Quelle Wkl.Data.Gateway.
• Selbstsigniertes Zertifikat: Das Installationsprogramm kann eines erzeugen, nur zum Ausprobieren. Kein Arbeitsplatz vertraut ihm von selbst.
• Fest in Kestrel lässt sich ein Zertifikat auch unter Kestrel:Endpoints:Https:Certificate eintragen (Kennwort über die Umgebungsvariable Kestrel__Endpoints__Https__Certificate__Password). Ein so festgelegtes Zertifikat wechselt erst mit einem Neustart, und --urls gilt dann nicht mehr.

• HTTPS antwortet nicht
• Installation
• Installationspaket: Let's Encrypt
• So betreiben Sie den Dienst hinter IIS oder einem Proxy