How to Exclude the .well-known Folder From Redirection

The first step in requesting any SSL certificate is a validation step. This way, the Certificate Authority (CA) can validate that the certificate requested is indeed requested for a domain and hosting you have control over. This validation can be done in multiple ways, one of them being HTTP validation. For this, the CA will attempt to read a small text file located in the .well-known folder on your site.

By default we’ll create the .well-known folder on any new site created on your Bolt. As this folder will not only be used for new certificate requests, but also for renewals it’s important to make sure that this folder is accessible at all times. An example is the ordering process for Let’s Encrypt. For the Let’s Encrypt CA being able to validate the request it has to be able to check a validation file and if that file can’t be created inside an already existing .well-known folder or the URI gets redirected the validation will fail.

This validation step can fail for a multitude of reasons. These are some of the most common ones we encounter:

Requests get redirected or rewritten by a .htaccess file.

If you have rewrite rules in place, it’s wise to add an exclusion to those rules. This way we’ll prevent requests going to the .well-known folder from being rewritten. We can do so by adding the following rewrite condition directly above the rewrite rule in your .htaccess:

RewriteCond %{REQUEST_URI} !/\.well\-known/?.*

If you’re not using a rewrite, but a redirect instead the syntax is slightly different. The behaviour can be modified by using the following redirect instead of the normal one. By adding (?!\.well\-known\/) we exclude the .well-known folder from being redirected:

RedirectMatch 301 ^\/((?!\.well\-known\/).*)$ [THEIR_REDIRECT_TO_URL]

Your site is protected by a .htpasswd file

Another common case can be that you’re using .htaccess and .htpasswd to restrict access to your site using a username and password. In that case a .htaccess file has to be created inside your .well-known folder. Because it’s in a subfolder, it will override the settings made in your regular .htaccess file. All we need in that file is the following content:

Satisfy Any
Order Allow,Deny
Allow from all

How can I test this?

Once you’ve changed your .htaccess it’s always good to test if the changes actually work. A simple typo can easily mess these kinds of things up. The easiest way to test this is by uploading a small text file to the .well-known folder and see if you can access it through your browser. The contents of that file are not important, as long as you’ll be able to recognize it. Once the file has been uploaded you should be able to access it using the browser allowing you to see the content. That can look something like this: