Visual Studio 2017 - Resolving SSL/TLS Connections Problems with IIS Express

Building ASP.NET web projects that enable HTTPS helps ensure website authenticity, the integrity of the data exchanged between the client and the website, and protections over users' interactions with the website from prying internet service providers and third-party snoopers.

Using HTTPS for production websites relies on trusted public key certificates that are issued by certificate authorities. These certificates are issued by specialist commercial enterprises or nonprofit organizations like CACert.org and Let's Encrypt.

Developers using Microsoft Visual Studio to build websites can create a local certificate to provide HTTPS functionality. Visual Studio includes IIS Express, a "lightweight" version of Internet Information Server designed for the needs of developers.

In particular, IIS Express:

• Does not require Administrator rights on the local machine, making it convenient for developers working in an enterprise environment where the user rights on their development workstation are restricted.

• Runs automatically when the web project is run from Visual Studio and shuts down when stopped from Visual Studio or the browser is closed.

*Supports edit and reload and other debugging and development features included with Visual Studio.

• Can be run from the command line without requiring Visual Studio to be running.

• Displays the full HTTP server log in the command window in real time as IIS Express serves requests.

Note that IIS Express 10 is the current version and ships with Visual Studio 2017 (all editions, including Community). An IIS Express 10 download is also available separately. IIS Express documentation on docs.microsoft.com and IIS.net dates from 2010 to 2013 and covers IIS Express versions 7.5 and 8.0. Experience indicates that much of the information still applies to version 10.

When IIS Express is installed with Visual Studio, the installation process creates an IIS Express Development Certificate that serves as the HTTPS certificate for websites running on IIS Express on the local machine. This certificate has an expiration date that is five years from the date on which the certificate is created.

Using HTTPS to connect to a website running in IIS Express will fail when the IIS Express Development Certificate is improperly bound to the port or the certificate has expired or the certificate has been improperly installed.

Common browser error messages for HTTPS failures include the following:

The specific error message you receive will depend on the browser version you are using for debugging.

This guide provides one approach to resolving SSL/TLS connection problems experienced when running ASP.NET web projects using the IIS Express development web server. It is oriented to the current version of Visual Studio (as of the time of writing). It has not been tested for compatibility with prior versions of Visual Studio or IIS Express.

Most importantly, this guide is intended for developers who are using automatic port configuration for their web projects. Visual Studio assigns unique ports to projects for both HTTP and HTTPS on the local machine (localhost) and keeps this information in sync in various places. Unless you have a compelling reason to assign specific ports, life is more convenient if you leave this alone.

This guide is also based on the automatic creation of a self-signed certificate for use in development. If you have any reason to use a specific certificate, the instructions in this guide will not apply to you.

In addition, we have no way of knowing if your system is configured in a way that might adversely affect the results of following the procedures documented here or if these instructions are incomplete or inaccurate for a specific configuration.

• Visual Studio 2017 (version 15.3.4 or higher)
• IIS Express 10
• Google Chrome version 60+ (if Chrome is being used for debugging)

Before getting started, you may want to do the following to ensure you can recover from any unforeseen consequences:

• Check-in your code and publish it to a remote repository.

• Create a current system restore point.

• Create a current backup or sync your local data folders with your cloud drive(s).

It's always good to have a current backup, and there are multiple services that make doing so easy and inexpensive.

PluralSight and the author disclaim all liability for the reliability, accuracy, and effect of following these instructions. Use at your own risk.

As noted above, there are a few constraints on the use of these instructions:

• IIS Express will automatically assign port numbers.

• localhost is the server name for the IIS Express host (not the machine name).

• Although IIS Express can host or php projects, this guide does not address them.

Google introduced a key change in the way it handled SSL certificates in version 58. Working with Microsoft, they resolved differences in version 60. Many recent problem reports associated with SSL debugging with Visual Studio and Chrome come from this issue.

Before proceeding with this solution, check your Chrome version number and be sure it is 60 or higher:

Menu > Help > About Google Chrome (Alt > down arrow > e > g)

IIS Express reserves a limited number of ports for automatic SSL binding. Be sure you are running (or attempting to run) SSL connections on ports in the following range:

If you are running an up-to-date version of Chrome (or Edge or Firefox or Opera) and you are using a valid SSL port number and you are still getting errors, proceed with the process presented in this guide.

The following instructions are based on the premise that you want your development environment to automate as many routine, repetitive tasks as possible. Accordingly, the instructions intend to generalize and automate Visual Studio and IIS Express.

These instructions are also based on the premise that a clean slate is often the best way to resolve a problem and prevent future problems. Accordingly, these instructions are intended to provide a complete reset of your IIS Express Development Certificate by removing any currently existing certificates and creating a new one that will bind successfully to the appropriate ports.

Author's note: If your development environment doesn't meet the prerequisites for this solution, or you have other constraints that prevent you from following these instructions, I hope you'll still be able to derive some value from the information presented below.

The first step in the repair process is to clear out existing certificates for localhost. You may want to create a system restore point and a recovery drive before beginning.

Open a command window (Run As Administrator).

Open Microsoft Management Console: type MMC at the command prompt and press Enter.

Add the Certificates snap-in.

When you click Add you will be presented with a dialog box to select the account:

Select My User Account and click Finish.

