Except a username-and-password-only Authelia instance is just a fancier login form sitting in front of the exact same single point of failure every other login form has: whatever password you picked. The entire reason to run a centralized auth layer in the first place is to get to do hard things — like enforcing real two-factor authentication — once, centrally, instead of bolting it onto every app individually. If you skip that part, you’ve built infrastructure for a feature you’re not actually using.

So this post is about closing that gap: turning on real TOTP-based two-factor, and wiring up the notification system Authelia needs to actually deliver codes, links, and alerts — which sounds like a footnote but turned into its own small adventure once I hit a TLS certificate quirk that’s worth flagging for anyone else who runs into it.

Why two-factor isn’t optional once you centralize auth

Once Authelia is gating Nextcloud, Open WebUI, and whatever else lives behind it, that one login becomes the single key to the entire DMZ. That’s the whole point — but it cuts both ways. A compromised password used to mean a compromised app. Now it means a compromised everything, all at once, through the front door I built specifically to make access more convenient. Centralizing authentication without centralizing strong authentication is just centralizing risk — and it’s the same reason the DMZ network itself is VLAN-isolated from the rest of the homelab in the first place: a single compromised layer shouldn’t mean a compromised everything else too.

Authelia supports TOTP out of the box, and enabling it for an access_control policy is a one-line change in configuration.yml:

yaml

access_control:
  rules:
    - domain: openwebui.yourdomain.com
      policy: two_factor
    - domain: nextcloud.yourdomain.com
      policy: two_factor

That’s it on the policy side — flip one_factor to two_factor for any domain you want gated, restart Authelia, and the access control layer now requires a second factor before granting a session. I deliberately left auth.yourdomain.com itself — Authelia’s own login portal — on a bypass policy, since that’s the page doing the authenticating in the first place; there’s nothing to gate behind itself.

The part that actually takes thought isn’t the policy line, though — it’s how the person setting up TOTP for the first time actually receives the QR code and registration link. Authelia’s identity-verification flow for first-time 2FA registration works by emailing you a link to confirm it’s really you before letting you scan a QR code and bind an authenticator app. No working notification channel, no registration. The login page rendering correctly was never actually proof the auth system was complete; it was proof exactly one feature — first-factor password checking — was complete.

Bootstrapping without email: the filesystem notifier

Here’s a chicken-and-egg problem I didn’t expect going in: you generally need a working SMTP setup to register 2FA, but I hadn’t actually wired up SMTP yet when I wanted to register my own TOTP for the first time. Authelia’s answer to this is a notifier mode that doesn’t try to send anything anywhere — it just writes the notification to a file on disk:

yaml

notifier:
  filesystem:
    filename: /config/notification.txt

With this in place, instead of an email landing in an inbox, the identity-verification link gets written straight into a text file inside the Authelia container. Reading it is just:

bash

docker exec authelia cat /data/notification.txt

Copy the link out, paste it into a browser, and the registration flow proceeds exactly as if a real email had arrived. This is a genuinely useful bootstrapping trick worth knowing about independent of whatever your final SMTP setup ends up being — any time Authelia needs to send something and you don’t yet trust (or haven’t yet built) the real delivery path, dropping back to the filesystem notifier lets you keep moving without blocking on infrastructure that isn’t ready yet.

Wiring up real SMTP, and the trap waiting inside it

Bootstrapping aside, a filesystem notifier obviously isn’t a long-term answer — it only works because I have shell access to the box, which defeats the entire purpose of a notification system the moment any other person needs to register their own 2FA. The real fix is pointing Authelia at an actual mailbox.

The notifier config for SMTP looks innocent enough:

yaml

notifier:
  smtp:
    address: 'submissions://mailserver.domain.com:465'
    username: 'mymail@domain.com'
    password: 'REDACTED'
    sender: "Authelia <mymail@maildomain.com>"
    identifier: 'yourdomain.com'
    startup_check_address: 'mymail@maildomain.com'
    tls:
      skip_verify: false
      minimum_version: 'TLS1.2'

The submissions:// scheme tells Authelia this is an implicit-TLS SMTP submission connection on port 465, rather than the older plaintext-then-STARTTLS dance on port 587. That part’s fine and fairly standard.

What actually tripped me up was something that, in hindsight, is an obvious consequence of how TLS works, but is exactly the kind of thing you don’t think about until it bites you: my first instinct was to point the address field at the mail server’s raw IP rather than its hostname, since I already had the IP handy and it felt like one less moving part — no DNS resolution step, no dependency on DNS staying healthy. Authelia started up, attempted the connection, and immediately failed with x509: cannot validate certificate for <IP> because it doesn't contain any IP SANs.

That error message, once you actually read it instead of just reflexively googling it, explains the whole problem. The mail server’s TLS certificate was issued for the hostname mailserver.domain.com. TLS certificates assert an identity — “I am this specific name” — and the client connecting is supposed to check that the name it asked to connect to matches the name on the certificate it received back. When I connected by raw IP, there was no hostname in the conversation for the certificate to match against; the certificate says “I’m mailserver.domain.com,” and the connection was nominally to 203.0.113.45 or whatever the IP happened to be, and those two things have no relationship as far as the TLS handshake is concerned, unless the certificate specifically lists that IP as an additional valid identity (an IP SAN, which this one didn’t have, because almost no certificates bother to).

This is a small, almost embarrassing thing to get wrong, and also a genuinely common trap, because using a raw IP feels like it should be strictly safer or simpler — fewer dependencies, no DNS lookup that could fail or get hijacked. For plaintext or non-validated connections, sure. The moment TLS certificate validation enters the picture, the hostname isn’t an implementation detail you can route around — it’s load-bearing. The certificate’s whole job is binding a cryptographic identity to a name, and if you don’t connect using that name, there’s no name for the certificate to authenticate against, full stop. (The same hostname-vs-certificate confusion shows up again, in a slightly different shape, when verifying a wildcard cert covers a new subdomain — worth a read if this kind of TLS mismatch interests you beyond just SMTP.)

The fix was simply using the hostname Authelia was always meant to use:

yaml

address: 'submissions://mailserver.domain.com:465'

Once that one piece changed, the connection succeeded cleanly, the startup check passed, and Authelia logged a clean Startup complete with no certificate complaints.

Confirming it actually works, end to end

Configuration that merely starts without errors and configuration that actually works are two different claims, and I’ve been burned often enough by the first one masquerading as the second that I always insist on testing the real flow before calling something done. With SMTP wired up correctly, I went back through the TOTP registration process one more time, this time as a genuine end-to-end test rather than the filesystem-notifier bootstrap — triggered the identity verification flow, and watched a real email land in the actual inbox a few seconds later, with a working confirmation link.

From there, registering TOTP itself is almost anticlimactic after all that setup: scan the QR code with an authenticator app, enter the six-digit code it generates to confirm the binding succeeded, and from that point forward, every login to a two_factor-policy domain prompts for that code after the password. The login page, from the outside, looks exactly like it did before any of this work — username, password, and now an extra six digits. The difference is everything behind that screen actually does what centralizing authentication was supposed to buy in the first place.

The actual lesson here

None of this was hard, exactly — every individual piece was a short config block and a restart. What made it worth writing up is how each step quietly assumed the previous one actually worked, and how easy it would have been to stop at “the login page renders” and call it done. Two-factor without a working notification channel isn’t two-factor, it’s a setting nobody can finish enabling. A notification channel that starts without errors isn’t necessarily a notification channel that delivers anything, if a hostname-vs-IP TLS mismatch is quietly swallowing every send attempt. The only way to know any of it actually works is to walk the whole path a real, first-time user would take, end to end, and watch what actually lands in an actual inbox.

This same 2FA-gated access_control pattern gets reused directly in the next build — Ditch Google, which gates a self-hosted SearXNG instance behind exactly this TOTP setup, plus a network-scoped bypass rule for Open WebUI’s API calls. And if locking yourself out of your own auth layer is a worry — it should be, once you’ve made Authelia the single key to everything — Never Lock Yourself Out covers the equivalent safety net on the OPNsense side.

Two firewalls, two very different jobs. But they share a problem that took me longer than I’d like to admit to solve properly: how do you restrict management access on the remote box to “just me, at home” when your home connection doesn’t have a fixed IP — and worse, doesn’t even have a real IP from the internet’s point of view?

This post walks through what I built: a self-updating allowlist that tracks my home IP automatically, even through CGNAT, without me touching either firewall again. If you’re running a similar two-site setup — homelab plus colo, or homelab plus VPS — this is the kind of plumbing that’s easy to skip and annoying to retrofit later.

Why Bother Locking This Down At All

The webhosting firewall has a management GUI and SSH, like every OPNsense box does. In an ideal world, neither would ever touch the WAN interface — everything would go over VPN, full stop. In practice, there are legitimate reasons to want a direct fallback path: VPN daemons crash, tunnels flap, and at 2am when something’s on fire, you want a door that doesn’t depend on the thing that might be broken.

The compromise I landed on is the same one most of us reach for eventually: keep the door, but restrict who can knock. An allow rule scoped to “traffic from my home IP only” on top of a default-deny stance shrinks the attack surface from “anyone on the internet” to “anyone who happens to be sitting at my house, or who happens to share my ISP’s NAT pool at this exact moment” — which, as I’ll get into, isn’t quite as airtight as it sounds, but it’s a meaningful improvement over leaving the GUI wide open.

This is also just good practice independent of the CGNAT wrinkle. If you’ve got a static IP at home, the IP-allowlist part of this is trivial — one alias, one rule, done. The interesting part of my setup, and the reason this post exists, is what happens when your home connection doesn’t give you a stable address to allowlist in the first place.

The CGNAT Catch

My home ISP, like most residential providers these days, doesn’t hand out a unique public IPv4 address per customer. Instead, I sit behind Carrier-Grade NAT: a whole pool of subscribers shares a smaller set of public IPs, and the address my OPNsense’s WAN interface reports is a private one in the 100.64.0.0/10 range — not my actual internet-facing address at all.

This is the same CGNAT wrinkle that made getting a WireGuard tunnel through to this homelab in the first place its own separate problem — there, the issue was inbound traffic having nowhere to land; here, it’s an outbound-facing allowlist having nothing stable to allowlist. Same root cause, two different symptoms.

This matters a lot for dynamic DNS. The naive approach — point a DDNS client at your WAN interface and have it push that address to a DNS record — completely falls apart under CGNAT. You’d faithfully update your DNS record every few minutes with an address nobody on the internet can route to. The fix isn’t complicated once you know it’s needed, but it’s a “you don’t know what you don’t know” trap: the DDNS client has to ask an external service what your IP looks like from the outside, rather than trusting what your own interface thinks it is.

Building a Self-Updating Allowlist

With that constraint in mind, the chain I built has three links:

1. A DNS record on Cloudflare that always points at my real home IP.
2. A DDNS client on the home OPNsense box that keeps that record current — sourcing the IP from an external lookup service instead of the WAN interface, specifically because of the CGNAT issue above.
3. A firewall alias on the webhosting OPNsense box that resolves that same hostname on a timer and feeds the result straight into the pf table, with a rule referencing the alias instead of a hardcoded address.

