Bypassing Caddy2 Auth With Custom Header

May 06, 2023

The use case behind this revolves around my homelab.  I have several services running behind Caddy2 which require authentication via Google OAuth.  This is an easy way to protect your services and is highly recommended (even on your personal, private home network).  However, what do you do when you have a client that needs to bypass authentication?

For me, this situation came up when I tried to use the app LunaSea (website).  LunaSea is a fantastic app that provides a nice, mobile friendly user interface to manage several services such as Radarr, Sonarr, etc.  By default, the app can do basic authentication and provide custom headers with all of its outgoing requests.

In this article, we're going to allow LunaSea to bypass Caddy's authentication as long as it injects/provides a custom header.  Is this the most secure way of doing things?  Absolutely not.  Will it be fine for a home network?  Most definitely.  Furthermore, if your service requires an API token, bypassing the traditional Caddy auth is understandable as your service is still secured behind the token.

Make sure you have setup SSL and are connecting over HTTPS. If you connect over HTTP, your headers can be easily seen in a packet capture (which leads others to easily determine this method of "authentication" that we are setting up).
For this guide, we'll be using:
- Caddy 2.6.4
- LunaSea 10.2.4


  1. First, we'll assume that you have Caddy already up-and-running. If not, you'll want to put a hold on this for now.
  2. Open up your Caddyfile and find the FQDN that you wish to add this functionality to. For me, I'm going to use this for Radarr.
  3. We'll setup the following:
    • BypassAuth is our header's name.
    • 1234567890 is our header's required value.
    • The last handle is for the normal flow that requires users to authenticate. {
      	@hasSPECIALHeader {
      		header BypassAuth 1234567890
      	handle @hasSPECIALHeader {
      		reverse_proxy radarr:7878
      	handle {
      		reverse_proxy radarr:7878
      		authorize with admin
  4. Reload your Caddy instance so that the new config goes into effect.
  5. Now, on your client, make sure you are injecting a header called BypassAuth with a value of 1234567890. All requests should now bypass authentication.

Going Further

  • Keep in mind that the header's name and value and be set to whatever you prefer.
  • You can also combine this with other rules. For example, you could specify that in order to utilize this special header, you must be sourcing from a specific subnet. This adds an additional layer of "security."

©2024 Tyler Wright