Enabling SSL

By default Sym3 Web is installed to serve on the default http port (80). To secure Sym3 Web with TLS (SSL) so that it listens on the https port (443), a valid SSL certificate is required with the configuration changes below.

Please note that http alarm web services (basicHttpBinding) are not yet supported to allow SSL and so the default TCP binding (netTcpBinding) should be used instead.

It is recommended to also enable the secure web socket in Operator Server. This change will also require changes to the Sym3 Web Client configuration..

IIS Configuration

The default IIS configuration do not have a https binding. In IIS Manager, first add a new binding to the https port (linking the certificate) and then remove the http binding.

Sym3 Web Configuration

The file web.config is used to configure basic Sym3 Web server configuration. This file is located in the installation folder of Sym3 Web, typically at C:\Program Files\Sym3\Sym3 Operator\Sym3Web\.

The area of interest is around line 145 and starts with this commented warning:

<!--
Please note that both 'NO SSL' and 'SSL ENABLED' cannot be active at the same time. 
-->

Below this warning, a NO SSL and a SSL ENABLED section allows us to switch between the two configurations by simply commenting out the section that is not applicable.

Default Configuration

<!-- NO SSL -->
        <service name="BCS.Sym3.Web.WebService.BCSWebService" behaviorConfiguration="BCS.Sym3.Web.WebService.BCSWebServiceBehavior">
          <endpoint address="" 
                    binding="basicHttpBinding" 
                    bindingConfiguration="BCS.Sym3.Web.WebService.BCSWebServiceBinding" 
                    contract="BCS.Sym3.Web.WebService.Contracts.IBCSWebService">
            <identity>
              <dns value="localhost"/>
            </identity>
          </endpoint>
          <endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange"/>
        </service>
  
  <!-- SSL ENABLED -->
  <!--
        <service name="BCS.Sym3.Web.WebService.BCSWebService" behaviorConfiguration="BCS.Sym3.Web.WebService.BCSWebServiceBehavior">
          <endpoint address="" 
                    binding="basicHttpBinding" 
                    bindingConfiguration="BCS.Sym3.Web.WebService.BCSWebServiceBinding.SSL" 
                    contract="BCS.Sym3.Web.WebService.Contracts.IBCSWebService">
            <identity>
              <dns value="localhost"/>
            </identity>
          </endpoint>
          <endpoint address="mex" binding="mexHttpsBinding" contract="IMetadataExchange"/>
        </service>
  -->

SSL Enabled Configuration

<!-- NO SSL -->
<!--
        <service name="BCS.Sym3.Web.WebService.BCSWebService" behaviorConfiguration="BCS.Sym3.Web.WebService.BCSWebServiceBehavior">
        <endpoint address="" 
                    binding="basicHttpBinding" 
                    bindingConfiguration="BCS.Sym3.Web.WebService.BCSWebServiceBinding" 
                    contract="BCS.Sym3.Web.WebService.Contracts.IBCSWebService">
            <identity>
            <dns value="localhost"/>
            </identity>
        </endpoint>
        <endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange"/>
        </service>
-->
<!-- SSL ENABLED -->
        <service name="BCS.Sym3.Web.WebService.BCSWebService" behaviorConfiguration="BCS.Sym3.Web.WebService.BCSWebServiceBehavior">
        <endpoint address="" 
                    binding="basicHttpBinding" 
                    bindingConfiguration="BCS.Sym3.Web.WebService.BCSWebServiceBinding.SSL" 
                    contract="BCS.Sym3.Web.WebService.Contracts.IBCSWebService">
            <identity>
            <dns value="localhost"/>
            </identity>
        </endpoint>
        <endpoint address="mex" binding="mexHttpsBinding" contract="IMetadataExchange"/>
        </service>

Web Client Configuration

In Sym3 Web, go to Settings -> Operator Server and enable “Enable Secure Websocket” if it isn’t already, then restart Operator Server.

Next, the web client has to be configured to use the secure websocket. The file config.prod.json is used to configure the Sym3 web client, and is typically located at C:\Program Files\Sym3\Sym3 Operator\Sym3Web\Client\assets\config.

The top of the file looks like this:

{
    "sym3Server": {
        "sslEnabled": false,
        "server": "*",
        "port": 27000
    },

Set sslEnabled to true, and port to your secure web socket port (28000 by default). Refresh any web client instances to have them use the new settings – the server does not need to be restarted.

The websocket must be bound to a certificate. This can be done from the command line (in administrator mode) with these commands:

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

And then

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

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

If when you connect to the web client your browser tells you the connection is insecure, your certificate is likely invalid and the web client is unlikely to work. Make sure it is not expired, and you are connecting using the correct domain name.

Web Client & Alarms

If the Sym3 web client is being served via HTTPS, the alarms also need to be served over HTTPS. In Sym3Web, go to the Settings -> Alarm Server and set Web Service HTTPS to True. Return to the config.prod.json (C:\Program Files\Sym3\Sym3 Operator\Sym3Web\Client\assets\config) and set sslEnabled to true so that the section looks like this:

    "sym3Alarms": {
        "sslEnabled": true,
        "server": "*",
        "port": 20013
    },

The certificate must be bound to the alarm server for the appropriate port. Assuming the port for the alarms is 20013, run this command from a command prompt in administrator mode:

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

And then

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

After making these changes, make sure the alarm server is restarted and any web client instances are reloaded.