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?
/.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
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:
.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:
With a little trick to create the folder and a single configuration file, you’re all set. Happy coding!