The elegant part is that none of this needs glue scripts or cron jobs duct-taped together. OPNsense’s alias system natively understands FQDNs in Host-type aliases — it resolves them on a configurable interval (300 seconds by default) and keeps the underlying table in sync on its own. Once the chain is wired up, it just runs.

Step 1 — A DNS Record and a Properly Scoped API Token

On the Cloudflare side, I added a plain A record — home.yourdomain.com — with the proxy turned off (grey cloud, “DNS only”). That last bit matters more than it looks: if the orange-cloud proxy is on, anything resolving that hostname gets back one of Cloudflare’s edge IPs instead of my home address, which would quietly break the whole scheme in a way that’s annoying to debug.

For authentication, I skipped the Global API Key — it grants account-wide access, which is a lot of blast radius for something that only needs to touch one DNS record — in favor of a scoped API token limited to Zone / DNS / Edit permissions on the specific zone. Good habit generally: minimum necessary privilege, even for the small stuff.

Step 2 — DDNS on the Home Firewall

OPNsense doesn’t ship dynamic DNS support out of the box; it’s a plugin (os-ddclient). Once installed, the configuration lives under Services → Dynamic DNS, and the account setup is where the CGNAT-specific decision actually gets made.

The provider is Cloudflare, the token goes in the password field (with a slightly odd quirk — the username field has to literally contain the word “token” rather than an email address, which is how the plugin distinguishes API-token auth from the legacy global-key auth). The zone is the bare domain, the hostname is the full subdomain I want updated.

The setting that actually solves the CGNAT problem is “Check IP method.” Left on “Interface,” the client would read the WAN interface’s address — the private CGNAT one — and dutifully push garbage upstream. Pointed instead at a web-based IP-checking service, the client asks an external host what address the request arrived from, which is the real, routable, internet-facing IP, regardless of how many layers of NAT sit between my router and the actual internet.

It’s a small dropdown selection with a big practical consequence, and it’s the kind of detail that’s invisible until you’ve had a DDNS setup silently failing for a week because nobody told you the interface address wasn’t the address that mattered.

Step 3 — Alias and Rule on the Webhosting Firewall

On the colo box, the configuration is almost anticlimactic by comparison. A new Host-type alias with the DDNS hostname as its content, and OPNsense takes care of the rest — resolving it on its own schedule and populating the pf table transparently. Any rule referencing that alias automatically tracks whatever the hostname currently resolves to.

The rule itself is a single allow entry, sourced from the alias, scoped to the specific port the management interface listens on, sitting above the default-deny rule that covers everything else. From the rule’s perspective, it looks exactly like a static IP allowlist. The dynamic part is entirely hidden inside the alias. (This same idea — trusting a request because of where it’s coming from, rather than what it claims to be — is exactly what the network-scoped Authelia bypass rule for Open WebUI’s search calls does at the application layer instead of the firewall layer.)

What Could Still Go Wrong

I want to be honest about the limits of this setup, because IP-based access control always sounds more solid than it actually is.

First, there’s a convergence gap. If my home IP changes, there’s a window — typically a few minutes — between the DDNS client noticing and pushing the update, and the remote firewall’s alias re-resolving the hostname. During that window, the old IP is still allowed and the new one isn’t yet. If the only path into the box were this rule, a badly timed IP rotation could lock me out at the worst possible moment.

Second, and more fundamentally: CGNAT means the public IP I’m allowlisting isn’t uniquely mine. It’s shared across a pool of subscribers on the same ISP infrastructure. Anyone else sitting behind the same NAT pool at the same moment would also satisfy the source-IP check. That doesn’t make the rule useless — it still meaningfully narrows things down from “the entire internet” to “people on my ISP’s network right now” — but it’s not the same security guarantee a unique static IP would give you, and I don’t want to oversell it as one.

Because of both of these, this rule isn’t my primary path into the box. I already run a WireGuard tunnel between the two sites, with HAProxy, ACME, and VLAN isolation deciding what’s actually reachable on the other end of it, and that’s where day-to-day management traffic goes. This dynamic allowlist exists as the fallback — the door I can still use if the tunnel itself is down — not as the front line. And I’ve kept a separate, non-network access path (console/out-of-band) available too, specifically so that a mistimed IP change during a real outage can’t compound into a full lockout.

The Bigger Lesson

None of this is exotic infrastructure — a DNS record, a small plugin, two firewall objects. But it’s a good small-scale example of something that shows up constantly in the day job too: a control that looks complete in isolation often has a hidden dependency that only surfaces under specific conditions. “Just allowlist the IP” is a perfectly fine instruction right up until someone’s home connection sits behind carrier-grade NAT, at which point the naive implementation fails silently instead of loudly.

The fix, in both the homelab and the enterprise version of this problem, is the same: don’t treat any single control as sufficient on its own. Layer the dynamic allowlist behind the VPN, keep an out-of-band path alive, and build in the assumption that any one piece — DNS propagation, a NAT pool reassignment, a tunnel daemon crashing — will eventually fail at an inconvenient time. The goal isn’t a system that never breaks. It’s one where a single break doesn’t turn into a 2am lockout. The same defense-in-depth instinct shows up again later in locking down Authelia’s own 2FA setup — never trusting that one layer rendering correctly means the whole chain behind it actually works.

That’s the version of “secure by default” I actually trust — not because it’s clever, but because it assumes its own cleverness will eventually be wrong about something.

