Set up HTTPS and the certificate

Workstations reach the service over HTTPS only, and for that the server needs a certificate. This guide takes you step by step from the certificate file to the first successful connection.

A certificate identifies the server to the workstations, much like an ID card. It has two parts:

• the public part, with the server's name, the issuer, and the validity period;
• the private key, which must never leave the server.

A file ending in .pfx (or .p12) contains both parts and is protected by a password. A file ending in .cer or .crt usually contains only the public part; with that alone, the service can't offer HTTPS.

The service looks for the certificate by the name you set in the configuration, in the computer's certificate store (LocalMachine\My, shown as “Personal” in the certificate manager). It only takes a certificate that is currently valid and has a private key. It picks up a renewed certificate with the same name without a restart, within 30 seconds.

There are two ways:

• Option A (recommended): use the installer. You import and check the certificate (steps 1 and 2); the installer does the rest: permission, configuration, firewall, restart.
• Option B: by hand. You do these steps yourself as well.

• Administrator rights on the server.
• The service is installed; see Installation.
• The name the workstations use to reach the server, for example data.example.com. This name must be in the certificate, in the Subject Alternative Name field as a DNS name. A workstation that addresses the server by another name or by its IP address rejects the certificate. So ask the issuer for a certificate for exactly this name.
• A server certificate with a private key for this name, with the purpose “Server Authentication”. Where it comes from:
  • your company's certification authority (for example Active Directory Certificate Services), for internal names such as srv01.company.local;
  • Let's Encrypt, for public names such as data.company.com only; Let's Encrypt doesn't issue certificates for internal names such as ….local. The installer orders it for you; see Installation, step “Certificate”;
  • a commercial provider.
• Every workstation must trust a certificate from the company CA. In a domain, Group Policy usually distributes the company CA's root certificate already. A certificate from Let's Encrypt or a commercial provider needs no setup on the workstations.

If the certificate is already in the store, for example because the company CA put it there, continue with step 2.

With the certificate manager:

1. Copy the .pfx file to the server, for example to C:\Temp.
2. Press Windows key + R, type certlm.msc, and select OK. Confirm the User Account Control prompt. “Certificates - Local Computer” opens. Not certmgr.msc: that is your own account's store, which the service doesn't read.
3. On the left, right-click Personal and select All Tasks > Import.
4. Store Location: “Local Machine” is preselected. Next.
5. File to Import: Select Browse. At the bottom right of the file window, change the file type to Personal Information Exchange (*.pfx;*.p12); otherwise the window doesn't show the .pfx file. Select the file. Next.
6. Password: Enter the password of the .pfx file. Leave the other options as they are. Next.
7. Certificate Store: “Place all certificates in the following store” with Personal. Next, Finish.
8. Delete the .pfx file from C:\Temp once you no longer need it. It contains the private key.

Or with PowerShell (as administrator):

$password = Read-Host -AsSecureString 'Password of the PFX file'
Import-PfxCertificate -FilePath 'C:\Temp\data.pfx' -CertStoreLocation 'Cert:\LocalMachine\My' -Password $password

If you have two files (.crt and .key) instead of one .pfx, you can skip the store and name the files directly; see Certificate from a file.

Run in PowerShell on the server:

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

For the right certificate:

• Option A: continue with Option A (recommended): use the installer.
• Option B: continue with Option B: by hand.

4. Start the installer again, or in Windows open Apps & features, select WKL Database Gateway and then Change (Windows 11 and Windows Server 2025: Settings > Apps > Installed apps). In the installer, select Change.
5. In the Certificate step, select Existing certificate and, in the list, the certificate from step 2. The list only shows certificates the service can use. If yours is missing, a condition from step 2 isn't met.
6. Go through the remaining steps and select Change on the last page. The program gives the service account read access to the private key, enters the certificate and the HTTPS port in the configuration, creates the firewall rule, and restarts the service.
7. Continue with Check.

4. Give read access to the private key. The service runs under its own account, the virtual service account NT SERVICE\Wkl.Data.Gateway (or the group managed service account you chose during installation). Without read access, this account can't use the key, and connections fail.
   1. In certlm.msc, under Personal > Certificates, right-click the certificate and select All Tasks > Manage Private Keys.
   2. Select Add. Under Locations, choose this computer's name (not the domain).
   3. Enter NT SERVICE\Wkl.Data.Gateway, select Check Names, then OK.
   4. Check Read for this account, not “Full control”. OK.

