SSL And External Connections

SSL (TLS) is the technology behind HTTPS, which allows for encrypted connections between a web browser and a server. In addition, SSL certificates assert the identity of the server, allowing more certainty that you are connecting to who you think you are.

Sym3 Web now requires a secure connection to function. The default install uses a SSL certificate that allows Sym3 Web to be accessed on the machine it was installed on via https://localhost/Sym3Web. As mentioned, SSL certificates assert an identity. One of the ways they do this is by only allowing content to be served through the domain that the certificate was created for (localhost, in this instance). In addition to having to be associated with a domain, certificates must also be trusted by every browser that is to connect to the web server.

What this means for you is that additional work is required to connect to and use Sym3 Web from other machines beyond simply installing it.

Broadly, that work is as follows:

  1. Acquire a certificate.
  2. Configure Sym3 Web and the machine it is hosted on to use the new certificate.
  3. If the certificate is self-signed, install and trust it on each and every client machine.
  4. (Optional) Configure the web client to use HTTPS.

Certificates require maintenance. They have expiry dates, and must be renewed. Technology changes in this area fairly rapidly, meaning new browser versions can often require new certificates, direct intervention to continue to function. If you are using a self-signed certificate, any new machines (or old machines with a new OS install) will require work to be made to function with Sym3 Web.

This document will guide you through the steps required for a simple setup.

Choose The Domain To Use

When you install Sym3 Web, it installs a certificate appropriate for hosting from localhost/Sym3Web. The localhost portion is the domain name – a name that resolves to a specific IP address using DNS.

In order to serve Sym3 Web over SSL, you’ll need a domain name that every machine that is going to connect to Sym3 can use that will resolve to the machine that has Sym3 Web installed. Note that you cannot use localhost for this purpose; it is a special name that means “the machine that the browser is running on”.

There are multiple ways to go about setting up a domain. If the machine is facing the open internet, you’ll have to purchase a domain from a provider. If the network involved is local however, you can configure your network or the clients to resolve a domain to the desired IP address. The specific details will depend on your particular network; contact your local network administrator. On the plus side, you do not have to purchase a domain name for the local network – you can simply choose a name that won’t collide with an existing domain.

At the end of this step you’ll need a domain name that resolves to the IP address of the machine that has Sym3 Web installed on each client you want to set up.

Acquiring A Certificate

If you’re configuring a machine on the open internet, purchasing a certificate for that domain will be the best option.

Otherwise, you’ll need to generate a self-signed certificate. These are certificates that instead of being signed by a CA who vouches that you are in control of your domain, that you generate yourself. A self-signed certificate doesn’t cost any money to generate, and you can generate as many as you need, but they come with the downside of requiring set up on every client machine.

Generating A Self-Signed Certificate Using PowerShell

On Windows you can use PowerShell to generate a self-signed certificate.

IMPORTANT: In the following code, replace DOMAIN_NAME that points to the machine where Sym3 Web is installed.

