Path Rules for /.well-known/
The Restriction
On a domain that isn’t a wildcard (*.example.com), the Path Rules > Allow and Path Rules > Block pages refuse any path containing well-known, with or without the leading dot, for every match type.
Why It Exists
Your SSL certificate renews by answering a check at /.well-known/acme-challenge/, and the WAF answers that check itself. An allow rule sends the check to your application instead, and a block rule answers it with a 403. Either one stops the renewal from verifying your domain. The certificate then expires without being replaced, and visitors see a security warning.
Allowing One Specific File
Services such as Apple Pay and Android App Links read files under /.well-known/. Most of these files need no rule at all.
If your WAF logs show one of these files being blocked, add an allow rule with the Contains match type and the file name or its subdirectory, leaving out /.well-known/. For /.well-known/apple-app-site-association, allow paths containing apple-app-site-association. A rule that doesn’t contain well-known doesn’t affect your certificate renewal.
An allow rule skips WAF checks for every URL it matches, and Contains matches its text anywhere in the URL, including the query string. Use text that won’t appear in your other URLs, and contact support if you need a narrower option.
While HTTP Flood (DDoS) Protection is set to Filtering, a service that can’t run javascript can be stopped with no log entry, and an allow rule doesn’t get it past that check. Set the protection to Not Filtering while the service verifies your file.
Blocking One Specific File
Add a block rule with the Contains match type and the file name or its subdirectory, leaving out /.well-known/, such as pki-validation/. A rule that doesn’t contain well-known doesn’t affect your certificate renewal. Contains matches its text anywhere in the URL, so the rule can block a little more than the one file. Contact support if you need a narrower option.
If You Already Have a Rule
Rules added before this restriction stay in place until someone removes them.
Any of these rules stops your certificate from renewing, including one that names a single file. Remove it from its Path Rules page before your certificate’s next renewal, and if you still need it, replace it with a Contains rule as described above. Contact support if you aren’t sure what a rule is for.
Don’t shorten a path to get it past the form, and never use acme-challenge in a rule. A Begins With rule for /.well still matches the renewal check, and so does any rule containing acme-challenge, so either one stops the renewal.
Heroku ACM Errors
If you added a rule for /.well-known/acme-challenge/ so Heroku ACM could renew its certificate, remove it. While your domain points at the WAF, Heroku ACM can’t verify your domain, so errors or a failed renewal in the Heroku dashboard are expected and safe to ignore. Your visitors see the WAF’s certificate, not Heroku’s. See Heroku ACM and the WAF for more.
Wildcard Domains
Wildcard domains have a specific setup that works with our certificate infrastructure, so this restriction doesn’t apply to them. That setup usually includes a block rule for well-known. Leave that rule in place.
Using Your Own SSL Certificate
If you supply your own certificate, the renewal check above doesn’t apply to it, but the dashboard still refuses these paths. Contact support if you need one of these rules added.
Need Help?
If you have trouble with any of these rules, contact support:
- Contact us at support@expeditedsecurity.com
- Book a Call at https://app.harmonizely.com/expedited/30-min