Using LetsEncrypt with Umbraco

date_range  09 April 2016

Umbraco
Tutorial
ASP.Net

So who doesn’t like free stuff?

SSL certificates are hard to come by cheaply, or at least they were until LetsEncrypt came along. It’s a service that gives them out for nothing because it does all of it’s validation using a fully automated, client instigated protocol.

I found it very simple to use the letsencrypt-win-simple project to get certificates for simple sites and there are plenty of documentation on how to do that so I won’t go into any detail on that here.

When I turned it onto an Umbraco instance, however, I came across an issue whereby the authentication token could not be verified as the Umbraco pipeline was intercepting all the extensionless paths the ACME protocol uses. Reordering the httpModules as the error message suggested just caused 500 errors and Umbraco to not be invoked at all. Then I remembered that Umbraco uses OWIN and is relatively extensible in that department so I thought, “why don’t I just throw a little bit of middleware in there?”

So I came up with this:

It’s an OWIN configuration that inherits from the default Umbraco one that essentially, intercept any calls that start with the path .well-known, the container for the ACME verification tokens, checks whether a file exists on that sub path, if it does serve it up, otherwise invoke the rest of the pipeline. It needs to be placed before the call to base.Configure so that no other middleware is executed (which includes Umbraco) if a file is matched.

If you want to use it, create a Startup.cs file in your Umbraco project and update the owin:appStartup app setting in your web.config. The middleware requires the Nuget package Microsoft.Owin.FileSystems so we can access the mapped physical path of the app inside the OWIN pipeline. I tried using the UseFileServer extension method but got nowhere.

I’ve targeted this post at Umbraco but there’s no reason the meaty part of this, the map("/.well-known") call, wouldn’t work with pretty much any ASP.Net app that utilises OWIN.

comments powered by Disqus

chevron_left Archive