For a long time, my fail2ban setup did exactly what fail2ban is supposed to do, and I was perfectly happy with it. Watch the logs, count the failures, ban the IP at the host firewall level via nftables. WordPress brute-forcers, badbots scraping for wp-login.php, the usual cast of characters — all of them got banned, all on the backend server itself.

The problem with that picture only became obvious once I actually thought about where the ban was happening. My backend, the box running Apache and ISPConfig and all the actual application logic, sits behind OPNsense and HAProxy, with a WireGuard tunnel carrying the traffic between the two boxes in the first place. Every single request that gets banned by fail2ban has already traveled all the way from the internet, through OPNsense, through HAProxy, before fail2ban even gets a chance to say no. The ban was real, but it was the last possible line of defense, not the first. Every blocked request still cost me a hop through the entire stack before being rejected.

That’s the itch this post scratches: take the bans fail2ban is already correctly deciding on, and push them out to the actual edge — OPNsense itself — so the next attempt from that IP never even reaches HAProxy, let alone the backend. The attacker gets stopped at the door instead of in the living room.

Why this isn’t a five-minute job

The annoying part of this problem is that fail2ban and OPNsense don’t speak the same language. fail2ban lives on a Linux box and bans IPs using nftables or iptables rules, scoped entirely to that machine. OPNsense is a separate firewall appliance running pf, with its own rule engine and its own way of thinking about IP lists, called aliases. There’s no built-in bridge between the two. fail2ban has no idea OPNsense exists, and OPNsense has no idea fail2ban exists. If you want one to inform the other, you have to build that bridge yourself.

OPNsense, fortunately, gives you a reasonable on-ramp: a URL Table (IPs) alias type, found under Firewall → Aliases. Instead of manually typing a static list of IPs into an alias, you point this alias type at a URL, and OPNsense periodically fetches that URL, expecting a plain text file with one IP per line, and uses the contents as a dynamically updating block list. That’s the missing piece — if I can get fail2ban to maintain a text file with all its currently-banned IPs, and serve that file somewhere OPNsense can reach, the rest is just OPNsense doing what it already knows how to do.

So the pipeline has three parts: a script that asks fail2ban “who’s currently banned, across every jail you’re running” and writes that to a file; a way to serve that file so OPNsense can fetch it; and an OPNsense-side alias and firewall rule that actually uses the list to block traffic at the WAN edge.

Part one: asking fail2ban what it knows

fail2ban already tracks every jail’s banned IPs internally — you can query any individual jail with fail2ban-client status <jailname>, and it’ll show you a Banned IP list line. The annoying bit is that if you’re running several jails (and most reasonably hardened setups are — separate jails for WordPress login attempts, badbots, 404 floods, and so on), you need to loop over all of them and merge the results, deduplicated, into one list.

bash

#!/bin/bash
OUTPUT_FILE="/home/user/dmz-stack/caddy/banlist/banned.txt"
TMP_FILE="$(mktemp)"

for jail in $(fail2ban-client status | grep "Jail list" | sed 's/^.*://;s/,//g'); do
    fail2ban-client status "$jail" | grep "Banned IP list" | sed 's/^.*://' | tr ' ' '\n'
done | grep -v '^$' | sort -u > "$TMP_FILE"

mv "$TMP_FILE" "$OUTPUT_FILE"
chmod 644 "$OUTPUT_FILE"

This is deliberately unfancy. fail2ban-client status with no jail name lists every active jail; the loop asks each one for its banned IPs, strips the label text fail2ban prepends, and splits the space-separated list onto individual lines. Sorting and deduplicating means it doesn’t matter if the same IP shows up in two jails — it lands in the output file exactly once. The mktemp-then-mv pattern matters more than it looks like it should: writing directly to the final file risks OPNsense fetching a half-written file mid-update, while writing to a temp file and atomically moving it into place guarantees whoever reads banned.txt always sees a complete, consistent snapshot.

Drop this in /usr/local/bin/export-fail2ban-bans.sh, make it executable, and you’ve got the first link in the chain. Run it manually once and cat the output file to sanity-check it’s actually populated with real-looking IPs before moving on.

Part two: serving the file without opening a new can of worms

Now OPNsense needs to fetch this file over HTTP. The lazy option is to drop it somewhere your existing web server already serves — but I didn’t want a list of banned IPs sitting in a publicly browsable directory, even an obscure one, so I gave it its own dedicated, narrowly scoped route instead.

Since I already run Caddy as my reverse proxy in front of everything else, adding one more tightly restricted route was the path of least resistance:

caddyfile

:8090 {
  @opnsense remote_ip 172.18.32.1
  handle @opnsense {
    root * /srv/banlist
    file_server
  }
  handle {
    abort
  }
}

That remote_ip matcher is doing the actual security work here — only requests originating from OPNsense’s own WireGuard IP get served anything; everyone else hits abort, which just drops the connection outright rather than politely saying “no” with an HTTP error (politely saying no still tells a port-scanner something is listening). Putting this on its own port, 8090, separate from your normal 80/443 traffic, also means a casual look at access logs for your real sites never gets cluttered with OPNsense’s periodic polling requests. Mount the directory containing banned.txt into the container, expose the port in your compose file, and this half is done.

Part three: getting OPNsense to actually act on it

Inside OPNsense’s web UI, go to Firewall → Aliases and create a new alias. Set the type to URL Table (IPs), point the content field at the internal address of wherever you’re serving the file from — in my case http://172.18.32.11:8090/banned.txt, reachable over WireGuard — and set a refresh frequency. I run mine on a 5-minute cadence, which, combined with fail2ban’s own cron job re-running the export script every five minutes too, means worst-case latency between a ban happening and OPNsense enforcing it at the edge is comfortably under ten minutes. That’s not instant, but it’s a different category of protection than “eventually gets blocked after wasting a hop through my whole stack every single time.”

