Two-Factor Authentication

Add a TOTP second factor to your admin account for stronger login security.

TL;DR

Go to Admin → top-right user menu → Two-Factor Setup. Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.). Enter the 6-digit code to confirm setup. After that, every admin login will require a verification code.

Details

How It Works

Pubvana implements TOTP (Time-based One-Time Password) two-factor authentication using the spomky-labs/otphp library. TOTP generates a new 6-digit code every 30 seconds, synchronized between your authenticator app and the server using a shared secret key.

Setting Up 2FA

1. Log in to the admin panel.
2. Click your username or avatar in the top-right corner.
3. Select Two-Factor Setup from the dropdown menu.
4. A QR code and a manual entry key are displayed.
5. Open your authenticator app and add a new account:
   • QR code method: scan the code with your camera.
   • Manual method: enter the key shown below the QR code.
6. The app will start generating 6-digit codes every 30 seconds.
7. Enter the current code from your app into the confirmation field on the setup page.
8. Click Confirm & Enable. 2FA is now active on your account.

Logging In With 2FA

After 2FA is enabled, the login flow becomes:

1. Enter your email and password as normal.
2. After successful password verification, you are redirected to /auth/2fa.
3. Enter the current 6-digit code from your authenticator app.
4. On success, a totp_2fa_verified flag is set in your session and you are admitted to the admin panel.

The 2FA check is enforced by the TotpFilter, which intercepts all admin requests. If the session flag is not set, you are redirected to the code entry page regardless of which admin URL you tried to visit.

Disabling 2FA

Return to Two-Factor Setup (same menu location). Click Disable Two-Factor Authentication. Your account immediately reverts to password-only login.

Data Storage

Two fields are added to the users table:

The secret is never displayed after initial setup. If you lose access to your authenticator app, a Super Admin can disable 2FA on your account directly in the database by setting totp_enabled = 0.