Configure IIS to use your self signed certificates with your application including IIS client certificate mapping authentication

I’m now assuming that you read my previous post about how to create self signed certificates for development and it might’ve left you thinking “Yay great! ….But how do I actually use them?”. This blog post will take you step by step through the manual process of configuring IIS on your PC or Windows Server to use your self signed certificates together with IIS client certificate mapping authentication.

Please note that I in my examples I use my localhost hosting and a random domain name but you can do this on your real server’s IIS if you have a static IP address from your internet service provider or your domain hosting company as well as configured your firewall, router etc. correctly where finally you can point your domain name to your that address. BUT I won’t recommend either together with self signed certificates unless your clients/users are willing to receive and install your self-signed root and client certificate. A good example of this is in a closed intranet where you have access to all the end-user’s computers because then you can install the certificates on their machines, which is necessary if you don’t want your users to get a big fat warning about trust issues with your self signed server certificate. If you are looking for a commercial production-worthy solution you should purchase your certificates instead of self signing. So now we have that out of the way I’m using a PC with Windows 8.1 Pro, IIS 8.5 and Visual Studio Premium 2013. (I’ve also tested with a Windows Server 2012 R2 Hyper-V VM on my PC).

Installing IISIf you haven’t already installed IIS on the machine that will act as the hosting server, please do so by pressing the Windows button for a PC and search “Turn Windows features on or off” (or go to Control Panel and search). Check Internet Information Services and the following childnodes.(If you are running on .NET 3.5 you need to check the .NET Extensibility 3.5 and ASP.NET 3.5)

For Windows Server 2012 go to the Server Manager Dashboard ➜ Click add roles and features ➜ Choose role-based or feature-based installation and go next ➜ Select the server ➜ Enable the server role called Web Server (IIS) and following child elements

Also make sure Application Development is checked with the following childnodes

Click OK and let Windows install.

Creating our sample project
For the sake of this demo we’ll create a really simple mini application that we will be hosting in the local IIS. (You can also just fork mine directly at Github)

In Visual Studio, create a new empty web application and reference web api

We’ll just need a reeeeaally simple controller:

1 2 3 4 5 6 7 8 9 10 11 12

using System.Web.Http;   namespace IISWithCertificatesSample.WebApi.Controllers {     public class CatsController : ApiController     {         public IHttpActionResult Get()         {             return Ok("A lot of cats meowing for food");         }     } }

You should now be able to run both routes (F5) and surf to the localhost url with /api/cats (mine looks like http://localhost:62172/api/cats). Awesome, lets host this application using our local IIS.

NOTE: We will no longer be running the application directly from Visual Studio (F5) which is set to use IIS Express.

Configuring IIS
Open your IIS Manager (Windows button + search for it). Add a new website and application pool with our sample application. (Right-click Sites ➜ Add Website) The path needs to be the folder where your web site documents are located, so if you have published your website point the path there. I’m just going to use the direct path to the project in Visual Studio for this very simple example.

Now let’s locally host this site by specifying the host name AKA. your domain name.

Since I’m just hosting locally I need to add the site to my local hosts file in order to bind my localhost IP address with the host name. This is done by running notepad as administrator and opening the hosts file in the path: %systemroot%\System32\drivers\etc

Adding the following at the end: 127.0.0.1 yourdomain.com www.yourdomain.com

Now whenever I surf to yourdomain.com and www.yourdomain.com on my machine it will resolve the site with my newly added bindings to the 127.0.0.1 IP address (which is localhost’s IP).

Let’s add the www. binding to your site in the IIS Manager as well

Surf to the domain name you set up in the bindings with or without www. and add the ending /api/cats and you should get the meowing cats. (If not try emptying the cache)

IMPORTANT: This is ONLY going to happen on the local machine because we altered the hosts file to redirect our requests of the domain name we added to the localhost IP address. It is meant for development and to be able to test your changes before deploying them to your real web hosting server.

Securing the server with SSL
Now we want to secure the cats by adding a SSL certificate to our Server.
In your IIS Manager go to your server (The top of the tree to the left) ➜ Scroll down and double-click Server Certificates.

(If your self signed certificate is already here, jump ahead to the bindings steps)

We need to import our self signed server certificate in order to enable https communication with SSL, so click Import…

Click the … and find your .pfx file, fill out the password (the -po parameter in your command batch file) and click OK

Your certificate is now added

Double-click the newly added cert to verify that it is trusted (Your self signed certificates were added to the correct stores in my previous post, so again: read it if you are lost right now ;-))