Once the alias exists and OPNsense has successfully fetched it at least once (you can confirm this under the alias’s own details view, which shows the current resolved IP count), the last step is actually using it. Go to Firewall → Rules → WAN, add a new rule with action Block, source set to your new alias, and — this part actually matters — drag the rule to the very top of the WAN rule list. Firewall rules are evaluated top-to-bottom, first match wins, and if some broader “allow” rule sits above your block rule, the block never gets a chance to fire.

Testing it without waiting for a real attacker

I didn’t want to wait around for an actual bot to get banned just to confirm the whole pipeline worked end to end, so I manually banned a couple of made-up test IPs directly through fail2ban (fail2ban-client set <jail> banip 203.0.113.99), ran the export script by hand, and watched the alias refresh in the OPNsense UI to confirm the count ticked up and the test IP appeared in the resolved list. Unbanning the same way and re-running the export confirmed it cleared correctly too. This kind of synthetic round-trip test is worth doing deliberately rather than trusting the pipeline blind — it’s much easier to debug a test IP that you know should or shouldn’t be there than to debug a real attacker’s IP weeks later while also wondering whether the pipeline ever worked at all.

What this actually buys you

It’s tempting to think of this as a marginal optimization — fail2ban was already blocking these IPs, so who cares if the block happens one hop earlier? But the difference compounds in ways that aren’t obvious until you’ve lived with it. Every blocked request that used to traverse OPNsense, HAProxy, and reach the application layer before being rejected was still consuming connection slots, CPU cycles, and log lines at every layer along the way. Pushing the block to the WAN edge means a banned attacker’s retry traffic gets silently dropped before it ever touches HAProxy’s connection table, which matters more than you’d expect once you’re also running Suricata and CrowdSec at that same edge — fewer packets reaching the inspection layers means cleaner signal in those tools too, since they’re not wading through traffic that’s already a known, settled case. Hardening Your Homelab’s Public Edge covers that GeoIP/CrowdSec layer in full — worth noting that post describes a different fail2ban-to-OPNsense sync method (a direct API push from fail2ban itself) than the pull-based, flat-file approach built here, so treat them as two alternative implementations rather than the same pipeline described twice.

There’s also a quieter benefit: once this pipeline exists, it becomes the natural place to plug in anything else that produces a list of bad IPs. CrowdSec’s own community blocklist already feeds OPNsense through a similar mechanism; Suricata’s alert-driven blocks could, in principle, feed the same kind of alias. The pattern — local detection, exported as a flat list, consumed by the edge firewall as a dynamic alias — turns out to be a reusable shape for tying together security tools that were never designed to talk to each other directly. fail2ban doesn’t need to know OPNsense exists, and OPNsense doesn’t need to know fail2ban exists. They just both need to agree on the shape of a text file, and that turns out to be enough.

This same “trust based on network origin, not credentials” idea reappears in two later posts: the network-scoped Authelia bypass for Open WebUI’s search calls, and the self-updating anti-lockout alias for remote firewall management — both are the same alias-driven, dynamically-resolved trust pattern used here, just applied to allowing traffic instead of blocking it.

Under the hood, one of my apps has no idea Authelia exists. The other one talks to it directly, as a first-class citizen, using a protocol with its own handshake, its own tokens, its own opinions about what a “user” even is. Get this distinction wrong — or worse, not realize it’s a distinction at all — and you’ll spend an evening debugging a problem that looks like a bug but is actually a category error. I know this because I did exactly that a few weeks later, but that’s a story for a different post.

For today: how do you actually wire Authelia in front of Open WebUI and Nextcloud, and why are these two setups fundamentally different shapes, not just different flavors of the same thing?

The app that doesn’t know it’s protected

Open WebUI, like a lot of self-hosted tools, was never built with an external identity provider in mind. It has its own login form, its own user table, its own idea of “logged in.” If I want Authelia sitting in front of it, I’m not integrating with Open WebUI’s authentication — I’m overriding it from the outside, before any of its own login logic ever runs.

This is forward-auth, and the mental model is simpler than the name suggests: Caddy intercepts every request to openwebui.yourdomain.com and, before it reverse-proxies anything to Open WebUI, makes a side-channel call to Authelia asking one question — “is this person allowed in?” If Authelia says yes, Caddy lets the request through to Open WebUI exactly as if nothing happened. If Authelia says no, the visitor gets redirected to a login page, and Open WebUI never even sees the request.

The forward-auth block in my Caddyfile looks roughly like this:

caddyfile

(forward_auth_block) {
  forward_auth authelia:9091 {
    uri /api/verify?rd=https://authelia.yourdomain.com
    copy_headers Remote-User Remote-Groups Remote-Name Remote-Email
  }
}

openwebui.yourdomain.com:80 {
  import forward_auth_block
  reverse_proxy openwebui:8080
}

Two things matter here that are easy to skim past. First, copy_headers — once Authelia approves the request, it hands back a set of headers identifying who just logged in, and Caddy stitches those onto the request before it reaches Open WebUI. Second, and this is the part that actually matters for day-to-day reliability: Open WebUI still has no idea any of this happened. It sees a request arrive, optionally with some Remote-User-style headers it may or may not even read, and that’s it. As far as Open WebUI’s own code is concerned, Authelia doesn’t exist.

