Traefik Auth Bypass: Conditionally Bypassing Forward Authentication

This post shows you how to conditionally bypass Traefik forward authentication, in a secure way. This is useful for apps such LunaSea, NZB360, etc.

If you have been a reader of this blog, you know by how much I love Traefik. It is a wonderful piece of application that provides a dynamic reserve proxy for all my applications.

As a cherry on top, it also makes protecting Docker and non-Docker web applications using Basic Auth, Google OAuth, or other multifactor authentication systems such as Authelia.

But sometimes, I want to be able to access my applications from mobile apps, bypassing (but still maintaining some level of security) the authentication layer added via Traefik.

In this post, I will show you how to conditionally bypass the authentication for certain applications.

Why Do I have to Bypass Traefik Authentication?

Let me explain this with an example. What are your options to stay connected to your Arr applications such as Radarr, Sonarr, etc. using the LunaSea app on iOS, while not on the same network as your home server?

  1. VPN into your home network and connect to the apps - Wireguard is great for this.
  2. Tie your home server and phone to an overlay network such as Zerotier-One or tailscale.
  3. Forward the Arr ports to the home server (PLEASE DO NOT DO THIS).

You could also securely put the Arr apps behind Traefik and access those using their FQDN (e.g. while on the go.

The only problem is if you have added an additional authentical layer on top of the app's native authentication, then LunaSea cannot get through that layer. This is where bypassing Traefik authentication comes in handy.

Other Posts in the Wireguard Series:

Of course, you can completely disable authentication for Arr apps but the point of this post is not removing security entirely.

How to Conditionally Bypass Traefik Forward auth

Note that this post assumes you have followed my Docker and Traefik guides. But the general principles may still apply to Traefik setups that are different.

Except basic HTTP authentication, other authentication systems I have used (Google OAuth and Authelia) have built in bypass mechanisms.

For example, when using Google Oauth initially, I was able to see if the request received by the server contains Radarr's API key, using this command in Google Oauth Docker Compose:

This guide has been updated to the new Traefik v3 syntax. To understand more about how has changed from Traefik v2, check my Traefik v3 guide.
command: --rule.radarr.action=allow --rule.radarr.rule="Header(`X-Api-Key`, `$RADARR_API_KEY`)"

You may notice this in my GitHub repo files.

While I ran with this method initially, I found it to be easier to do this in Traefik. And even better, I do not have to use the API key in my Docker compose.

So, let's see how to use Traefik routers to conditionally apply basic authentication or forward authentication.

1. Generate Traefik Auth Bypass Key

First, let's generate a random key. It can be anything, just like a strong password that you can remember.

You may use one of the many available strong password generators on the web or one of the password managers.

Let's set it to the environmental variable TRAEFIK_AUTH_BYPASS_KEY in .env file, like so:


2. Add Docker Compose Labels to the App

In this example, I am going to try to reach my Radarr instance, by passing the forward authentication if the above bypass key is present in the request. If it is not, then the user is presented with the authentication form.

So, let's add the Docker compose labels to Radarr to accomplish this:

This guide has been updated to the new Traefik v3 syntax. To understand more about how has changed from Traefik v2, check my Traefik v3 guide.
      - "traefik.enable=true"
      ## HTTP Routers Auth Bypass
      - "traefik.http.routers.radarr-rtr-bypass.entrypoints=https"
      - "traefik.http.routers.radarr-rtr-bypass.rule=Host(`radarr.$DOMAINNAME_CLOUD_SERVER`) && Header(`traefik-auth-bypass-key`, `$TRAEFIK_AUTH_BYPASS_KEY`)" # Bypass Auth for LunaSea on iOS
      - "traefik.http.routers.radarr-rtr-bypass.priority=100"
      ## HTTP Routers Auth
      - "traefik.http.routers.radarr-rtr.entrypoints=https"
      - "traefik.http.routers.radarr-rtr.rule=Host(`radarr.$DOMAINNAME_CLOUD_SERVER`)"
      - "traefik.http.routers.radarr-rtr.priority=99"
      ## Middlewares
      - "traefik.http.routers.radarr-rtr-bypass.middlewares=chain-no-auth@file"
      - "traefik.http.routers.radarr-rtr.middlewares=chain-oauth@file"
      ## HTTP Services
      - "traefik.http.routers.radarr-rtr.service=radarr-svc"
      - "traefik.http.routers.radarr-rtr-bypass.service=radarr-svc"
      - ""

How Do the Bypass Labels Work?

Here is an explanation of what the above Docker compose labels do.

As with any Docker service behind Traefik, we have 3 components: routers, middlewares, and services. The only difference above is that there are 2 sets of each component for 2 different scenarios.

Scenario 1: HTTP Routers Auth Bypass
Restricted Content

Additional explanations and bonus content are available exclusively for the following members only:

Silver - Monthly, Silver - Yearly, Gold - Monthly, Gold - Yearly, Diamond - Monthly, Diamond - Yearly, and Platinum Lifetime (All-Inclusive)

Please support us by becoming a member to unlock the content.
Join Now

Scenario 2: HTTP Routers Auth

Here again, we are monitoring the https entrypoint. First let us look at the following router:

      - "traefik.http.routers.radarr-rtr.rule=Host(`radarr.$DOMAINNAME_CLOUD_SERVER`)"

This router will apply to the requests received at That is all we are checking. We are calling this router radarr-rtr.

We are setting a lower priority for this router: 99.

If this scenario is met, then we are defining a specific middleware for this router (radarr-rtr, using the line:

      - "traefik.http.routers.radarr-rtr.middlewares=chain-oauth@file"

Notice the chain-oauth@file middleware. If you are familiar with my setup, then you may know that this middleware chain includes Google OAuth authentication layer.

And finally, for this router (radarr-rtr, we need to specify a service, which is done using the following line:

      - "traefik.http.routers.radarr-rtr.service=radarr-svc"

Notice that the service line is exactly same as Scenario 1. This is because all the requests reach the same Radarr service in the end. What changes is the path (middleware) they take to reach the service.

3. Setup LunaSea with Custom HTTP Header

NZB360 is another famous application for the same purpose for the Android platform. Custom HTTP headers are not available yet but it is planned soon.

You have laid the groundwork. Now, we need to configure the mobile application to send the bypass information (the name and key) with the request.

Open your LunaSea application and go to app (Radarr) configuration as shown below.

Lunasea Radarr Configuration
Lunasea Radarr Configuration

Then, navigate to connection details:

Lunasea Radarr Connection Details
Lunasea Radarr Connection Details

Finally, go to Custom Headers and Add Header. Enter the traefik-auth-bypass-key for Header Key and your chosen MySuperSecretStrongKey for Header Value, as shown below.

Lunasea Radarr Custom Headers For Bypass
Lunasea Radarr Custom Headers For Bypass

And that's it. LunaSea should bypass the authentication layer and reach Radarr. And Radarr already has mechanism to bypass its own authentication if the API key is present in the request, which is the expected/normal behavior.

Be sure to recreate Radarr docker container for the new labels to take effect, before trying to connect.

Concluding Remarks

Bypassing Traefik Forward Auth beats the purpose of securing the apps. But if done properly it can complement your setup and add a layer of convenience.

In my case, I am able to monitor Tautulli, SABnzbd, and all the Arr apps on the go.

There were some questions on our Discord Server on how to use Traefik auth bypass, and that is what I tried to explain in this article.

If you are aware of other apps and services that could leverage custom headers to bypass Traefik auth, be sure to let us know in the comments.

Be the 1 in 200,000. Help us sustain what we do.
46 / 150 by Dec 31, 2024
Join Us (starting from just $1.67/month)


Anand is a self-learned computer enthusiast, hopeless tinkerer (if it ain't broke, fix it), a part-time blogger, and a Scientist during the day. He has been blogging since 2010 on Linux, Ubuntu, Home/Media/File Servers, Smart Home Automation, and related HOW-TOs.