Add a /.well-known/ Directory to an Application

I just encountered a scenario that required hosting a static file in a /.well-known/ directory of a website. Simple enough, right? You would think, but Microsoft has a knack for complicating things. I'll try to simplify the process for you by sharing what I learned.

What is the /.well-known/ directory?

The /.well-known/ directory is for publicly available, static files that contain site-wide metadata and is defined by RFC 5785. The purpose of the standard is to provide site-wide metadata without the overhead of using HTTP headers that are sent with every response and without cluttering the root directory with metadata files (like robots.txt).

How do I create a folder with a leading dot?

If you try to create a new folder in Windows with a leading dot, you'll receive an error: You must type a file name. But I don't want to type a file name! I want to type a folder name. Trying to understand Windows is futile. Fortunately, there's almost always a simple (albeit rarely intuitive) solution:

Type .well-known. for the folder name (yes, with a trailing dot). Voila! The trailing dot will fall off once the folder is created.

Getting IIS to play nice with your new folder

You may run into a couple issues with IIS actually serving your new static files. The first is authorization. Files in the .well-known directory must be accessible to everyone, even anonymous users. Second, if your static metadata file is extensionless (no .txt, .json, etc.), IIS will return a 404 Page Not Found error instead of returning the file. This is because the ExtensionLess handlers come before the StaticFile handler by default.

You can fix both issues with a single configuration file. Just add the following .well-known/Web.config to your project:

That's it!

With a little trick to create the folder and a single configuration file, you're all set. Happy coding!

Subscribe to 90 Degrees

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.