That’s the whole trick of forward-auth. It’s a bouncer standing in front of a door, not a doorman the building hired. The building’s own systems are completely unaware there’s anyone checking IDs outside. This is also exactly why it works for literally any app — Open WebUI, a dashboard, an internal wiki, whatever — regardless of whether that app has ever heard of OIDC, SAML, or any authentication standard at all. If it speaks HTTP, you can put a forward-auth gate in front of it. (This is the exact same forward_auth_block reused later, almost verbatim, to gate a self-hosted SearXNG instance behind Authelia too.)

The tradeoff is just as structural. Because the protected app doesn’t know about Authelia, it also doesn’t really know who’s logged in beyond whatever you choose to pass through those headers. There’s no rich user object, no group claims baked into a token the app can inspect on its own, no session the app controls. Everything the app “knows” about the user is whatever you handed it in a header, and if that header mapping is wrong or missing, the app just falls back to whatever its own default behavior is — which, for Open WebUI, meant new accounts landing in a “pending” status that I had to manually promote the first time around. The app isn’t broken; it’s just genuinely in the dark about the bigger picture.

The app that wants to know you personally

Nextcloud is a different animal entirely, because user_oidc isn’t a gate in front of Nextcloud — it’s a plugin running inside Nextcloud that speaks OpenID Connect directly to Authelia. There’s no bouncer here. Nextcloud itself walks up to Authelia, introduces itself with a client ID and secret, and asks for a proper, structured answer: who is this person, what’s their email, what groups are they in, and here’s a signed token to prove you’re not lying to me.

This is OIDC done the way the spec actually intends it, and it shows in how much more Nextcloud knows once the dance is over. Setting it up means configuring an actual client relationship between the two systems, not just a header-passing convention:

bash

docker exec -u www-data nextcloud php occ user_oidc:provider authelia \
  --clientid="nextcloud" \
  --clientsecret="..." \
  --discoveryuri="https://authelia.yourdomain.com/.well-known/openid-configuration"

That discovery URI is doing a lot of quiet work. Nextcloud fetches it once, learns where Authelia’s authorization endpoint, token endpoint, and signing keys all live, and from then on the two systems are talking a real protocol with real cryptographic guarantees — not just trusting whatever headers happen to show up. When I log in through Nextcloud’s web UI, I’m redirected to Authelia, I authenticate there (TOTP and all), and Authelia hands back a signed JWT containing claims: email, groups, name, sub. Nextcloud reads that token directly and uses it to provision or update my account.

This is the crucial difference. Open WebUI never sees a token — it sees headers Caddy chose to forward. Nextcloud sees an actual cryptographically signed identity document and parses it itself. That gives Nextcloud a much richer, more reliable picture of who’s logging in — group membership for access control, email for notifications, display name for the UI — all sourced directly from the identity provider rather than relayed secondhand through a proxy’s header rewriting.

It also means Nextcloud has opinions about how it builds a user from that token, and those opinions matter more than they look like they should. By default, user_oidc uses the sub claim — a stable, unique identifier Authelia generates — as the internal Nextcloud account ID. That’s the technically correct choice for uniqueness, and it’s also a UUID, not anything resembling a username. I didn’t think about this at all when I set it up, because why would I — the login worked, I could see my files, case closed.

It came back to bite me weeks later in a completely different context (ask me about the desktop sync client some other time), but the shape of the problem is worth flagging here: with forward-auth, the protected app never had to make a decision about identity at all, because it was never given the opportunity. With native OIDC, the protected app is making real decisions — how to map claims to accounts, what becomes the username, whether to provision automatically or require a pre-existing account — and every one of those decisions is a place a default can surprise you.

Same login screen, two different trust relationships

Step back far enough and the distinction is really about where the trust boundary sits. With forward-auth, the trust boundary is at the edge — Caddy and Authelia have a private conversation, and the app behind them is simply handed a verdict. The app trusts Caddy to have done its job; it has no independent way to verify anything, and it doesn’t need one, because it was never designed to.

With native OIDC, the trust boundary moves inside the app itself. Nextcloud doesn’t trust Caddy’s opinion about who’s logged in — Caddy, in fact, is barely involved in the authentication conversation at all beyond passing bytes back and forth. Nextcloud independently verifies a cryptographic token against keys it fetched from Authelia’s discovery document. It’s a direct relationship between the two systems, with the reverse proxy reduced to plumbing.

Neither pattern is strictly better — they solve different problems. Forward-auth is the right tool when you want to blanket-protect something that was never built with SSO in mind, and you’re willing to accept that the protected app will only ever know what you choose to tell it. Native OIDC is the right tool when the app actually needs to reason about identity — assign permissions by group, send mail to the right address, distinguish “logged in as Marco” from “logged in as some anonymous header value” — and you’re willing to take on the deeper integration work and the protocol-level decisions that come with it.

What I’d tell past-me, a few weeks before the desktop sync client incident: when you wire up native OIDC, go look at exactly what claim becomes the account ID, on purpose, before you start using the account for anything real. It’s a five-minute check during setup. It’s a multi-hour debugging session if you skip it and only find out later, indirectly, through a symptom that looks like it’s about something else entirely.

Same login screen. Two completely different conversations happening behind it. Worth knowing which one you’re having before you need to debug it.

This same forward-auth-versus-native-protocol distinction is worth keeping in mind for the network-scoped Authelia bypass too — Open WebUI’s web-search calls to SearXNG hit an API directly, with no forward-auth bouncer able to intercept them the normal way, which is exactly why that post needed a different kind of trust rule instead.

Once you have public services running behind OPNsense and HAProxy, you quickly notice something: the internet is noisy. Within hours of exposing port 443, the logs start filling with probes for /wp-login.php, /.env, random PHP shells, and credential stuffing attempts against anything that looks like a login page. Most of it is automated. Almost none of it is your real users.

This post is about the three layers I use to keep that noise out — and to make sure that when something does slip through, it doesn’t get a second try:

1. GeoIP blocking at the firewall, to drop traffic from regions I have no business serving.
2. CrowdSec, to share threat intelligence and block known bad actors automatically.
3. Syncing Fail2Ban logs from my webservers back to OPNsense, so that an attack on a single host turns into a network-wide block.

Each layer is simple on its own. Together, they cut the attack surface dramatically.

The Mental Model

Before the config, the philosophy:

• The firewall should do as much filtering as possible, as early as possible. A packet that’s dropped at OPNsense never reaches HAProxy, never reaches the webserver, and never burns CPU on your application.
• The webserver knows things the firewall doesn’t. It sees failed logins, application-level abuse, and patterns the firewall can’t infer from packet headers alone. That knowledge needs to flow back to the firewall.
• Reputation beats reaction. Blocking an attacker after they’ve hit you is fine. Blocking them before they’ve hit you — because someone else already reported them — is better.

GeoIP handles bulk noise. CrowdSec handles shared reputation. Fail2Ban-to-OPNsense sync handles what only your own services can see. The three together form a feedback loop.

Layer 1: GeoIP Blocking in OPNsense

GeoIP isn’t a security solution by itself — a determined attacker will use a VPN or a cloud instance in a country you allow. But it’s an extraordinarily cheap way to drop the volume of automated attacks, which mostly originate from a predictable handful of regions.

Setup

OPNsense uses MaxMind’s GeoLite2 database via aliases. The high-level steps:

1. Get a free MaxMind license key. Register at maxmind.com and generate a license key under your account.
2. Configure the GeoIP source in OPNsense. Under Firewall → Aliases → GeoIP settings, paste the MaxMind download URL with your license key. OPNsense will pull the database on a schedule.
3. Create GeoIP aliases. Under Firewall → Aliases, create a new alias of type GeoIP, and pick the countries you want to group together. I keep two aliases:
   • GeoIP_Allow — countries where my actual users live.
   • GeoIP_HighRisk — countries that show up disproportionately in my logs as sources of automated attacks.
4. Apply the alias in your WAN-facing rules. On the firewall rule that allows inbound traffic to HAProxy (port 443 from the WireGuard tunnel), add a block rule above it that drops traffic from GeoIP_HighRisk. Or, if you want to be stricter, use a default-deny model: only allow traffic from GeoIP_Allow, and let everything else fall to a deny rule.

A Word of Caution

GeoIP blocking is a blunt tool. Two things to watch for:

• Legitimate users on VPNs or mobile carriers sometimes appear from unexpected countries. If you serve a global audience, default-deny will hurt you. Default-allow with a high-risk blocklist is usually the better compromise.
• CDN and monitoring traffic (uptime checks, search engine crawlers) may originate from regions you’d otherwise block. Whitelist their IP ranges explicitly above the GeoIP rule.

I treat GeoIP as layer one of noise reduction, not as security. It’s the bouncer who turns away the obvious troublemakers before they get to the door.

Layer 2: CrowdSec

CrowdSec is the layer I’m most enthusiastic about. The short pitch: it’s a modern, open-source alternative to Fail2Ban that not only detects local attacks but also shares anonymized signals with a community blocklist. If a thousand other CrowdSec users are being hit by a particular IP, you benefit from that knowledge automatically.

Architecture

There are two pieces:

• The CrowdSec agent — reads logs, detects malicious behavior, and reports it.
• The bouncer — enforces decisions. There’s an official OPNsense plugin that acts as a firewall bouncer, pulling the blocklist and applying it as a pf table.

You can run the agent on OPNsense itself, on your webservers, or both. I run agents on the webservers (where the interesting logs live) and the bouncer on OPNsense (where blocks are most effective).

Setup on OPNsense

1. Install the OPNsense CrowdSec plugin from System → Firmware → Plugins (os-crowdsec).
2. Enroll the instance with the CrowdSec Console (free tier is fine for a homelab). Enrollment lets you manage decisions across multiple agents from one dashboard.
3. Enable the firewall bouncer. It will create a pf table that’s automatically populated with malicious IPs from both your local detections and the community blocklist.
4. Add a block rule referencing the CrowdSec table, placed near the top of your WAN/tunnel-facing rules — above GeoIP and any allow rules.

Setup on the Webservers

1. Install the CrowdSec agent on each webserver (Debian/Ubuntu packages are straightforward).
2. Enable the relevant parsers and scenarios — nginx, apache2, sshd, http-cve, base-http-scenarios, etc. CrowdSec ships with a hub of community-maintained detection rules.
3. Forward decisions to OPNsense. There are two ways:
   • Run a local bouncer on each webserver (e.g., the iptables or nginx bouncer) so blocks happen at the host level too.
   • More importantly, configure the webserver agent to share decisions with the central OPNsense agent via the CrowdSec API. This is where one webserver’s detection becomes a firewall-level block for everything.

Why I Like It

CrowdSec gets you three things Fail2Ban alone doesn’t:

• Community blocklist. You’re blocking known-bad IPs before they ever touch your services.
• Centralized decisions. Multiple agents, one source of truth, one bouncer enforcing at the firewall.
• Better scenarios. Detection rules are written and maintained by a community, not by you at 2 a.m. after an incident.

It doesn’t replace Fail2Ban entirely in my setup — but it carries most of the load.

Layer 3: Syncing Fail2Ban Logs from Webservers to OPNsense