5. Enter the configuration. In the program folder (C:\Program Files\Wkl\Data Gateway), open the file appsettings.Local.json in Notepad as administrator. If it doesn't exist, create it. Values in this file take precedence over those the installer writes, and they're kept on an update. If you later choose the certificate through the installer after all (option A), remove the entries here again; otherwise these keep applying. Enter the following, replacing data.example.com with your server's name:

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

   • Subject is the name from DnsNameList in step 2. The name isn't case-sensitive.
   • 0.0.0.0 means: on all of the server's network addresses. 8433 is the HTTPS port; if you chose another one during installation, enter that one.
   • If the file already has content, add the sections instead of replacing the file. The file must stay valid JSON: commas between entries, all brackets closed.

6. Allow the port through the firewall. The installer usually creates the rule already. Check in PowerShell:

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

   If no line shows Enabled True, Inbound, Allow, create the rule. Under -RemoteAddress, list the networks of your workstations; without it, the port is reachable from every network that reaches the server:

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

7. Restart the service (PowerShell as administrator):

   Restart-Service Wkl.Data.Gateway

   Later renewals of the certificate don't need a restart.

8. Continue with Check.

Instead of the store, the service can read the certificate from a file, also on Linux. In step 5, enter the file instead of "Subject":

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

• A relative path is relative to the program folder.
• The password isn't in the file but in an environment variable (env:Name) or a file (file:Path).
• For two files: "File": "certificate/gateway.crt", "KeyFile": "certificate/gateway.key".
• The service account needs read access to the files. The service picks up a new file in the same place without a restart.

All settings: Configuration: Gateway:Certificate.

1. On the server (PowerShell): the service listens on the HTTPS port.

   Get-NetTCPConnection -LocalPort 8433 -State Listen

   At least one line appears. If none does, the HTTPS entry from step 5 is missing, or the service isn't running.

2. On a workstation (PowerShell): the port is reachable.

   Test-NetConnection data.example.com -Port 8433

   Expected: TcpTestSucceeded : True.

3. On a workstation in the Edge browser: https://data.example.com:8433/health/live. Expected: the page shows Healthy, without a certificate warning, with a lock in the address bar. Enter the address with exactly the name from the certificate, with https:// and the port.

After that, the ServiceStatus entity set of the administration API shows the certificate's subject, expiry date, and days left; 14 days before expiry it reports warn (Gateway:Certificate:WarnDays).

If a step fails: HTTPS does not respond.

Run as administrator on the server and on the workstations:

Enable-TlsEccCurve -Name 'X25519_MLKEM768' -Position 0   # first in the list, otherwise X25519 wins

The service and the driver then negotiate TLS 1.3 with X25519MLKEM768; if the setting is missing on one side, both fall back to X25519. Both sides need a Windows version that supports the curve; if it doesn't, the command reports an error. The setting applies to the whole computer, so to every program that uses the Windows TLS library. To undo: Disable-TlsEccCurve -Name 'X25519_MLKEM768'; Get-TlsEccCurve shows the list before and after the change (Microsoft: Enable-TlsEccCurve).

• Only HTTPS from outside. Unencrypted HTTP (port 8434) answers only on the server itself and serves testing and the health probe. Never bind it to an address other computers can reach: keys and passwords would travel in plain text.
• Certificate validation can't be turned off. The driver, WklGatewayClient, and Power Query reject a certificate the workstation doesn't trust or whose name doesn't match.
• If the service finds no valid new certificate, it keeps using the current one until that one expires. Event Viewer gives the reason as a warning from the source Wkl.Data.Gateway.
• Self-signed certificate: The installer can create one, for trying things out only. No workstation trusts it on its own.
• Certificate fixed in Kestrel: you can also set a certificate under Kestrel:Endpoints:Https:Certificate (password through the environment variable Kestrel__Endpoints__Https__Certificate__Password). A certificate set this way changes only with a restart, and --urls no longer applies.

• HTTPS does not respond
• Installation
• Installation package: Let's Encrypt
• Run the service behind IIS or a proxy