- 5 minutes to read

Step 10: Configure TLS

In v6, a custom IIS web site usually terminated TLS. In v7 you describe the certificate once, per environment, in the Portal, and the CLI binds it to every Core Service web site at each install and update. Because v6 TLS settings are not carried forward, decide now whether to enable HTTPS (recommended) or continue on HTTP.

Understanding TLS in v7

flowchart LR CA["fa:fa-certificate Certificate
subject or SAN"] -->|"Install"| STORE["fa:fa-key LocalMachine\WebHosting
or LocalMachine\My"] PORTAL["fa:fa-cloud Portal Servers step
Core host Configuration"] -->|"Package"| CLI["fa:fa-terminal Nodinite.Installer.Cli.exe"] CLI -->|"Find by subject"| STORE CLI -->|"Bind HTTPS + SNI"| SITES["fa:fa-globe One IIS web site
per Core Service"] USER["fa:fa-user Browser"] -->|"https://host:port"| SITES style CA fill:#9E59BB style STORE fill:#3F827B style PORTAL fill:#2678BD style CLI fill:#E47528 style SITES fill:#93d16d style USER fill:#2678BD

How the certificate reaches the Core Services. You install the certificate (purple) in a LocalMachine store (teal) and enter its subject in the Portal Core host Configuration (blue). At every install and update, the CLI (orange) searches LocalMachine\WebHosting and LocalMachine\My for a valid matching certificate and binds it to each web site (green): Web Client, Web API, Log API, Logging Service, Monitoring Service, and MCP Server.

Identify the certificate by Certificate subject. A renewal keeps the subject but changes the thumbprint, so after a renewal you only install the new certificate and run the update again. Set a thumbprint only when you must pin one exact certificate.

Prerequisites

Choose Your Path

Option When to use
Option A: Enable TLS ✅ Recommended. Your certificate is installed and DNS is configured
Option B: Continue Without TLS You run HTTP only, for example a test environment on an intranet

Option A: Enable TLS (HTTPS)

Critical Shared IIS Certificate Reuse Edge Case

Warning

If this server hosts other IIS web sites and you reuse the same certificate for Nodinite, the installer can remove HTTPS bindings on those other sites when they lack a host name with SNI enabled. In this exact configuration the risk is effectively 100%, and dependent APIs or applications stop working.

IIS HTTPS binding without host name and SNI
Example of an HTTPS binding on another site that must be corrected before you reuse the same certificate for Nodinite.

Before you continue, use one of these mitigations:

  • On every non-Nodinite IIS site that uses the certificate, assign a host name and enable SNI on the HTTPS binding.
  • Use a different certificate for Nodinite.
  • Install Nodinite on another machine.

If those bindings already have a host name and SNI, Nodinite can co-exist with the other sites.

Steps

  1. In the Portal, open your environment and go to the Servers step.

  2. In Core host Configuration, enter:

    • Hostname / SNI: the DNS name users and agents use, for example nodinite.contoso.com
    • Certificate subject: for example nodinite.contoso.com or *.contoso.com
    • Certificate thumbprint: leave empty unless you must pin one certificate

    Servers step with the Core host Configuration section
    Example of the Servers step where you enter the Hostname (SNI), the Certificate subject, and the optional Certificate thumbprint.

    Important

    A migrated environment runs Windows authentication. Add the host name to the browser's Local Intranet Zone, for example through Group Policy, or browsers fall back from Kerberos to NTLM with 4+ second page loads. When the IIS application pools run as a custom domain account, the host name also needs HTTP Service Principal Names (SPN). See NTLM vs Kerberos Authentication and Restoring Kerberos Transparent Login After v7 Upgrade.

  3. (Recommended) In Core platform services, set the Web Client port to 443, and update your firewall rules (Network and Firewall Overview). With 443, the HTTPS default, users reach the Web Client without a port in the URL. HTTPS also works on any other port, but users must then include it in the URL.

  4. (Optional) In the Agents step, add and configure the Pickup Log Events Service now to save a round trip; details in Step 11.

  5. Save, go to Review and Download, and download the package.

  6. Extract the package and run the CLI from an elevated PowerShell 7 prompt, as in Step 7: Run the CLI Workflow. Use the server folder of your package:

    .\Nodinite.Installer.Cli.exe validate --config .\nodinite01\config.cli.json
.\Nodinite.Installer.Cli.exe deploy-environment --config .\nodinite01\config.cli.json --dry-run
.\Nodinite.Installer.Cli.exe deploy-environment --config .\nodinite01\config.cli.json

    The deployment keeps the existing configuration and databases and updates the IIS bindings for the new TLS settings.

  7. Open https://nodinite.contoso.com:<Web Client port>, check the padlock, and sign in.

After a certificate renewal, install the renewed certificate and run the update again with Update Nodinite v7; with a subject configured, nothing changes in the Portal.

Option B: Continue Without TLS (HTTP Only)

  1. Confirm in the Portal that the migration is marked complete (Step 7) and the workspace is saved.
  2. Leave Core host Configuration empty and continue with Step 11.

You can enable HTTPS later with Option A at any time. OAuth 2.0 / OpenID Connect requires HTTPS.

Completion Checklist

  • Option A: certificate subject configured, package deployed, Web Client reachable over HTTPS without certificate errors, sign-in works
  • Option B: environment confirmed in the Portal, Web Client reachable over HTTP
  • Pickup Service can now be configured in the Portal

Troubleshooting

"HTTP Error 500.21" After Install

The Web Client shows a handler error. Check the following:

  • The .NET 10.0 Hosting Bundle is installed after the IIS Windows Features
  • Restart IIS: iisreset /restart
  • Run the CLI deployment again

Browser Shows "Not Private" Warning

The browser shows a certificate warning. Check the following:

Next Steps