Current Status#

TIP

Through persistent effort, both luci-app-2fa and the corresponding login patches have been merged into the official OpenWrt LuCI repository. Users can install the luci-app-2fa package directly in new versions (expected from 25.x onwards).

NOTE

Please visit my independent luci-plugin-2fa repository and give it a Star. Your support is greatly appreciated!

The Origin#

Since its inception in 2004, OpenWrt has served as the foundation for countless router systems. While its features and performance have evolved significantly, the security authentication of its web interface, LuCI, has remained stagnant, relying on the traditional username and password model. In an era of increasingly sophisticated network threats, this single-factor authentication has become insufficient.

At the start of this project, I reviewed community resources and found that the official repository lacked a native 2FA component. Although Issue #8273 showed sporadic community attempts, most stalled due to architectural constraints or lack of maintenance. The most promising attempt was PR #7069, which implemented a basic TOTP algorithm. However, it failed to address the coupling of the login logic, and the original author eventually disappeared, leaving the project abandoned.

Taking on this challenge, I realized that the primary obstacle was not the TOTP algorithm itself, but rather the login architecture that OpenWrt had utilized for over a decade.

Restructuring the Architecture: Redesigning the Login Flow#

While analyzing PR #8281, I discovered that the existing LuCI login chain was overly linear and lacked atomicity. The original logic followed a rigid sequence:

Input Credentials -> Verification -> Immediate Session Generation -> Login Complete

This tightly coupled logic was hardcoded within the core Dispatcher, leaving no room for third-party modules to intervene. Attempting to force 2FA logic into this existing chain would have resulted in bloated and unmaintainable code.

When considering solutions, simply hooking the core Dispatcher file offered a shorter path to implementation, yet such an approach lacked elegance and introduced significant maintenance risks. It would essentially amount to piling more complexity onto existing technical debt. Given the potential need to integrate other authentication methods such as Captcha or WebAuthn in the future, a “patchwork” development style was deemed irresponsible.

To resolve this fundamentally, I engaged in several deep discussions with core OpenWrt developer @systemcrash. These consultations led to the definition and design of a Plugin System. By introducing a multi-stage verification hook mechanism into the login process, we reshaped the flow as follows:

Input Credentials -> Base Verification -> Call Authentication Hooks (2FA/LDAP, etc.) -> Generate Session after total approval

This design transforms 2FA into an optional enhancement plugin, removing the requirement to modify core code for every security feature. Compared to the traditional hardcoded method, this atomic restructuring provides a stable foundation for supporting modern security protocols like WebAuthn.

2FA Implementation Details#

Once the underlying architecture was resolved, the implementation of PR #8280 became straightforward. For the Time-based One-Time Password (TOTP) algorithm, I utilized the existing uqr library to generate the necessary configuration QR codes, thereby minimizing system dependencies.

During development, security and robustness remained the top priorities. Compared to a simple demonstration, code intended for the official repository must account for various edge cases, including:

1. Clock Synchronization: If the router fails to sync via NTP, TOTP verification will fail. To address this, I added prominent synchronization warnings.
2. Emergency Recovery: A backend reset mechanism was implemented in case a user loses their phone or deletes their secret key.
3. UI Adaptation: Ensuring the verification interface renders correctly across various mobile browsers.

The entire process underwent multiple rounds of code review before receiving approval from the official maintainers and being merged into the main branch.

Future Outlook: Embracing WebAuthn#

While current 2FA implementation focuses on TOTP codes, there is still room to improve the user experience. I am currently advancing the development of luci-plugin-webauthn.

Compared to TOTP codes, WebAuthn allows users to authenticate using fingerprints, FaceID, or hardware keys like Yubikey. This represents a leap in both security and convenience, enabling a passwordless login experience. Although this implementation involves more complex cryptographic challenges and browser interactions, I am confident it will become a vital part of the OpenWrt security ecosystem.

Moving from a simple Issue to a final merge into the official main branch has taught me a valuable lesson: in the open-source community, implementing a feature may only require a few lines of code, but building a universal, standard architecture requires deep reflection and a relentless pursuit of detail.