DS Server

HTTPS

Topic

Applications, browsers and the Document Editor send credentials, access tokens and documents to DS Server, so a server that is reachable from other machines should be served over HTTPS. When DS Server runs on its own with Kestrel, the web server of ASP.NET Core, you give Kestrel a TLS certificate in the configuration. In IIS, the HTTPS binding of the site does this instead.

The sections below explain what happens with the default HTTPS address, and how to configure a certificate in appsettings.json or with environment variables, for a server, a Windows service or a container.

The Default HTTPS Address

The hostsettings.json of the download archive lists an HTTPS address next to the HTTP address:

{
  "urls": "http://*:5000;https://*:5001"
}

It names no certificate, so Kestrel looks for the ASP.NET Core development certificate:

  • On a server with only the .NET runtime, there is none, and DS Server ends at startup:

    Unhandled exception. System.InvalidOperationException: Unable to configure HTTPS endpoint. No server certificate was specified, and the default developer certificate could not be found or is out of date.
To generate a developer certificate run 'dotnet dev-certs https'. To trust the certificate (Windows and macOS only) run 'dotnet dev-certs https --trust'.
For more information on configuring HTTPS see https://go.microsoft.com/fwlink/?linkid=848054.

  • On a development machine with the .NET SDK and a development certificate, DS Server starts and serves https://localhost:5001 with that certificate, and logs the warning "The ASP.NET Core developer certificate is not trusted.". The certificate is issued to localhost and is for development only.

For a server, either remove the HTTPS address from hostsettings.json and serve HTTP only, for example behind a reverse proxy or load balancer that terminates TLS, or configure a certificate as described below. The official Docker image has no HTTPS address.

Configure HTTPS in appsettings.json

Kestrel endpoints in appsettings.json define the addresses and the certificate. Add a Kestrel section to the existing appsettings.json, next to Logging, AllowedHosts and LiteDbOptions:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:5000"
      },
      "Https": {
        "Url": "https://0.0.0.0:5001",
        "Certificate": {
          "Path": "certificate.pfx",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

The configuration works as follows:

  • Endpoints lists the addresses Kestrel listens on. The names Http and Https are free to choose; the Url of each endpoint sets the protocol, the network interface and the port. 0.0.0.0 accepts connections on all IPv4 interfaces.
  • Certificate names the certificate of the HTTPS endpoint. Path is a PFX file, and a relative path is resolved against the DS Server folder. Password is the password of the file.
  • Only the endpoints serve. Once endpoints are defined, DS Server ignores the addresses of hostsettings.json and logs "Overriding address(es) 'http://:5000, https://:5001'. Binding to endpoints defined via IConfiguration and/or UseKestrel() instead.". Without the Http endpoint, DS Server listens on HTTPS only.

Copy the certificate file to the DS Server folder and start DS Server as usual:

dotnet TXTextControl.DocumentServices.dll

The log file lists both endpoints:

[2026-09-29 08:02:02] [Information] Now listening on: http://0.0.0.0:5000
[2026-09-29 08:02:02] [Information] Now listening on: https://0.0.0.0:5001

Kestrel also accepts a certificate and its private key as PEM files: set Path to the certificate file and KeyPath to the key file instead of Password. Microsoft's Configure endpoints for the ASP.NET Core Kestrel web server describes the other options, such as certificates from the certificate store.

Keep the Password Out of the File

A certificate password in appsettings.json can be read by anyone with access to the file. Leave Password out of the file and set it as an environment variable. ASP.NET Core maps the variable Kestrel__Endpoints__Https__Certificate__Password to the setting Kestrel:Endpoints:Https:Certificate:Password, and the variable overrides the file. If the password is missing from both, DS Server ends at startup with "System.Security.Cryptography.CryptographicException: The certificate data cannot be read with the provided password, the password may be incorrect."

In PowerShell on Windows:

$env:Kestrel__Endpoints__Https__Certificate__Password="<certificate password>"
dotnet TXTextControl.DocumentServices.dll

In Bash on Linux:

export Kestrel__Endpoints__Https__Certificate__Password="<certificate password>"
dotnet TXTextControl.DocumentServices.dll

For a systemd service, set the variable with an Environment= line in the unit file. A common layout keeps the certificate in its own folder, such as certs/certificate.pfx next to appsettings.json, so that certificates and secrets are managed apart from the files of DS Server.

Configure HTTPS With Environment Variables

The whole endpoint configuration can come from environment variables, which suits containers: the image stays unchanged, and the certificate is mounted from outside. For the official image:

docker run -d -p 5001:5001 --name dsserver \
  -v /etc/dsserver/certs:/certs:ro \
  -e Kestrel__Endpoints__Https__Url=https://0.0.0.0:5001 \
  -e Kestrel__Endpoints__Https__Certificate__Path=/certs/certificate.pfx \
  -e Kestrel__Endpoints__Https__Certificate__Password="<certificate password>" \
  txtextcontrol/dsserver-core:5.0.1
  • -v /etc/dsserver/certs:/certs:ro mounts the folder with the certificate read-only at /certs.
  • The three Kestrel__Endpoints__Https__… variables define the HTTPS endpoint and its certificate. Because they define an endpoint, the HTTP address of the image is no longer served; add -e Kestrel__Endpoints__Http__Url=http://0.0.0.0:5000 and -p 5000:5000 to keep it.

HTTPS in IIS

When IIS hosts DS Server, add an HTTPS binding with your certificate to the IIS site. IIS terminates TLS, and neither hostsettings.json nor Kestrel endpoints are used. Manual Installation sets up the site.

Connect Clients Over HTTPS

The service URL of your applications changes to the HTTPS address, for example https://dsserver.example.com:5001. The Document Editor then connects with a secure WebSocket, wss:, instead of ws:. Update the service URL in the client packages, and the redirect URIs of the security profiles if their addresses change as well.

Next Steps