Secure Your Nodinite Installation with HTTPS/TLS

Protect your Nodinite installation with industry-standard HTTPS/TLS encryption. This guide provides clear, version-specific instructions to ensure your environment meets security and compliance requirements.

Quick Navigation

Choose your scenario:

• ^{New 7.x} Configure HTTPS Before v7 Installation - Recommended approach for new installations
• ^{New 7.x} Add TLS to Existing v7 Installation - Enable HTTPS on already-installed v7 environment
• Development Certificates - Self-signed certificates for testing

Tip

Upgrading from v6→v7? The TLS re-enabling process is documented in the Updating from v6 to v7 guide.

Warning

Using Nodinite v6? See the legacy How to perform hardening on your Nodinite v6 installation guide. v6 is deprecated - we strongly recommend upgrading to v7.

Understanding the HTTPS Architecture

When you enable HTTPS for Nodinite, several components work together to provide secure communication:

Diagram: HTTPS communication flow between user, DNS, firewall, IIS, certificate, authentication, and Nodinite services.

Key Components Explained

Important

The DNS name users type in their browser (e.g., nodinite.yourdomain.com) must exactly match the Common Name (CN) or Subject Alternative Name (SAN) on your SSL certificate. Mismatches cause browser security warnings.

Understanding the Difference: v7 vs v6

The approach to security has fundamentally changed between versions:

Important

You should configure HTTPS/TLS BEFORE running the installation script. This is configured in the Nodinite Portal when registering your Environment.

If you didn't enable HTTPS during installation, follow the Nodinite v6 hardening steps to enable it now.

What You Need Before Starting

Before configuring HTTPS for Nodinite, ensure you have:

Certificate Requirements

