When Authelia Whispers Instead of Speaks: The QR Code Mystery

Authelia’s Silent QR Code: A Lesson in Configuration Over Magic

The task seemed straightforward enough: set up two-factor authentication for the borisovai-admin project using Authelia. The authentication server was running, the configuration looked solid, and the team was ready to enable TOTP-based device registration. But when a user clicked “Register device,” nothing happened. No QR code appeared. Just silence.

The natural first instinct was to assume something broke. Maybe the TOTP endpoint wasn’t responding? Perhaps there was a network issue? But after digging through the Authelia logs and checking the API responses, everything appeared to be working correctly. The registration request was being processed, the system acknowledged it—yet no visual feedback reached the user.

That’s when the real issue revealed itself: Authelia was configured with notifier: filesystem.

Here’s where most developers would have a moment of clarity mixed with mild embarrassment. When you deploy Authelia without configuring email notifications, it defaults to writing registration links directly to the filesystem instead of sending them via email. It’s a sensible fallback for development environments, but it creates a peculiar situation in production. The authentication server diligently generates the QR code registration URL and writes it to a notification file on the server—but there’s no automatic mechanism to display it back to the user’s browser.

The solution required a bit of lateral thinking. Rather than trying to force Authelia to display the QR code through some non-existent UI element, the developer needed to retrieve the notification from the server filesystem directly. A simple SSH command would read the contents of /var/lib/authelia/notifications.txt, exposing the full registration URL that Authelia had generated. That URL, when visited in a browser, would display the actual QR code needed for TOTP enrollment.

This discovery illustrates something fundamental about infrastructure configuration: there’s a difference between a system working and a system working as expected. Authelia was functioning perfectly according to its configuration. The QR code existed—it was just living in a text file on the server instead of being rendered in the browser. The real lesson wasn’t about debugging code; it was about understanding the downstream implications of configuration choices.

For the borisovai-admin project, this meant either reconfiguring Authelia to use proper email notifications or documenting this workaround for the admin team. Either way, the silent mystery became a teaching moment about reading documentation carefully and understanding what your configuration files actually do.

Sometimes the hardest bugs to find are the ones where nothing is actually broken—they’re just misconfigured in ways that create invisible friction. 😄