IIS Configuration

In IIS Admin go to Sites -> Default Website

• Click on the ’Bindings’ menu item on the far-right of the Admin console

• Add a binding for your Server Certificate on port 443 – leaving the IP Address range to ’All Unassigned’

From a development perspective, other than the two small URL changes and IIS Bindings, there isn't anything that changes for SSL operation, which is nice.·

• Important: You must restart the StifleR service for the changes to take effect.

And… you're done!

Introduction

This is a companion document to the StifleR Planning and Deployment Guide. It details the steps required to secure 2Pint Software StifleR components using SSL.

Securing StifleR is pretty straightforward, but as with anything involving Microsoft Security and Certificates, you need to get it exactly right or it just won’t play ball.

This document is intended to provide some details around this configuration and hopefully a more coherent description of setting up a certificate for self-hosting SignalR, the communication platform upon which StifleR is built.

Microsoft Configuration Manager and SSL

If you are using Microsoft System Center Configuration Manager (SCCM) and are interested in securing StifleR then it is likely that you have already secured SCCM. In this case your job is easier as you can reuse the Certificates that you have already put in place for SCCM.

What exactly do we need to secure?

A couple of areas of concern:-

The SignalR Endpoints (the StifleR Service that the Clients talk to), and the Web API which is used by the dashboards and/or scripts. See Securing the StifleR Endpoint for more info

Ports - By default, the StifleR Service listens on Port 1414 and the Dashboards on 9000. Certificates should be bound to these Ports in order to enable secure communication over these channels. See Running StifleR with SSL

Securing the StifleR SignalR endpoint is easy once you have your server certificate info. It is possible that StifleR may be installed on a server where IIS is NOT installed – for instance where the Dashboards are installed on a separate server. IIS is not a prerequisite for securing the StifleR Service.

Next Step - Binding Certificates to SSL Ports for SignalR/StifleR

Clients

On new and existing StifleR Clients, setting the SSL info is performed within the StifleR.ClientApp.config file which resides in the StifleR Client installation folder:

<add key="StiflerServers" value="https://SERVER.2PSTEST1.LOCAL:1414”/>

SignalR Dashboard URL Configuration

To configure the Web Page which will consume the SignalR service change the script URL that loads up the SignalR client library for the Dshboards or connections in your app.js file ( \Installation Path\StifleR\Dashboards\App\App.js) as follows:

app.value('backendServerUrl', 'https://2PINT.2PINT.LOCAL:1414');

app.constant('backendLocationServerUrl', 'https://2PINT.2PINT.LOCAL:9000/api');

where the URL strings are the local machine name to which the certificate is registered.

StifleR Service Endpoint

You'll also need to assign the Dashboards URL to your SSL URL as part of the SignalR startup routine that is used internally in the Stifler Server Service:

<add key="ListenToUrl" value="https://*:1414/" />

<add key="LocationWSListenToUrl" value="https://*:9000/"/>

This binds SignalR to the all IP addresses on Port 1414. You can also specify a specific IP address, but using * is more portable especially if you set the value as part of a shared configuration file.

Server Certificate

• See Appendix A for Self-Signed Certificate Creation.

Client Certificate (if using self-signed certs)

• If using a self-signed certificate the clients will need their own certificate.

Once you have the required Certificates, you can proceed to the next section.

If you don't have a full server certificate yet, but you'd like to test with SSL operations locally you can also use the IIS Admin interface to very easily create a self-signed certificate Here's how to do it:

• Go to the machine root of the IIS Service Manager

• Go to the Server Certificates Item in the IIS section

• On the left click Create Self-Signed Certificate

• Give it a name, and select the Personal store

• Click OK

• Job Done!

Copy the self-signed Certificate to the Trusted Root Certification Store

Once you have a self-signed certificate, you need one more step to make the certificate trusted so that HTTP clients will accept it on your machine without certificate errors. The process involves copying the certificate from the personal store to the trusted machine store. To do this:

1. From the Run Command - open Manage Computer Certificates (certlm.msc)

2. Go into Personal | Certificates and find your certificate

3. Drag and Copy (Ctrl-Drag) the certificate to Trusted Root Certification Authorities | Certificates

Although you now have a server certificate – you must now install an appropriate certificate on your clients so that they can trust the server certificate.

Self-hosting under HttpListener is wonderful and completely self-contained, but one of the downsides of not being integrated with IIS is that it cannot be aware of any certificates that are installed for IIS. This means that any certificates you want to use must be explicitly bound to a Port. If you can use IIS certificates and if you need to acquire a full certificate for use with a self-hosted application, going through the IIS certificate process is the easiest way to get the certificate loaded. If you require a certificate for local testing then it is quite easy to use the IIS self-signed certificate creation tool to create this component.

For now, let's assume that you already have a certificate installed into the Windows certificate store. In order to bind a certificate to the StifleR endpoint, you have to use the NETSH command line utility to register it on the machine (entered all on one line, split below for readability):

netsh http add sslcert ipport=0.0.0.0:1414 
appid={12345678-db90-4b66-8b01-88f7af2e36bf} 
certhash=cert_hash_thumbprint_goes_here

For every endpoint mapping you need to supply 3 values:

1. The ipport which identifies the ip and port

Specified as ipport=0.0.0.0:1414 where the zeros mean all ip addresses on port 1414. You can also specify a specific IP Address if required.

2. An AppID which is fixed for HttpListener Hosting

This value is static so always use appid={12345678-db90-4b66-8b01-88f7af2e36bf}

3. The certhash which is the Certificate's Thumbprint. Here's how to find the certhash

The certhash is the id that maps the certificate to the IP endpoint above. You can view this hash in the properties of the certificate in the Windows Certificate store. This is covered in the next section.

Once the above command has been run you can check if it was successful by checking the binding as follows:

netsh http show sslcert ipport=0.0.0.0:1414

which should give you a display similar to the following:

Repeat the above procedure for port 9000 (or other port used for the Web API)

• The IIS Certificate Manager OR

• The Windows Certificate Storage Manager

Using IIS to get the Certificate Info

If IIS is installed, then this is the easier option. From here you can easily see all installed certificates. The UI is also the easiest way to create local self-signed certificates.

To look up an existing certificate, simply bring up the IIS Management Console, go to the Machine node, then Server Certificates:

You can see the certificate hash in the rightmost column. You can also double click and open the certificate and go in the Details of the certificate. Look for the thumbprint which contains the hash.

Unfortunately, it is difficult to copy the hash from either of these interfaces, so you either have to copy it manually or remove the spaces from the thumbprint data in the dialog after copying it.

Note: When copying the thumbprint from Certificate Manager in the details window, a hidden character may get copied at the start. You can check this by using the cursor to move through it - delete it if it's there! Leaving it in can cause the "The Parameter is Incorrect" message despite everything looking fine at the command prompt. This was noted in testing on Windows 8 and Server 2012.

Self-signed certificates are great for testing under SSL to make sure your application works, but it's not practical for production apps as the certificate would have to be installed on every machine you'd expect to trust this certificate.

Once you go to production, especially public production you will need an 'official' certificate signed by one of the global certificate authorities.

The easiest way to do this is to purchase a full IIS certificate and install it in IIS. The IIS certificate can be used for self-hosted applications using the HttpListener so therefore it will work with a self-hosted SignalR or any HttpListener application.

Once the time comes to go live, simply register a new certificate through IIS, then use:

netsh http add sslcert

to register that certificate as shown above. A public SSL certificate, in most cases, is already recognized so no further certificate store moving is required. It should only require the netsh registration to tie it to a particular port and app Id.