Using client certificates in .NET part 7: working with client certificates in OWIN/Katana

Introduction

In the previous post we accomplished a couple of things. First we secured our demo Web API website with a client certificate. Second we enabled client certificates for it so that IIS doesn’t just ignore them. Finally we saw that the client certificate is also picked up in the customers controller when sent in code in a web request.

In this post we’ll start discussing how to add client certificate handling as an OWIN middleware component.

Make sure you open the demo Web API project in Visual Studio as an administrator.

What are OWIN and Katana?

We’ve taken up OWIN and Katana in various series on this blog lately so I won’t repeat that stuff here. Check out this page and scroll down to the “OWIN and Katana” section. In short Katana is a new light-weight web framework built by Microsoft. It is based on a specification called OWIN – Open Web Interface for .NET. The default MVC5 template in Visual Studio 2013 have elements of Katana and OWIN.

You can also check out the series dedicated to implementing a custom authentication method in OWIN starting here. We’ll take a similar approach here: first set up OWIN and then build the necessary components so that client certificate handling is picked up automatically.

OWIN has been around for a while now so I guess you’ve come across it in your .NET development work. If not then check out one of the series available on this blog to get to learn the basics.

This page has a number of posts dedicated to OWIN and Katana at a basic level. Whereas this page lists the posts on security. Check out the posts under the sections “Claims transformation posts” and “Web API 2”.

The main difference between this and previous series is that now we’re running on a local IIS server instead of the one built into Visual Studio. That requires a slightly different way of setting up OWIN correctly.

Adding OWIN

Our demo project has no OWIN installed at all currently. Therefore we’ll add the OWIN parts to begin with using the steps we saw in this series.

In order to integrate the OWIN pipeline into our application we’ll need to add a couple more NuGet packages. First off the OWIN version of System.Web:

Second let’s add the following NuGet package:

The Startup class

The Startup class is the entry point into a Katana-based application. It’s like Global.asax in a traditional ASP.NET app. If you go through the posts on OWIN/Katana referenced above you’ll know that by convention this entry point class must be called “Startup” and not “StartUp” or “startup” i.e. the casing is important. Another convention is that the Startup class must contain a method called Configuration which accepts an object of type IAppBuilder.

Therefore add a class called Startup to the root of the project:

public class Startup
{
	public void Configuration(IAppBuilder appBuilder)
	{
             Debug.WriteLine("OWIN is working.");
	}
}

…where IAppBuilder is located in the Owin namespace.

Put a breakpoint within the Configuration method. Start the Web API project and you’ll see that the break point is NOT hit. It turns out that it’s normal behaviour when debugging a web project in IIS when it is deployed on the local IIS web server the OWIN breakpoint won’t be hit within the Configuration method. In fact, if you place a breakpoint within Global.asax it won’t be hit either. However, it’s evident that the Application_Start() runs as the Web API routes have been correctly registered since we can call /customers. This behaviour is documented in one of the responses in this StackOverflow thread.

We’ll soon prove that the Configuration method is in fact executed despite the breakpoint not being hit.

Additional preparation and troubleshooting

There are a couple of things we can prepare for IIS to execute OWIN. Normally at this point we should be fine, i.e. installing the above NuGet packages and inserting a Startup class with a Configuration method should be enough, but there are times when IIS and OWIN just don’t agree with each other. Here comes a short check list for troubleshooting.

Make sure that the IIS website we created before run in the correct application pool. Also, the application pool must run on .NET 4 and Managed Pipeline Mode “integrated”. The application pool I set up for the demo web site is called mylocalsite.local – it was actually inserted automatically when I created the mylocalsite.local web site:

If your values are different then double click the application pool and set the correct .NET version and pipeline mode:

Then right-click the web site node in IIS, select Manage Web Site and then Advanced Settings… Check that the application pool points to mylocalsite.local:

Next, add the following setting to web.config under the system.webServer node:

<modules runAllManagedModulesForAllRequests="true" />

Finally we’ll add the following application setting to the appSettings section:

<appSettings>
    <add key="owin:AutomaticAppStartup" value="true" />
</appSettings>

That should be enough. Now let’s see if OWIN is in fact executed.

OWIN test

We’ll ask OWIN to write to a text file from the Configuration method. I created a file called owin.txt in the c:\tmp folder. Here’s the revised Configuration method:

public void Configuration(IAppBuilder appBuilder)
{
	File.WriteAllText(@"c:\tmp\owin.txt", "OWIN is here.");
}

Now if I run the web project I can see that the file was in fact written to:

We’ll continue in the next post.

You can view the list of posts on Security and Cryptography here.