Under Console Root / Certificates - Current User / Personal / Certificates locate any certificates for which the value in the Issued To column is localhost (under most circumstances there shouldn't be any). Select the certificate(s), right-click, and select Delete.

Under Console Root / Certificates - Current User / Trusted Root Certification Authorities / Certificates locate any certificates for which the value in the Issued To column is localhost. Select the certificate(s), right-click, and select Delete.

There will be a long list of certificates. Some of the certificates issued to localhost may be current or expired. Delete all of them: the goal is to remove potential conflicts with the results of the IIS Express repair process described below.

Close Microsoft Management Console.

Re-open Microsoft Management Console (from the command prompt in the command window you previously opened) and add the Certificates snap-in. This time, select Computer account at the Certificates snap-in dialog box and click Finish.

You will be presented with a dialog box:

Select Local Computer and click Finish.

Under Console Root / Certificates - (Local Computer) / Personal / Certificates locate any certificates for which the value in the Issued To column is localhost. Select the certificate(s), right-click, and select Delete.

Under Console Root / Certificates - (Local Computer) / Trusted Root Certification Authorities / Certificates locate any certificates for which the value in the Issued To column is localhost. Select the certificate(s), right-click, and select Delete.

Close Microsoft Management Console.

This process uses the IIS Express installer to generate a certificate for localhost and get it installed in the right place, then it uses Visual Studio to bind the certificate to the ports used by IIS Express. These steps only need to be executed once to install the certificate. After installation, each subsequent web project that uses SSL will be assigned an SSL port bound to the certificate.

From the Windows desktop, open the old-style Control Panel:

Note: you must use the old-style Control Panel. Windows Settings / Apps will not give you the appropriate context menu option.

Select Programs > Programs and Features and find IIS Express in the list of programs.

Right-click on ISS Express and click Repair. Answer "Yes" to any confirmation dialog boxes that appear.

The IIS Express installer will chug through the repair process and return you to the list of Programs and Features when it's finished.

Open Microsoft Management Console again and select the Certificates snap-in for the Local Computer account.

Under Console Root / Certificates - (Local Computer) / Personal / Certificates you should see a new certificate Issued To localhost with a description of IIS Express Development Certificate and an Expiration Date 5 years minus 1 day from the current date.

Close Microsoft Management Console (leave the command window open, though - you're not done with it).

Open Visual Studio and open the solution containing the web project you'd like to run in IIS Express with SSL.

Verify that the project is configured to use SSL by selecting the project in Visual Studio Solution Explorer and pressing F4. You should see a panel similar to the following:

Verify that SSL Enabled is set to True.

If you are working with a web project for which SSL has not yet been enabled, set SSL Enabled to True. Visual Studio will assign a unique SSL port number in the appropriate range (44300 - 44399) dynamically and set the SSL URL property.

Make note of the value for SSL URL.

Open the project properties by selecting the project in Solution Explorer and:

• Press Alt + Enter, or

• Right-click and select Properties... from the context menu, or

• Select Project > project name Properties from the menu bar.

Select the Web tab and enter the value from SSL URL in the step above in the Project URL field:

Save your changes: File > Save (Ctrl + S).

You may be shown a dialog box like the following if you haven't run the web project using the port before:

Select Yes.

Run the project in Visual Studio:

You will be presented with a dialog box:

Select Yes.

This enables Visual Studio to trust the SSL certificate you created using the IIS Express Repair process, which is installed in:

Certificates - (Local Computer) / Personal / Certificates

You will be presented with another dialog box:

Select Yes.

This will take the certificate that you created and bound to the port selected in the Project Development Server Properties (F4) and the Project Properties (Alt + Enter) and install it in:

Console Root / Certificates - Current User / Trusted Root Certification Authorities / Certificates

The project should run (unless you have build or runtime problems otherwise) and appear in the browser like below:

Note the following characteristics:

• The green lock icon and "Secure" is visible to the left of the URL (different indicators are used in other browsers).

• The protocol is indicated as https.

• The port being served is the automatically generated one for SSL connections.

Examine the values for running applications in IIS Express:

Find the IIS Express Tray Icon, open the context menu (right-click), and select Show All Applications.

This will display the IIS Express Running Applications dialog box:

Note that IIS is running the website on both the http and https ports specified in the Project Development Server Properties.

Stop the project in Visual Studio. The browser window should close and IIS Express should stop running (the tray icon will disappear).

As a final step, you can verify the installation of the new IIS Express Development Certificate.

Open Microsoft Management Console and add the Certificates snap-in. Select the Current user account.

Navigate the folder structure to:

Console Root / Certificates - Current User / Trusted Root Certification Authorities / Certificates

You should see that a localhost certificate has been installed:

Note that the localhost IIS Express Development Certificate created by the IIS Express Installer repair process now appears in this list with a special icon:

Although the process for repairing IIS Express SSL certificate binding problems with Visual Studio web projects is somewhat lengthy, it is a reliable and repeatable way to reset this functionality using built-in processes in the IIS Express installer and Visual Studio. This is important because installing the certificates and binding them correctly is not just a matter of copying the certificates to the right place in a folder structure.

SSL certificate port binding, an essential part of the process of configuring SSL for a web project, requires a number of precise steps these build-in processes handle behind the scenes. Using Visual Studio's automatic SSL port assignment eliminates the need to execute a number of steps to bind an SSL certificate to the SSL port for each new web project.

For best results, be sure you are using the latest versions of Visual Studio 2017 and IIS Express.

PluralSight and the author disclaim all liability for the reliability, accuracy, and completeness of the information presented by third-parties.

Handling URL Binding Failures in IIS Express is an article, from 2011, that provides much useful information on using a custom SSL certificate and custom port bindings with IIS Express. It is of more help to those looking to customize their IIS Express configuration than those looking to resolve problems with their configuration.