LetsEncrypt with Umbraco – serving static, extensionless URLs within an Umbraco installation.

Situation; you have a bunch of domains and subdomains which are secured using Letsencrypt. by default, Letsencrypt will try to put a static, extensionless file like named e.g.  “jCk1zSkjsiuJHrmnSFnxdvkhkjnnNNkjsaaRo” in a “/.well-known/acme-challenge/” subfolder of the site root.

If that file isn’t reachable and browsable – the Letsencrypt acme servers won’t authenticate your domain. Letsencrypt will warn you at this point and recommend re-ordering the IIS Handler Mappings to promote the “StaticFile” handler above the three “ExtensionlessUrl” handlers.

However even if you reorder the handlers, you’ll still see a 404-page not found error when browsing directly to the static file’s URL e.g. http://yourdomain/.well-known/acme-challenge/jCk1zSkjsiuJHrmnSFnxdvkhkjnnNNkjsaaRo

If you check the logs in your Umbraco /App_Data/Logs directory, you may see “Status code is 404 yet TrySkipIisCustomErrors is false – IIS will take over”

IIS won’t log anything useful though.

What’s happening can only be seen once you tell Umbraco not to pass error handling onto IIS; so edit /Config/umbracoSettings.config and set trySkipIisCustomErrors=true

This will force Umbraco to print its own, more informative error, confirming the problem:

No umbraco document matches the url ‘/.well-known/acme-challenge/jCk1zSkjsiuJHrmnSFnxdvkhkjnnNNkjsaaRo’

Finally; to fix the problem and exclude the /.well-known/acme-challenge/ directory from Umbraco’s control, you need to edit Umbraco’s main Web.config file, and add the following:

<add key=”umbracoReservedPaths” value=”~/umbraco,~/install/,~/.well-known/,~/.well-known/acme-challenge/” />

The next time you load http://yourdomain/.well-known/acme-challenge/jCk1zSkjsiuJHrmnSFnxdvkhkjnnNNkjsaaRo in a browser, you should see a plain-text string of json that the acme server needs to authenticate your control of the domain for which you’re requesting the certificate.

Retrying the Letsencrypt client at this point should be successful.

Have a coffee and don’t forget to revert the logging and error handling changes you just made.


4 thoughts on “LetsEncrypt with Umbraco – serving static, extensionless URLs within an Umbraco installation.”

  1. Man, you saved my day… I had a feeling Umbraco had something to do with it, because everywhere on the internet people were resolving extensionless static files the same way, which only didn’t work me! 🙂 Thank you a lot, man 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *