How to Change the HTTPS Certificate in IIS Express

Visual Studio creates a self-signed certificate for your web application that allows you to access your site over HTTPS. As long as you do not need to change anything, this magical configuration works like a charm. Unfortunately, when you need to change something, it is incredibly hard and the magic turns into a curse.

 

What happens?

If there is no certificate for localhost, Visual Studio creates one for you. You notice this when a dialog like this one pops up and asks if you allow to install a certificate:

If you agree to install this certificate, it gets installed on your machine and IIS Express magically links that certificate to your application. This happens not only for localhost, but for any domain you configure in Visual Studio.

 

What is the problem?

If you delete this automatically generated certificate and create a new one in your own certification authority (CA), IIS Express will continue to work. Everything looks great, but it is not. If you check the certificate, you will notice that it still uses the old one. That will work up to a not defined point in the near future. Then everything breaks and you can no longer reach your application. The errors you get, if any, do not help because they are too general about SSL/TLS problems (like ERR_CONNECTION_RESET).

It took me a while until I found the post Working with SSL at Development Time is easier with IISExpress from Scott Hanselman. It turns out, IIS Express did not much change since 2011 and IisExpressAdminCmd.exe still works and can fix this problem as well.

 

How to change a certificate?

To make anything with certificates, you should open the certificate snap-in for mmc or Certlm.msc for your local computer. This tool allows you to create backups and import certificates.

1. Create a backup for the old certificate, including the private key.
2. Delete the old certificate for localhost.
3. Import your new certificate for localhost
4. Move the CA-Certificate to the folder Trusted Root Certification Authorities
5. Open the certificate for localhost and copy the Thumbprint
6. Open a Command Prompt (cmd) as administrator and go to the folder
   c:\Program Files (x86)\IIS Express
7. Map your application to the new certificate, replace PORT with the port of your application and THUMB with the Thumbprint from step 5:
   
   MS DOS

   IisExpressAdminCmd.exe setupsslUrl -url:https://localhost:PORT/ -CertHash:THUMB

   1	IisExpressAdminCmd.exe setupsslUrl -url:https://localhost:PORT/ -CertHash:THUMB

If you have multiple applications, you need to repeat step 7 for all of them.

If your certificate is in the personal certificate store and not in the local machine, you will get this error:

A specified logon session does not exist. It may already have been terminated.

To fix this, import your certificate into the local machine certificate store.

 

Conclusion

As so often, a magical configuration makes your developer life simpler until you hit an edge case for which you need to know the exact details. Then that magic turns into hours of debugging. I hope I can spare you those hours when you run into a problem of a missing certificate on IIS Express.