The Bitwarden mobile app wipes its local cache when receiving an HTTP 403 error. By default, a WAF rule in a Cloudflare free account can only return a 403. This guide shows how to use Cloudflare Workers to validate mTLS certificates and return an HTTP 404 instead.

Background

For accessing internal services remotely, I have been a big fan of Cloudflare Tunnels. This system provides an easy mechanism to provide access without opening up firewall ports, and the ability to take advantage of Cloudflare security controls like their Web Application Firewall (WAF) and Zero Trust access control.

Previous authorization model

Up until recently, I have secured my internal applications with a simple OAuth identity validation through Zero Trust. Depending on the identity provider used, this can provide a significant amount of protection, but it can cause issues with non-web based applications like mobile apps.

One simple alternative I’ve used is Service Tokens, which can be provided via custom HTTP headers – if the app I’m trying to use supports that type of customization. However, this is quite rare, so I started looking for a more universal approach.

mTLS authorization

Historically, during client/server communication, the focus has been on ensuring the server endpoint is trustworthy, and where SSL/TLS is a standard requirement. There are many use cases where the server may need to assess the trustworthiness of the device communicating with it. For a very sensitive system like a password manager, validating the device in addition to the user credentials provides an extra layer of security.

Mutual TLS (mTLS) is a process that provides the missing validation, by having the client provide its certificate to the server (after the client has validated the server’s certificate).

Cloudflare mTLS support on free plans

I am currently using Cloudflare’s free plan, as the pricing for their Pro and Business plans is quite lofty for a single household use case.

With the free plan, you can create certificates via the Cloudflare dashboard, which ends up creating a certificate signed by a Cloudflare-managed, account-level root CA. Then, the client certificate validation can be referenced in a WAF rule.

However, there are some important limitations here:

• You cannot bring your own CA, which means the certificates cannot be used in Zero Trust access controls.
• You cannot get the cert for your individual Cloudflare-managed CA, which means you cannot bundle it into the client certificate, which is a requirement to use it some situations (like Chrome on Android).

Another limitation, not strictly related to mTLS certs, is that the Cloudflare WAF rules will always return HTTP 403 when they block traffic. Customizing the response, including the response code, is limited to Pro plans (and above).

Need for customizing the response code

I have a password manager application (Bitwarden) that caches passwords locally, which is a helpful feature when I don’t have an Internet connection. However, this app will always try to sync passwords if it can. As a security mechanism, if it is able to reach the server (Vaultwarden, in my case), and the server returns a 401 or 403 response code, the app will immediately clear the local cache.

I encountered this scenario when testing my mTLS configuration. I immediately thought of future situations where this could cause significant distress – let’s say I’m outside my network and need access to a password. Something has happened on my device: maybe the mTLS cert was accidentally uninstalled, or maybe it expired and I haven’t realized it yet. I try to access the password, everything vanishes, and I’m stuck.

I wanted to prevent this from being a possibility, which is why I wanted to alter the response code from 403 to 404. As mentioned in the previous section, this isn’t possible on the free plan.

Enter Cloudflare Workers

However, there is another option within reach of the free plan, which is Cloudflare Workers. Workers allow you to deploy some custom code that can be mapped to a specific URL path. The free plan currently allows up to 100,000 Workers requests per day, which is plenty for household use.

To get this setup, I did the following:

Create and configure the mTLS certificate

Create an mTLS certificate and enable it for the targeted domain names.

Remove any WAF rules

I first made sure any WAF rules I had did not apply to the hostname in question. In the request lifecycle, these will be executed early on.

Add a Zero Trust bypass rule (optional)

Zero Trust access rules also run prior to Workers, so you need to make sure this won’t block access to your application.

If you only have Zero Trust applications set up for specific subdomains, you may not need to do anything here. I happen to have a wildcard application setup, so that anything in my domain would route to the Zero Trust handling by default. This means I needed to specify an exception just for the subdomain that I wanted to protect with an mTLS cert.

To do this, I created a “bypass all rule”:

Create the worker

Create a new worker, using the provided “Hello World” template. Replace the code with the following:

export default {
  async fetch(request, env, ctx) {
    // Get the certificate status from the Cloudflare edge
    const clientTrust = request.cf?.tlsClientAuth;

    // Check that the mTLS has been presented and verified by Cloudflare.
    if (!clientTrust 
        || clientTrust.certPresented !== "1"
        || clientTrust.certVerified !== "SUCCESS") {
      return new Response("Not Found", { 
        status: 404,
        headers: { "Content-Type": "text/plain" }
      });
    }

    // If valid, forward the fetch to the backend server.
    return fetch(request);
  },
};

Optional: If you would normally use a WAF rule to block other types of traffic, you likely can incorporate that logic into the Worker as well. For example, you could add a regional restriction like this:

if (request.cf?.country !== "US") {
  return new Response("Not Found", { 
    status: 404,
    headers: { "Content-Type": "text/plain" }
  });
}

Set up route and test the new worker

After deploying the worker, you can then configure the appropriate route by following the Cloudflare documentation.

Then, try accessing the application you have protected, on devices with and without the mTLS certificate installed.

Future wishes

Ideally, I would really like to be able to target mTLS certificates as part of the Zero Trust access policies. This would allow different combinations to be created, like supporting either mTLS auth or an OAuth identity provider. Depending on the application being protected, this type of configuration may provide adequate security, while providing greater flexibility – allowing web browser access with just OAuth, but falling back to mTLS auth for devices where it is the best option.

There is rich support for mTLS auth in Zero Trust, but this support is limited to Business accounts only! At hundreds of dollars per month, that’s a very high price to pay given that I don’t need most of what that plan provides.

If anyone from Cloudflare is listening, it’d be great to expand the availability of this feature – potentially they could offer individual feature plans, like what is currently done for Workers. I’d happily pay a reasonable amount just to get support to bring my own root CA and use it as part of my Zero Trust access policies.

Final thoughts

Securing a server shouldn’t come at the cost of usability. By moving logic from the limited WAF rules in a Cloudflare free account into a Cloudflare Worker, I believe I’ve managed to keep the high-security of using mTLS while smoothing out the quirks of the password manager application I’m using. It’s an easy-to-configure change that avoids a potential lockout.

Are you running a similar setup? Have suggestions on other ways to leverage Cloudflare’s copious free functionality? Leave a comment below or send me an email.

Motivation

I haven’t posted in a long time, and this blog had largely faded into the background for me. I was doing some management of my domains, trying to clean things up after my domains registered with Google were transferred to Squarespace. As part of this, I decided to use Cloudfare as my nameserver, which I’ve used for other projects.

I started reading about Cloudfare Pages, which seemed like a great match for easily deploying a statically-generated site. You can point Cloudflare to a GitHub repo, and it will automatically kick off a build after every commit, and deploy the static artifacts. Unfortunately, the Hyde framework I was using is no longer maintained, and still does not support Python 3. Cloudflare Pages does not have support for Python 2.7.

So I decided it would be a fun project to migrate to a new static site generator.

Finding a new tool

Searching around, I quickly settled on Hugo due to its large community, and reputation for blazing fast speed.

I wasn’t quite sure how the easy it would be to migrate my old site template, so I started off following the quick start guide, chose an existing public theme that looked ok, and started copying the content from my site’s old repository. This was pretty easy since both tools are based on Markdown – I just needed to slightly adjust each post’s metadata. With less than 20 total posts, I did that manually.

Fundamental differences

Hyde is a very simple generation tool, compared to Hugo which has a much larger feature set, but also very strong opinions on how things should be structured. In Hyde, I had a flat folder of templates, and could directly point individual pages to an arbitraty template.

Hugo has a very specific structure to follow, which it leverages to classify into a set of page types. This prevents the organizational structure that I wished to have, but I quickly adjusted. For example, my previous file hierachy looked like this:

content/
content/blog
content/blog/2025
content/blog/2025/01
content/blog/2025/01/post.md

Having multiple nested directories is not easily supported, so I needed to switch to the following hierarchy:

content/
content/blog
content/blog/2025-01-post.md

Given the limited number of posts, I don’t mind this setup too much. However, if I were a more prolific blogger, I would probably dig in to find a better way to organize individual post files.

Porting a Hyde theme

Hugo themes are also much more structured than the ad-hoc Hyde layouts. There is a rigid template lookup order, which required some trial-and-error to determine where all of the template types needed to live in order to get picked up correctly.

Hugo uses a Go templating library, so I needed to tweak all of my previous Jinja2 templates. This was a bit of manual work, but overall not too bad, largely because of the rich documentation available.

On the plus side, Hugo does have built-in templates for Google Analytics and Disqus, both of which are used on this site. Rather than needing to include the code for those in my templates, I could just define some simple config parameters and reference the built-in templates:

<head>
  {{ template "_internal/google_analytics.html" . }}
</head>

For posts, I ended up defining one “single” template, which is used for both posts and standalone pages like About. I need conditional logic to prevent showing Disqus on non-posts. I settled on excluding pages that appear in the site navigation menu:

{{ if not .Params.menu }}
{{ template "_internal/disqus.html" . }}
{{ end }}

Final result

As before, the code for this site remains open source. I left the old code in its own repository, and created a new repository for the Hugo-base site implementation, which you can find on GitHub.

The venue

PAX East is held at the Boston Convention & Exhibition Center, and is the perfect location for this type of event. The building has a ton of space, and can easily handle the number of people that attend. It doesn’t have the wacky charm that the Washington State Convention Center has (the site of PAX Prime), but I’ll take the elbow room over charm any day.

The games

Battleblock Theater: I first saw this game back at PAX Prime in 2009, before it had a name. I’ve watched it closely since then, following its progression over the years. The game finally released today, and it seems to have benefited from the extra polish. I hope it can captivate me the same way Castle Crashers did, and I look forward to seeing what’s next for The Behemoth.

Nutjitsu: This was a brand new game from Ninjabee. In its current state, it is a simple path building and stealth game built for tablets, with a fun art style and main character. I’m a big fan of their Kefling series of games, so I’m looking forward to playing this when it gets released.

Perspective: This game was one of the games playable at the Digipen booth, as it was a student project. It’s an excellent platformer that makes very clever use out of the interaction between 2D and 3D space. I highly recommend checking it out, as well as some of the other Digipen games from recent years.

The talks

Beyond playing new games, I really enjoy PAX for the variety of industry talks and panels that are held.

Mass Effect Retrospective: This panel had a number of designers, writers, and even a voice actor from the Mass Effect series of games. I had envisioned fans with pitchforks, still angry about the ending of Mass Effect 3, but the panel ended up being mostly fluff and softball questions. It was still nice to hear some background information over various bits of the development process.

Classic Videogame Panel: This panel was hosted by ACAM, who also have a classic arcade game room at PAX East. They hosted a similar panel last year, with a number of the same panelists, but that didn’t dampen my enthusiasm. I have no problem listening to those guys share stories and talk about what it was like to develop videogames back in the 80s.

Where’d my .htaccess go?

Azure Web Sites use IIS as a web server, not the more common Apache (or Nginx) server widely used across the Unix world. While Azure handles all of the server setup and maintenance for many cases, you’ll still need to get your hands dirty if you need custom handling.

One of the big behaviors I needed to maintain in the migration was to continue adherence to the No-WWW philosophy. This means making dancarroll.org the canonical name of my site, with www.dancarroll.org redirecting to the no-www version.

I had this set up on the previous iteration of the site using an Apache .htaccess file. It was very easy to find examples of how to do this across the web.

RewriteEngine On
RewriteBase /
RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
RewriteRule ^(.*)$ http://%1/$1 [R=permanent,L]

IIS, however, does not use .htaccess files. Instead, I needed to create a Web.config file with the appropriate settings.

IIS URL Rewrite

Luckily, IIS has its own URL rewriting module. And, even luckier, Azure Web Sites get this module configured automatically.

To get this set up, you need to create a file named Web.config in the wwwroot directory of your Azure deployment. I was only able to find a few examples of doing no-www redirects for IIS, but all of them hardcoded the domain name in the file. This wasn’t acceptable, as I like to reduce maintenance and use a similar configuration across many different web sites.

Here’s what I came up with:

<?xml version="1.0"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Canonical Hostname" stopProcessing="false">
          <match url="(.*)" />
          <conditions logicalGrouping="MatchAll" trackAllCaptures="false">
            <add input="{HTTP_HOST}" pattern="^(www\.)(.*)$" />
          </conditions>
      <action type="Redirect" url="http://{C:2}{REQUEST_URI}" redirectType="Permanent" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

And that’s it! I found that Azure would recognize the file modification and start using it, but you may need to manually restart the site using the Azure management portal.

Breaking it down

The documentation for IIS URL Rewrite is decent, but I wanted to provide a few quick notes about what is going on here.

  <match url="(.*)" />
  <conditions logicalGrouping="MatchAll" trackAllCaptures="false">
    <add input="{HTTP_HOST}" pattern="^(www\.)(.*)$" />
  </conditions>

The match element defines the pattern that will be used to find URLs to be processed. In this case, the regular expression used captures all URLs. A condition is then created to provide additional refinement to which URLs will have a rewrite action taken. Here, the condition only looks at the server variable HTTP_HOST, which requires matching the host domain (not the full URL). The regular expression used only matches hosts starting with www..

  <action type="Redirect" url="http://{C:2}{REQUEST_URI}" redirectType="Permanent" />

