The “.well-known” directory on webservers (aka: RFC 5785)

Mattias Geniar, Wednesday, March 16, 2016

I first came across the concept of the directory named '.well-known' when automating Let's Encrypt, the free SSL certificate authority. It didn't strike me as abnormal to have a validation happen via an HTTP or HTTPS GET request. Those Let's Encrypt validation URLs usually point to site.tld/.well-known/acme-challenge/random-key.txt.

At first I thought this was just the random URL used by Let's Encrypt, but today I learned there's more to it. Allow me to introduce RFC-5785.

It is increasingly common for Web-based protocols to require the
discovery of policy or other information about a host ("site-wide
metadata") before making a request.


When this happens, it is common to designate a "well-known location"
for such data, so that it can be easily located.


To address this, this memo defines a path prefix in HTTP(S) URIs for
these "well-known locations", "/.well-known/".


The directory location /.well-known isn't a coincidence, it's the result of a carefully considered RFC. This directory can be used for all kinds of information discovery.

For instance, Let's Encrypt uses a subdirectory called /.well-known/acme-challenge/, where 'ACME' stands for Automated Certificate Management Environment.

There's a Do Not Track policy (DNT) that uses a similar file in that directory for validation: /.well-known/dnt-policy.txt.

There are a couple of webservers configurations that prevent opening directories that start with dot ".". The reasoning behind it is that it might give away sensitive information, like a .git or .svn directory (which probably shouldn't even be on your webserver in the first place).

However, this RFC for the .well-known directory make it clear that at least this particular directory should be allowed to be accessed (not in a directory-listing sense, but for direct file access).

Hi! My name is Mattias Geniar. I'm a Support Manager at Nucleus Hosting in Belgium, a general web geek & public speaker. Currently working on DNS Spy & Oh Dear!. Follow me on Twitter as @mattiasgeniar.

Share this post

Did you like this post? Will you help me share it on social media? Thanks!


Nicolas Hoizey Thursday, March 24, 2016 at 12:33 - Reply

I already use a .well-known directory for some files, it helps keep the site root clean:

But I also have a few rewrite rules for browsers looking for some of these files on the root:

Mattias Geniar Saturday, December 10, 2016 at 09:48 - Reply

Sure, no harm in doing so. Delete it if you want.

Mohammad Shahidi Tuesday, June 18, 2019 at 16:55 - Reply

Hello. Thanks a lot for the valuable information you gave us on “.well-known” directory. Me too came across the concept when automating Let’s Encrypt and I was wondering what it is. And now I got it from your good post: short but straightforward.

Leave a Reply

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

Inbound links