So far, so good! Now we can add the https binding, the same way as before but choose https with port 443, your domain as the host name and find your self signed certificate in the drop down list

Check the Server Name Indication box which enables our server to have multiple certificates installed on the same IP address by sending the hostname with the first stage of the SSL handshake. Repeat the same steps to add SSL for www.yourdomain.com but with a certificate where the CN name matches the domain name or a wildcard certificate

Our bindings are complete for now

Tadaa, you can now use https://yourdomain.com/api/cats and https://www.yourdomain.com/api/cats

NOTE: Firefox doesn’t use the Windows certificate store, so you will have to add your root CA manually. Go to Firefox Settings ➜Options ➜ Advanced ➜ View Certificates ➜ Authorities ➜ import your CARoot.cer file

IIS Client Certificate Mapping Authentication
We have now been through the uses of the root and server certificates and you are probably wondering what to do with the client certificate we also created in my previous post. This is for situations when we for example need to authenticate clients without a user login and password approach but rather want the server to ask the client to show it’s certificate and if it’s the correct one the client is allowed in. This can be done with a Many-To-One or a One-To-One mapping and I will show you how to do both manually in the IIS Manager.

First we need to install the feature, so bring up the “Turn Windows features on or off” again and install the following

We’ll tell our server to require a SSL certificate from the client

Then we need to configure the server to know which client certificate it needs to validate, so go to the Configuration Editor and choose the iisClientCertificateMappingAuthentication section (you can also enter the path system.webServer/security/authentication/iisClientCertificateMappingAuthentication into the Section field)

Many-To-One MappingsIf you want to map multiple client certificate to a single user this approach is what you need. You can also share client certificates like this by installing the client certificate (and the CA Root, since we are self-signing certificate) on other users on whichever machine to gain access as long as the client certificate matches the rule criterias of the mapping. It would for example be useful in a situation where you would want all users in an organization to gain access through a single user mapping.

Enable the client certificate mapping authentication

To add a mapping click the … of the manyToOneMappings

Here you add the users that you want to grant access.

Fill out the properties for a mapping and repeat for each user you want to configure for access or denial. Remember that you need the client certificate and root CA certificate installed on all the user’s mmc.

IMPORTANT: In order for this to work you need to enter a valid username and password and since my computer is the server, the credentials will be my Windows username and password.

Now we need to create some rules to go with this mapping so the server can determine if a client is allowed in or not. It’s a  so click on the rules property and the … button

I will add one rule as an example where the server will check the client certificate to see if it’s signed by the correct CA root. Go ahead and add more rules for more safety, please visit the IIS Many-To-One Mapping reference for more documentation.

Remember to apply the changes in the IIS Manager, so close the rules and mappings windows and click Apply

Open a new incognito browser window to make sure to start from a clean slate cache and cookie-wise and enter your url with the /api/cats and see the browser prompting you for a certificate. Choose the ClientCert and click ok to gain access to the cats.

If this is not working make sure that your client certificate is in your CurrentUser/Personal store as well as in your browser’s certificate store. If yes, then go to Control Panel ➜ Internet Options ➜ Content and click Clear SSL state.

Open a new incognito windows and try again, your browser should now prompt you for the client certificate.

NOTE: Remember as I explained earlier on, Firefox has it’s own certificate store so you need to import the client certificate into “Your Certificates” in order to use this.

One-To-One Mappings
Let’s walk through the one-to-one mappings as well. This approach means that we need an individual client certificate for each user mapping. You can either disable the many-to-one mapping and use the same certificate and user or create new ones. Go back to the Configuration Editor and open the iisClientCertificateMappingAuthentication section again. Click the … of the oneToOneMappings.

To add the mapping to the certificate we need to export the public key of the client certificate file. You can export this from your Machine Management Console (press the Windows button and search for mmc) Snap-in the Local Machine’s Certificate’s personal store and export the client ssl certificate you want to use without the private key in the base64 format.

Right-click the newly exported certificate and open with notepad. Remove all the line-breaks in the certificate itself.

Now copy that into the certificate property field of the mapping and fill out the rest

IMPORTANT: In order for this to work you need to enter a valid username and password and since my computer is the server, the credentials will be a Windows username and password.

Again, remember to apply the changes.

And there you go, try it out and when prompted choose the certificate you mapped to the user you just mapped.