Why use HTTP Validation?
To request a certificate from Let's Encrypt (or any Certificate Authority), you need to provide some kind of proof that you are entitled to receive the certificate for given domain(s). Let's Encrypt support two methods of validation to prove control of your domain,
http-01 (validation over HTTP) and
dns-01 (validation via DNS). Wildcard domain certificates (those covering
*.yourdomain.com) can only be requested using DNS validation.
How to use HTTP Validation (on Windows)
When Let's Encrypt performs domain validation over http (known as an
http-01 challenge) they ask for a randomly named text file to be presented in the
/.well-known/acme-challenge path of your website. So they should be able to retrieve it at
If this step succeeds, you're all set to automatically complete HTTP validation of your domain. Once completed, Let's Encrypt marks your domain (associated with your account) as 'valid' and we can then proceed with requesting the final certificate.
How Http Validation works
With Certify The Web, we attempt to answer the http challenge using the built-in Http Challenge Server and as a fallback we use IIS (or whichever webserver is configured for port 80 http traffic, if any) by automatically detecting the website folder to write the challenge response file to, or by writing to the website path you provide in your configuration (for Apache etc).
On IIS this process presents a few challenges, which we attempt to fix automatically:
- The file does not have an extension (like .txt etc), so a static file handler usually needs to be configured to handle extension-less files
- Existing handlers for extension-less content may intercept the request and prevent access to the file
- If authentication (basic, forms etc) is enabled the access to the file will be restricted so this needs to be disabled
- Due to the above,
Asp.Net(and an app-pool) is generally required so that web.config can be supplied to override the configuration.
- Other customizations or app requirements for the parent website may affect configuration
So in the event that we cannot automatically provide the challenge response and fallback to IIS, we attempt to auto-configure the required configuration without modifying the configuration of the parent web application, this avoids app restarts for the parent application.
We create a file called configcheck in the
/.well-known/acme-challenge folder and
we cycle through a number of alternative web.config options and test each one. The testing process then makes a local http request to your website at
If the local request fails (perhaps because the local server can't resolve itself via DNS etc) and if proxy API support is enabled, the app asks the https://api.certifytheweb.com server if it can access the resource instead (which also has the benefit of being external, just like the Let's Encrypt server is).
Error 500, 404 or 403 (or other http error code)
The most common problem is that auto configuration has failed to determine the best config for your system. Different editions/distributions of windows have different defaults.
1 - Check the challenge folder exists
Check that test test configcheck file has been created at:
If not, check your folder permissions allow this folder/files to be created. If necessary, check the website root path is correctly mapped.
2 - Check you can access
If the file exists on disk but you get an error 404 (not found) accessing the file then you have a problem with mapping extensionless files to static content.
If you get an error 500 (server error), the web.config probably has a directive your server can't support. If the web.config has a
<clear/> directive, try removing it.
If you get an error 403 (access denied), your web application is denying access to the challenge response file, probably because the parent web application requires authentication. Your web.config in the
/acme-challenge/ folder should include the following directive:
<system.web> <authorization> <allow users="*" /> </authorization> </system.web>
In addition you may need to modify the web.config of the parent web application to allow access to the
<configuration> ... ... <location path=".well-known/acme-challenge"> <system.web> <authorization> <allow users="*"/> </authorization> </system.web> </location> ... ... </configuration>
The use of a web.config file to control web application configuration requires
Asp.Net to be installed alongside IIS.