Traefik Auth Bypass: Conditionally Bypassing Forward Authentication

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. radarr.example.com) 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:

• Wireguard VPN Intro in 15 min: Amazing new VPN Protocol
• Complete Wireguard Setup in 20 min – Better Linux VPN Server
• Wireguard Windows Setup: Powerful VPN for Windows
• Wireguard Mac OS Client Setup – The sleek new VPN
• Wireguard Android Client Setup – Simple and Secure VPN
• Ultimate WireGuard Docker Compose: with CF and Traefik Support

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

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:

command: --rule.radarr.action=allow --rule.radarr.rule="Headers(`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:

...
TRAEFIK_AUTH_BYPASS_KEY=MySuperSecretStrongKey
...

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:

    labels:
      - "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`) && Headers(`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"
      - "traefik.http.services.radarr-svc.loadbalancer.server.port=7878"

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

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 https://radarr.example.com. 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

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.

Then, navigate to 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.

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.

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.