Some things Fail2Ban catches that CrowdSec scenarios might not — custom application logs, niche services, anything you’ve written a bespoke filter for. I still want those bans enforced at the firewall, not just on the host that detected them.

The goal: when Fail2Ban bans an IP on any webserver, that IP gets blocked at OPNsense for everyone.

There are a few ways to do this. Here’s the approach I use, in order of complexity. (Note: this is the API-push method. From App Logs to Firewall Blocks documents a different, pull-based method for the same goal — exporting bans to a flat file that OPNsense fetches on a timer via a URL Table alias, rather than pushing them via API call on every ban. Worth treating as two alternative approaches rather than the same pipeline twice.)

Option A: Fail2Ban → OPNsense Alias via API (Cleanest)

OPNsense exposes a REST API that can manipulate aliases. The flow:

1. Create a host-type alias on OPNsense called something like Fail2Ban_Sync. This alias will hold the IPs to block.
2. Add a firewall rule that drops traffic from Fail2Ban_Sync, placed at the top of your WAN/tunnel rules.
3. On each webserver, configure a Fail2Ban action that, on ban, calls the OPNsense API to add the IP to the alias, and on unban, removes it.

The action script lives in /etc/fail2ban/action.d/opnsense-alias.conf and uses curl to hit the OPNsense API. You’ll need an API key with permission to modify aliases — create a dedicated user with the minimum scope, and store the credentials in a file readable only by root.

A simplified outline of the action:

ini

[Definition]
actionban   = curl -s -u "$API_KEY:$API_SECRET" \
              -X POST "https://opnsense.lan/api/firewall/alias_util/add/Fail2Ban_Sync" \
              -H "Content-Type: application/json" \
              -d '{"address":"<ip>"}'

actionunban = curl -s -u "$API_KEY:$API_SECRET" \
              -X POST "https://opnsense.lan/api/firewall/alias_util/delete/Fail2Ban_Sync" \
              -H "Content-Type: application/json" \
              -d '{"address":"<ip>"}'

Reference that action in your jail.local:

ini

[nginx-http-auth]
enabled  = true
action   = opnsense-alias
filter   = nginx-http-auth
logpath  = /var/log/nginx/error.log
maxretry = 3
bantime  = 86400

Now every ban on the webserver is mirrored to OPNsense within seconds.

Option B: Shipping Logs Centrally and Letting CrowdSec Handle It

If you’re already running CrowdSec, you can also ship webserver logs to a central CrowdSec agent (or use the CrowdSec multi-server setup), and let CrowdSec handle the detection-to-block pipeline. This is cleaner long-term but means moving away from Fail2Ban for those specific filters.

I run a hybrid: CrowdSec for the well-known patterns, Fail2Ban-with-API-sync for the bespoke ones I haven’t ported yet.

Option C: Syslog Forwarding

You can also forward Fail2Ban logs to OPNsense via syslog and parse them there. This is more fragile (parsing logs you didn’t generate is always a tax) and I’d recommend the API approach instead.

Putting It Together: Rule Order Matters

The order of firewall rules on the WAN-facing / tunnel-facing interface matters a lot. Mine looks roughly like this, top to bottom:

1. Allow known-good monitoring and CDN IP ranges (explicit whitelist).
2. Block CrowdSec table.
3. Block Fail2Ban_Sync alias.
4. Block GeoIP_HighRisk alias.
5. Allow HTTPS to HAProxy from the tunnel.
6. Default deny (implicit).

The principle: cheap, high-confidence blocks first; expensive or broader rules later. A packet from a known-bad IP gets dropped before GeoIP even has to look at it.

Operational Notes

A few things I’ve learned running this setup:

• Whitelist yourself. Add your own admin IPs (and your monitoring) to a Whitelist alias that’s referenced above all block rules. The day you lock yourself out because Fail2Ban banned your home IP is the day you build this safeguard — or better, build it before that day, the way Never Lock Yourself Out describes for a dynamic, CGNAT-aware home IP rather than a static one.
• Set sensible bantimes. Permanent bans grow your alias forever and eventually cause performance issues. I use 24 hours for most jails, 7 days for repeat offenders, and a separate manual alias for permanent blocks.
• Monitor the size of your aliases. If your Fail2Ban_Sync alias is growing by thousands of entries a day, something is misconfigured — probably a filter that’s too aggressive.
• Test from outside. Use a VPN or a phone on cellular to verify that blocks actually work from the public side, not just from your LAN.
• Keep an audit trail. Log every API call to OPNsense from your webservers. If you ever wonder why an IP is blocked, you want to be able to answer that question.

The Bigger Picture

What I like about this setup isn’t any one tool — it’s that each layer has a clear job and the layers compose cleanly:

• GeoIP removes bulk noise based on geography.
• CrowdSec removes traffic from IPs that other people have already flagged.
• Fail2Ban sync turns local detections into network-wide blocks.
• HAProxy (from the previous post) decides what gets routed where.
• VLAN segmentation (also from the previous post) ensures that even successful intrusions have a tiny blast radius.

No single layer is doing all the work. If one fails or is misconfigured, the others still hold. That’s the part worth taking away — not the specific commands, but the layered, composable design. It’s the same principle that applies to almost any system worth running: small, focused pieces that each do their job well, and that fail in ways the rest of the system can absorb.

The same composable, defense-in-depth instinct shows up again in Locking Down Authelia — never trusting that one layer rendering correctly (a login page) means the whole chain behind it (2FA, real SMTP delivery, TLS validation) actually works.

If you’re running a similar setup or solving the same problem differently, drop a note. The best part of the homelab community is comparing notes — and the best part of layered security is that everyone’s stack teaches you something new.