If there was a successful match, then an action is taken for that particular URL. In this case, the action is a redirect, with the “Permanent” redirectType mapping to an HTTP 301 status code. The url attribute defines the redirect URL, and I’m using two features here to generate it.

{C:2} is a back-reference, which as its name implies, refers back to data captured previously in the rule. The C states that we are referring to something captured by a condition (as opposed to the rule match), and the 2 is the second group match (0 is the full pattern, 1 is the www. part, and 2 is the remainder of the host).

Finally, {REQUEST_URI} is a another server variable that IIS lets us reference, and it contains the full path to the requested document. If the URL is http://www.dancarroll.org/blog/, then REQUEST_URI is /blog/.

Bonus Rules

A couple of extra URL rewrite rules I am using that are worth sharing.

Forcing lowercase URLs

  <rule name="Convert to lower case" stopProcessing="true">  
    <match url=".*[A-Z].*" ignoreCase="false" />  
    <action type="Redirect" url="{ToLower:{R:0}}" redirectType="Permanent" />
  </rule>

Redirecting default documents

For default documents (i.e. index.html), it is nice to redirect a request to domain.com\dir\index.html to its parent directory, domain.com\dir\. This also help to ensure there is only a single canonical name for any document.

	<rule name="Default document - html" stopProcessing="true">
	  <match url="(.*)index.html" />
	  <action type="Redirect" url="{R:1}" redirectType="Permanent" />
	</rule>

Take my site’s new design, rolling out today. I initially started working on it in February 2011, going by the file creation timestamps on my machine. I worked on it for a week or so, got some feedback, then dropped it. A year later, I took the big step to actually create a source repository on Bitbucket to make sure the code was backed up somewhere safe (I don’t recall making any other progress at the time).

It took me over a year from that point to actually pick up the project and push it through to completion.

The design

Like the previous design of my site, I have taken a lot of inspiration from people in the Django community. A lot of the design inspiration comes from Steve Losh, who has consistently done an excellent job at clean, readable web design.

I’m not sure what I was thinking with the previous iteration, which featured orange and beige on a darker, almost navy blue background. That’s been fixed now!

The code

Like Steve, I also made a transition in how the site is implemented. Previously, my site was developed using Django. Django is a Python-powered web framework, and it gave me tremendous flexibility to add features like a lifestream. However, it came with a lot of overhead for a simple blog, and could be unreliable on inexpensive, shared web servers.

This new iteration of the site is built using Hyde, a static web site generator built in Python. Hyde allows me to work with Python code and templating languages, much like the one used with Django, but the end result is a static HTML and CSS website (rather than a dynamic site backed by executing Python code and databases). The end product can now be hosted anywhere with relatively good performance.

And like the previous iteration, the new version is still open source. For ease of browsing both implementations, the new design lives in a separate code repository on GitHub.

The problems

Another big improvement made during this transition is in ease of use and maintainability for me. Previously, I tried a few different ways of creating blog posts. First, I tried writing HTML each time I needed to create a new post, and uploaded it using Django’s admin UI. This was a pain and prone to rendering issues.

Next, I spent a lot of time implementing support for the MetaWeblog API, which allowed me to create blog posts using applications like Windows Live Writer. That made post creation much easier for me, but those blogging applications would create ugly HTML with their own special markup, and often required tweaking the HTML by hand to get things to show up correctly.

Finally, regardless of how I created posts, they ended up being saved to a database on my web host. That’s not a very safe location, so I needed to make sure to create regular backups.

The solutions

With Hyde, it was easy to convert all of my blog posts to be written in Markdown. When generating the site, the posts get passed through a Markdown filter to convert them to HTML. As long as I have good CSS defined on how to render what HTML gets produced, I can create a blog post using a simple text editor and know that it will come out looking good on the other side.

Aside: Django has built-in support for Markdown, so I could have used it with the site’s previous implementation. However, things would have been more complicated. There would be performance issues if posts were passed through the Markdown filter for each web request, deployment complexity if I needed to leverage server-side caching, or implementation complexity if both versions were stored (Markdown version for editing, HTML version for serving up web requests).

For the issue of storing and backing up blog posts, content is now part of the codebase itself. It gets pushed up to Bitbucket, and lives on a few different machines where I have the code checked out.

The future

I feel very accomplished for finally completing this major redesign project, so I hope to actually use this thing more often. I’ll never be prolific, but my goal is to publish at least several posts a year.