$pfxFilePath = "Sym3Web_Cert.pfx"
$cerFilePath = "Sym3Web_Cert.cer"
$pfxPassword = ConvertTo-SecureString -String "<PASSWORD>" -Force -AsPlainText
$certificate = New-SelfSignedCertificate `
    -Subject "Sym3Web" `
    -DnsName DOMAIN_NAME `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -NotBefore (Get-Date) `
    -NotAfter (Get-Date).AddYears(1) `
    -CertStoreLocation "cert:CurrentUser\My" `
    -FriendlyName "SSL Certificate for Sym3 Web" `
    -HashAlgorithm SHA256 `
    -KeyUsage DigitalSignature, KeyEncipherment, DataEncipherment `
    -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.1")

$certificatePath = 'Cert:\CurrentUser\My\' + ($certificate.ThumbPrint) 
Export-PfxCertificate -Cert $certificatePath -FilePath $pfxFilePath -Password $pfxPassword
Export-Certificate -Cert $certificatePath -FilePath $cerFilePath
Import-PfxCertificate -FilePath $pfxFilePath Cert:\LocalMachine\My -Password $pfxPassword -Exportable
Import-Certificate -FilePath $cerFilePath -CertStoreLocation Cert:\LocalMachine\Root

Trusting A Certificate

On each machine that you want to connect to Sym3Web on, copy the .cer and .pfx files you created when generating the certificate to the machine. From the same folder, in an administrator level PowerShell prompt, run the following:

$pfxFilePath = "Sym3Web_Cert.pfx"
$cerFilePath = "Sym3Web_Cert.cer"
$pfxPassword = ConvertTo-SecureString -String "<PASSWORD>" -Force -AsPlainText
Import-PfxCertificate -FilePath $pfxFilePath Cert:\LocalMachine\My -Exportable
Import-Certificate -FilePath $cerFilePath -CertStoreLocation Cert:\LocalMachine\Root

Make sure to close and reopen all instances of any web browsers you want to use to connect to Sym3 Web with.

Using A Certificate

Stop The Sym3 Web Service

Next Sym3 Web must be configured to use your certificate instead of the one it ships with. The first step is to stop the Sym3 Web Service. Run “Services” as an administrator, or run the following in an administrator level PowerShell prompt:

Stop-Service -DisplayName "Sym3 Web Service"

Update The Sym3 Web Configuration File

The Sym3 Web configuration file is located (by default) at the path C:\Program Files\Sym3\Sym3Blazor\appsettings.json. The first thing to do is to create a back up of that file.

cd "C:\Program Files\Sym3\Sym3Blazor"
copy appsettings.json appsettings_backup.json

If you want to revert the changes you made, replace the modified appsettings.json with appsettings_backup.json.

Next open appsettings.json in a text editor (like Notepad) running as an administrator. Find the section near the top that looks like this:

      "HttpsInlineCertFile": {
        "Url": "https://*:6001",
        "Certificate": {
          "Path": "C:\\ProgramData\\Sym3\\cert\\Sym3Auth.pfx",
          "Password": "<PASSWORD>",
          "AllowInvalid": "true"
        }
      }

Copy the Sym3Web_Cert.pfx file for your certificate somewhere on your system. Change the path next to “Path” to point to it, and change password to the password you used (<PASSWORD> in our example).

      "HttpsInlineCertFile": {
        "Url": "https://*:6001",
        "Certificate": {
          "Path": "C:\\Path\\To\\Sym3Web_Cert.pfx",
          "Password": "<PASSWORD>",
          "AllowInvalid": "true"
        }
      }

Save the settings file once you’re done.

Start The Sym3 Web Service

After you’re happy with the changes, you can restart the Sym3 Web Service. Again, either use the Services program or run the following in an administrator level PowerShell prompt:

Start-Service -DisplayName "Sym3 Web Service"

Testing Your Changes

Once the service has been restarted, testing it is relatively simple. Navigate to https://yourcustomdomain.com/Sym3Web on every client machine.

If you can connect without the web browser complaining, you’ve succeeded. If the browser complains, make sure that the browser was completely restarted after importing your certificate. The easiest way to ensure that is to completely restart the operating system. Other common points of failure are incorrect domain names, or just a incorrectly created certificate. Make sure the command you generated matched the command given.

Common commands of SSL port binding

The commands can be run from Command Promt (in administrator mode).

Command to display SSL binding

netsh http show sslcert

Command to display SSL binding on a specific port

netsh http show sslcert ipport=0.0.0.0:20021

Command to bind a certificate to a port

netsh http add sslcert ipport=0.0.0.0:port certhash=certificate thumbprint appid={87bf8460-651d-4f2c-876a-0286f8217041}

And then

netsh http add sslcert hostnameport=your.domain.com:port certhash=certificate thumbprint appid={87bf8460-651d-4f2c-876a-0286f8217041} certstorename=MY

(You should replace {87bf8460-651d-4f2c-876a-0286f8217041} with a new guid.)

Remove a binding

netsh http delete sslcert ipport=0.0.0.0:20021