Using SSL and client certificates when debugging Commerce Engine

When you install Sitecore Commerce 9 using SIF all the connections use https as the transport protocol and Client Certificates are used for authentication between Sitecore Commerce Connect and the Commerce Engine.

SSL Encryption and decryption are handled by IIS and it's automatically set up for you or you configure it using IIS Administrator.

But when you're building a new plugin and you want to debug or test it, you use the Kestrel http server and you have to set up SSL in Kestrel.

Luckily the sample Commerce Engine Solution has already been set up to use https and client certificates, you just have to configure it.

Configuration of the SSL certificate and the client certificate to use is done in config.json which is located in the wwwroot folder of the Sitecore.Commerce.Engine project.

Configuring SSL

You'll find the following in config.json:

    "UseHttpsInKestrel": true,  
    "SslPort": 5000,
    "SslPfxPath": "wwwroot/localhost.pfx",
    "SslPfxPassword": "sitecore"

Here you specify that you want Kestrel to use HTTPS, which port to use, the location of the exported SSL certificate to use and the password used to save the SSL certificate.

These are the default settings you get out of the box. What's missing in the box is the exported certificate, obviously because it's environment specific.

So you will need to export the SSL certificate. To do this, you can use Powershell. Execute the following commands:

$pwd = ConvertTo-SecureString -String "sitecore" -Force -AsPlainText

This creates a variable containing sitecore in a secure string which you use to export the certificate.
Next you need the thumbprint of the certificate you want to export.

Get-ChildItem -Path cert:\localMachine\my\

This lists all the certificates in the my store. Look for the thumbprint for the localhost certificate.

Next, export the certificate:

Get-ChildItem -Path cert:\localMachine\my\<thumbprint of localhost certificate> | Export-PfxCertificate -FilePath C:\localhost.pfx -Password $pwd

Lastly, copy the localhost.pfx file from c:\ to the wwwroot folder of the Sitecore.Commerce.Engine project in the SDK and you're ready to go.

Configuring Client Certificates

There is a separate section for configuring client certificates in config.json:

  "Certificates": {
    "Certificates": [
      {
        "Thumbprint": "F1D8349D784BF672B99103C1C204A57556DD263A",
        "DefaultRoles": [
          "sitecore\\QA",
          "sitecore\\Commerce Business User"
        ] 
      }
    ],
    "CertificateHeaderName": "X-CommerceEngineCert"
  } 

Remove the thumbprint that is there and replace it with the thumbprint for your environment. You can find this thumbprint in C:\inetpub\wwwroot\CommerceAuthoring_Sc9\wwwroot\config.json. Look for the "Thumbprint" entry and copy it's value.

If you configure these two things you are ready to debug and test your commerce engine in Visual Studio.