SSL

Setting up 2-way SSL, .NET

866 views August 9, 2017 September 24, 2018 1

Before you start

This configuration description is not necessarily suitable for all types of production environments. It must rather be used as a guideline for the installation and configuration of the certificate, and not as a recipe to be followed to the letter. Depending on the way your server is set up, you might need to modify the code.

This recipe applies to Windows Server 2008 R2 and IIS 7.5 plattform.

Configuration process

The configuration process contains the following steps:

  1. Order certificate
  2. Install certificate
  3. Set up private key permissions
  4. Register certificateThumbprint in web.config
  5. Check certificate implementation

1. Order certificate

For details, please read this process description: Get a client SSL web service certificate.

A technical person sends an order to support@signicat.com and orders a production WS SSL certificate of the customer’s service. The order must contain the e-mail address and mobile phone number of the person responsible.

Signicat Operations will send an activation URL by e-mail, as well as an activation code by SMS to the mobile phone number provided. The certificate may be downloaded using this code. Note that his activation URL is valid for 15 minutes after it has been issued.

After the certificate is downloaded, another SMS with a decryption password for the certificate will be sent to the same mobile phone number.

2. Install certificate

At this point, installation of the SSL certificate may begin. The certificate should be installed in the Certificate archive on all application servers where Signicat.Basic.Service will be installed. During installation of the certificate, the installer will have to type in the decryption password.

 

 

3. Set up private key permissions

The next step is setting up private key permissions of the certificate. Select the SSL certificate, right click the context menu, and select All Tasks->Manage Private Keys as indicated in the image below.

Select ‘Add…’ in the “Permissions for … private keys” dialog box. Find the user that is running your service, select ‘Read’ permissions and add this user to the list of users that should have the correct permissions of the certificate.

There are several possible users that might be running your service depending on your configuration, for example:

  • “IIS AppPool\AppPoolName”, where “AppPoolName” is the name of your application pool
  • “NETWORK SERVICE”
  • “MyIISUser”

You can easily find out the name of the user running the service by looking at the ‘Details’ tab in Windows Task Manager.

4. Register certificate Thumbprint in web.config

In an ASP.NET project, there will always be a Web.config file available. Entries you add to this file can be read with WebConfigurationManager.AppSettings in any .net language. Also have a look at Microsoft’s documentation here: https://msdn.microsoft.com/en-us/library/610xe886.aspx. Dotnetperls also has a short introduction here: http://www.dotnetperls.com/appsettings

Configure the SSL certificate in web.config as follows:

<appSettings>
   <add key="CertificateThumbprint" value="- thumbprint of your WS SSL certificate --" ></add>
</appSettings>

 

If you open the certificate, for example from the explorer or the mmc-tool, you will find the thumbprint in the field list under the Details tab.

The thumbprint may contain special characters. To be completely safe, you should manually type in the thumbprint in the web.config file, not copy and paste it in.

5. Check certificate implementation

Write a web service request where the certificate is fetched from the Certificate Manager. Start with a web service call without the implemented certificate as below:

public ActionResult SendWebServiceRequest()
{
    var sslBinding = new BasicHttpBinding(BasicHttpSecurityMode.Transport);
    var productionEndpointAddress = new EndpointAddress("https://id.signicat.com/ws/documentservice-v2");
    using (var proxy = new DocumentEndPointClient(sslBinding, productionEndpointAddress))
    {
        documentactionrequest request = GetDocActionRequest();
        documentactionresponse response = proxy.send(request);
    }
    return View();
}

We will get a MessageSecurityExeption saying that the HTTP request was forbidden. This is because you are not authorized to access the id.signicat.com/ws/ domain.

When using your issued certificate you should get access. So we create an SSL binding and tell it to use a certificate for client authentication.

public ActionResult SendWebServiceRequest()
{
    var productionEndpointAddress = new EndpointAddress("https://id.signicat.com/ws/documentservice-v2");

    var sslBinding = new BasicHttpBinding(BasicHttpSecurityMode.Transport);
    sslBinding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Certificate;

    var certificateThumbprint = WebConfigurationManager.AppSettings["CertificateThumbprint"];
    var keyStore = new X509Store(StoreName.My, StoreLocation.LocalMachine);
    keyStore.Open(OpenFlags.ReadOnly);
    X509Certificate2 clientCertificate = keyStore.Certificates
                                                 .OfType<X509Certificate2>()
                                                 .First(c => c.Thumbprint == certificateThumbprint);

    using (var proxy = new DocumentEndPointClient(sslBinding, productionEndpointAddress))
    {
        proxy.ClientCredentials.ClientCertificate.Certificate = clientCertificate;

        documentactionrequest request = GetDocActionRequest();
        documentactionresponse response = proxy.send(request);
    }
    keyStore.Close();
    return View();
}

If you get a sensible response, your certificate is valid and 2-way SSL is implemented correctly.

Was this helpful?