• ✅ Valid SSL/TLS certificate from a trusted Certificate Authority (CA)
  • For production: Commercial CA (DigiCert, Let's Encrypt, etc.)
  • For development: Self-signed certificate (see development certificates)
• ✅ Certificate includes private key - Required for IIS binding
• ✅ Certificate matches your DNS name - Subject Alternative Name (SAN) or wildcard
• Avoid SHA-1 certificates - Use SHA-256 or higher (see Microsoft guidance)

Infrastructure Requirements

• ✅ Static IP address or DNS name for your IIS server
• ✅ Firewall rules allowing HTTPS traffic (port 443)
• ✅ Administrative access to IIS server and Nodinite Portal (v7)
• ✅ DNS record pointing to your Nodinite server

Common Certificate Sources

Option 1: Internal PKI (Most Common)
Use your organization's existing certificate infrastructure (Active Directory Certificate Services, internal PKI).

Option 2: Commercial Certificate Authority
Purchase from vendors like DigiCert, Sectigo, or GlobalSign.

Option 3: Free Certificates

• Let's Encrypt - Free, automated, renewable
• Certify SSL - Let's Encrypt GUI for IIS

Option 4: Development Only
Self-signed certificates (see development certificates)

^{New 7.x} Nodinite v7: Configure HTTPS Before Installation

The Modern Approach: With Nodinite v7, you configure HTTPS during environment registration in the Nodinite Portal. The installation script then applies these settings automatically.

Why Configure HTTPS Before Installation?

• ✅ Automated configuration - No manual web.config edits needed
• ✅ OAuth 2.0 / OIDC support - Required for modern authentication
• ✅ Consistent security - All services configured identically
• ✅ No reconfiguration - Avoid uninstalling/reinstalling later
• ✅ Immediate compliance - Production-ready from day one

Step-by-Step: Enable HTTPS in Nodinite v7

Step 1: Obtain and Install Your Certificate

Before configuring Nodinite, install your SSL/TLS certificate in IIS:

1. Obtain certificate (see Certificate Requirements above)
2. Install certificate in IIS:
   • Open IIS Manager
   • Select your server node
   • Double-click "Server Certificates"
   • Click "Import" (if you have a .pfx file) or "Complete Certificate Request"
3. Note the certificate thumbprint (you'll need this for the Portal)

See Microsoft IIS Certificate Installation Guide

Step 2: Create DNS Record

Create a DNS A record pointing to your Nodinite server:

nodinite.yourdomain.com  →  192.168.1.100

Step 3: Configure HTTPS in Nodinite Portal

1. Log in to the Nodinite Portal
2. Navigate to your Customer → Environments
3. Click "Add Environment" or edit existing environment
4. Navigate to the TLS tab
5. Configure the following settings:

Example of the TLS tab configuration in Nodinite Portal.

Important

If you plan to use OAuth 2.0 / OIDC authentication, you MUST enable TLS. See Install Nodinite v7 - OpenID for details.

Step 4: Complete Environment Setup and Install

1. Complete the remaining environment configuration tabs (Database, Authentication, Agents)
2. Save your environment configuration
3. Download the installation package
4. Run the PowerShell installation script

The script will automatically configure all Nodinite services with HTTPS bindings on port 443.

Step 5: Verify HTTPS is Working

After installation completes:

1. Open browser and navigate to https://nodinite.yourdomain.com
2. Verify the padlock icon appears in the address bar
3. Check that HTTP redirects to HTTPS (try http://nodinite.yourdomain.com)

^{New 7.x} Nodinite v7: Add TLS to Existing HTTP Installation

Already installed Nodinite v7 with HTTP? You can add TLS/HTTPS security at any time without reinstalling from scratch. This process applies to:

• ✅ New v7 installations that were initially configured with HTTP
• ✅ Upgraded v6→v7 environments where TLS was disabled during migration
• ✅ Development environments being promoted to production

Tip

This is the same process used when re-enabling TLS after v6→v7 upgrade. The steps are identical regardless of when you decide to enable TLS.

Prerequisites

Before enabling TLS:

• ✅ SSL/TLS certificate installed in IIS (see Step 1: Obtain and Install Your Certificate)
• ✅ Certificate thumbprint copied from IIS
• ✅ DNS record configured (optional but recommended for production)
• ✅ Access to Nodinite Portal with permission to edit your Environment
• ✅ Administrative access to the IIS server
• ✅ PowerShell 7 installed on the IIS server

Step-by-Step: Enable TLS on Existing v7 Installation

Step 1: Update Environment Configuration in Portal

1. Log in to the Nodinite Portal
2. Navigate to your Customer → Environments
3. Click Actions → Edit on your existing environment
4. Navigate to the TLS tab
5. Configure TLS settings:

Example of the TLS tab configuration in Nodinite Portal.

Important

The thumbprint must match a certificate installed in IIS on the target server. To find your thumbprint:

• Open IIS Manager → Server Certificates
• Double-click your certificate
• Copy the thumbprint from the Details tab

Step 2: Update Web Client Port to 443

1. In the same Environment modal, navigate to the Basic tab

2. Change the Web Client port from your current HTTP port (e.g., 40000) to 443

   Note

   If you use a custom HTTPS port other than 443, enter that port instead.

3. Save the environment configuration

Step 3: Download Updated Installation Package

1. After saving, close the Environment modal
2. Click Actions → Download to download the updated installation package
3. Extract the ZIP file to a temporary folder on your IIS server
4. Unblock the files:

cd C:\Path\To\Extracted\Folder
dir -r | unblock-file

Step 4: Run Uninstall Script (Remove Old Bindings)

Important

You must run the Uninstall script first to remove existing HTTP bindings. Do NOT use flags to remove setting files or databases.

1. Open PowerShell 7 with administrative privileges
2. Navigate to the extracted folder
3. Run the Uninstall script:

.\Uninstall-Core-Services.ps1

Tip

If you're using the uninstall script from the new ZIP file, you can safely ignore any errors about missing bindings during the uninstall process.

Do NOT include these flags:

• ❌ -RemoveSettingFiles
• ❌ -RemoveDatabases
• ❌ Any other destructive flags

The script only removes IIS bindings and applications - it preserves all your data, configurations, and databases.

Step 5: Run Install Script (Add HTTPS Bindings)

1. In the same PowerShell 7 terminal (still with admin privileges)
2. Run the Install script:

.\Core-Services-Only.ps1

Or if you're also updating agents:

.\Core-Services-and-Agents.ps1

The script will:

• Create new IIS applications with HTTPS bindings on port 443
• Configure applications to use the certificate matching your thumbprint
• Set up proper authentication and security settings

Step 6: Verify HTTPS is Working

1. Open a browser and navigate to https://nodinite.yourdomain.com (or your configured hostname)
2. Verify the padlock icon appears in the address bar
3. Confirm you can log in and access all Nodinite features
4. Check that all services are running:
   • Web Client
   • Web API
   • Log API
   • Logging Service
   • Monitoring Service

Troubleshooting: 401 Unauthorized When Accessing via Hostname Locally

Problem: PowerShell installation script or local browser access via FQDN (e.g., https://nodinitedev28.test.acme.com) returns 401 Unauthorized when accessing from the IIS server itself, but works from remote machines.

Root Cause: Windows loopback security check blocks local access to IIS via hostname when using Windows Authentication. By default, Windows treats local requests using a hostname (not localhost or machine name) as potential security risks.

Why Most Customers Don't See This Issue:

The loopback security check is enabled by default on ALL Windows installations - it's not specific to any particular environment. Most Nodinite deployments never encounter this because:

• Remote access pattern - Users access Nodinite from workstations, not from the IIS server itself
• localhost/IP bypass - The check doesn't apply to https://localhost or https://127.0.0.1
• NetBIOS tolerance - Accessing via server name (e.g., https://SERVERNAME) may work
• Remote installation - Setup scripts typically run from admin workstation, not on IIS server

When This Issue Occurs (Edge Case Scenario):

All of these conditions must be present simultaneously:

1. ✅ Script or browser running locally on the IIS server (not remote)
2. ✅ Accessing via FQDN (e.g., nodinitedev28.test.acme.com) not localhost/IP/machine name
3. ✅ Windows integrated authentication enabled
4. ✅ Typically during installation when PowerShell verifies HTTPS bindings immediately after configuration

Solution 1: Disable Loopback Check (Quick Fix - Less Secure)

Run this PowerShell command as Administrator on the IIS server:

New-ItemProperty HKLM:\System\CurrentControlSet\Control\Lsa -Name "DisableLoopbackCheck" -Value "1" -PropertyType dword

Restart required: No - takes effect immediately for new connections.

Warning

Security Impact: Disabling loopback check applies to all hostnames on the server, reducing security. Use Solution 2 for production environments.

Solution 2: Whitelist Specific Hostnames (Recommended - More Secure)

Whitelist only the specific hostname(s) you need:

# Get existing BackConnectionHostNames (if any)
$regPath = "HKLM:\System\CurrentControlSet\Control\Lsa\MSV1_0"
$existingValue = Get-ItemProperty -Path $regPath -Name "BackConnectionHostNames" -ErrorAction SilentlyContinue

# Add your Nodinite hostname
$hostnames = @("nodinitedev28.test.acme.com")

# If existing values, append to them
if ($existingValue) {
    $hostnames += $existingValue.BackConnectionHostNames
}

# Set the registry value (multi-string)
New-ItemProperty -Path $regPath -Name "BackConnectionHostNames" -Value $hostnames -PropertyType MultiString -Force

Restart required: No - takes effect immediately for new connections.

Verification:

1. Close all browser windows
2. Open new browser and navigate to https://nodinitedev28.test.acme.com (your FQDN)
3. You should now successfully authenticate and access Nodinite Web Client

Tip

For production environments, use Solution 2 (BackConnectionHostNames) to limit the security exception to only your Nodinite hostname.

External References:

• Microsoft KB896861 - Loopback Check

Step 7: Update Dependent Configurations

After enabling HTTPS, update any external systems or agents that connect to Nodinite:

Update these endpoints:

• ✅ Alarm Plugins - Update webhook URLs to use https://
• ✅ Pickup Log Events Service - Update Log API endpoint to use https://
• ✅ Azure Logic Apps - Update webhook and API endpoints
• ✅ Monitoring Agents (if remote) - Update service endpoints
• ✅ End-user bookmarks - Share new HTTPS URL with users
• ✅ Firewall rules - Ensure port 443 is allowed (update from previous HTTP port if needed)

Note

If you use Non-Events Monitoring Agent, verify the Log View API URIs are still accessible via HTTPS.

Completion Checklist

Before considering the TLS migration complete:

• HTTPS works in browser (padlock visible)
• Can log in to Web Client via HTTPS
• All Core Services accessible via HTTPS
• Alarm plugins updated and tested
• Pickup Service updated and logging events
• End-users notified of new HTTPS URL
• Firewall rules updated (if needed)
• Old HTTP port closed/blocked (optional security hardening)

Development Certificates for Testing

For development or testing environments, you can generate self-signed certificates.

Warning

Self-Signed Certificates are for Development Only! Do not use in production. Browsers will show security warnings, and clients will not trust the certificate without additional configuration.

Generate Self-Signed Certificate (PowerShell)

Simple Example (Minimal Configuration):

# Localhost certificate (minimal configuration)
New-SelfSignedCertificate `
    -DnsName "localhost" `
    -CertStoreLocation "cert:\LocalMachine\My" `
    -NotAfter (Get-Date).AddYears(2)

Production-Quality Development Certificate (Recommended):

# Configure your DNS name(s)
$dnsNames = @("nodinite.dev.local", "nodinite")

# Create certificate with security best practices
$cert = New-SelfSignedCertificate `
    -DnsName $dnsNames `
    -Subject "CN=$($dnsNames[0])" `
    -FriendlyName "Nodinite Dev SSL ($($dnsNames[0]))" `
    -KeyAlgorithm RSA -KeyLength 2048 `
    -HashAlgorithm SHA256 `
    -KeyExportPolicy Exportable `
    -NotAfter (Get-Date).AddYears(2) `
    -CertStoreLocation "Cert:\LocalMachine\My"

# Display certificate details
$cert | Format-List Subject, DnsNameList, Thumbprint, NotAfter

# Export certificate for backup and trust
New-Item -ItemType Directory -Force -Path C:\certs | Out-Null
$pfxPassword = Read-Host -AsSecureString -Prompt "Enter PFX password (for backup)"
Export-PfxCertificate -Cert $cert -FilePath "C:\certs\$($dnsNames[0]).pfx" -Password $pfxPassword | Out-Null
Export-Certificate -Cert $cert -FilePath "C:\certs\$($dnsNames[0]).cer" | Out-Null
Import-Certificate -FilePath "C:\certs\$($dnsNames[0]).cer" -CertStoreLocation Cert:\LocalMachine\Root | Out-Null

Write-Host "Certificate created successfully!" -ForegroundColor Green
Write-Host "Thumbprint: $($cert.Thumbprint)" -ForegroundColor Cyan
Write-Host "Files created in C:\certs\" -ForegroundColor Yellow

What This Script Does

1. Creates certificate with SHA-256 (secure), 2048-bit RSA key
2. Sets Subject Alternative Names (SANs) - Certificate valid for all specified DNS names
3. Exports to .pfx format - Includes private key, password-protected (for backup/migration)
4. Exports to .cer format - Public certificate only (for distribution to clients)
5. Automatically trusts certificate - Imports .cer to Trusted Root Certification Authorities
6. Displays thumbprint - Copy this for IIS binding and Portal configuration

Certificate Storage Locations

1. Personal Store (cert:\LocalMachine\My) - Used by IIS for HTTPS binding (requires private key)
2. Trusted Root Certification Authorities (cert:\LocalMachine\Root) - Same certificate copied here so browsers trust it

Important

The recommended PowerShell script above automatically handles both locations. If you used the minimal example, follow the manual trust steps below.

Trust Self-Signed Certificate (Manual Method)

If you used the minimal certificate example (not the recommended script), manually copy the certificate to Trusted Root:

Option 1: Using PowerShell

# Get the certificate thumbprint (from script output or find it)
$certificateThumbprint = "YOUR_CERTIFICATE_THUMBPRINT_HERE"

# Get certificate from Personal store
$certificate = Get-ChildItem -Path "Cert:\LocalMachine\My\$certificateThumbprint"

# Export to file
Export-Certificate -Cert $certificate -FilePath "C:\Temp\nodinite-dev.cer"

# Import to Trusted Root Certification Authorities
Import-Certificate -FilePath "C:\Temp\nodinite-dev.cer" `
    -CertStoreLocation "Cert:\LocalMachine\Root"

Option 2: Using Certificate Manager (GUI)

1. Press Win+R, type certlm.msc, press Enter
2. Navigate to Personal → Certificates
3. Find your certificate (e.g., CN=nodinite.dev.local)
4. Right-click → Copy
5. Navigate to Trusted Root Certification Authorities → Certificates
6. Right-click in the right pane → Paste

Tip

Why copy to Trusted Root? Self-signed certificates act as their own Certificate Authority. Browsers check the Trusted Root store to determine if they should trust a certificate. Without this step, browsers will show "Your connection is not private" warnings.

Certificate Backup

The .pfx file contains your private key (password-protected). Store it securely - you'll need it if you:

• Rebuild your server
• Move the certificate to another machine
• Recover from a disaster

Next Steps

Install Nodinite v7

Related Topics

• Install Nodinite v7
• Post Installation Steps
• Updating from v6 to v7
• How to perform hardening on your Nodinite v6 installation (deprecated)
• Secret Management
• Roles
• Users