Admin 2FA Controls

Opterius Mail's admin panel provides tools for managing two-factor authentication (2FA) across all user accounts. This page covers force-disabling 2FA for locked-out users, enforcing 2FA globally for all users, and managing the admin's own 2FA configuration.

The admin panel is available when MAIL_ADMIN=true is set in .env. Access it at http://your-server:8090/admin.

Viewing User 2FA Status#

To check whether a user has 2FA enabled:

1. Log in to the admin panel.

2. Navigate to Accounts in the left sidebar.

3. The accounts list shows each user's email address, last login date, and a 2FA status column:

   • Enabled — the user has 2FA active (a row exists in user_two_factor)
   • Disabled — the user has not enabled 2FA

4. Click a user row to open their account detail page, which shows more information including when they enabled 2FA and how many recovery codes they have remaining.

Force-Disabling 2FA for a Locked-Out User#

If a user has lost access to their authenticator app and has no recovery codes left, they cannot log in on their own. You can reset their 2FA as an admin:

1. In the admin panel, go to Accounts and find the locked-out user.
2. Click their email address to open the account detail page.
3. Click Force disable 2FA.
4. A confirmation dialog appears: "This will delete the user's 2FA secret and recovery codes. They will be able to log in with password only."
5. Click Confirm.

The user_two_factor row for this user is deleted. The user can now log in with just their email address and password.

Important: After performing a force-disable, contact the user and advise them to:

1. Log in immediately and change their password (if it may be compromised).
2. Re-enable 2FA with a properly backed-up authenticator and save their new recovery codes.

What Is Deleted#

The force-disable action removes the entire user_two_factor record for the user:

-- This is what the force-disable action executes:
DELETE FROM user_two_factor WHERE email = 'user@example.com';

This includes:

• The TOTP secret
• The recovery code hashes
• The timestamp of when 2FA was enabled

The user's mail_accounts record and all their IMAP data are not affected.

Requiring 2FA for All Users#

You can enforce 2FA across the entire installation so that no user can use the webmail without having 2FA enabled:

1. In the admin panel, go to Admin Settings → Security.
2. Find the Require 2FA for all users toggle.
3. Enable it and click Save.

What Happens When This Setting Is Active#

• Users who already have 2FA enabled: no change, they continue to log in normally.
• Users who log in without 2FA enabled: after entering their email and password, instead of going to the Inbox, they are redirected to the 2FA setup wizard. They must complete setup (scan QR, confirm code, save recovery codes) before they can access their mailbox.
• Users cannot bypass this wizard or close it. The webmail is inaccessible until 2FA is configured.

Disabling the Global Requirement#

To turn off the global 2FA requirement:

1. Go to Admin Settings → Security.
2. Disable Require 2FA for all users.
3. Click Save.

Users who have already configured 2FA keep it active — disabling the requirement does not disable their individual 2FA. Users who had not yet configured 2FA can now log in without it.

Admin's Own 2FA Configuration#

Admin accounts are stored in the admins table, which is separate from the user_two_factor and mail_accounts tables used for webmail users. Admin 2FA is managed through the admin panel's own account settings, not through the webmail settings panel.

To configure 2FA for your admin account:

1. Log in to the admin panel at /admin.
2. Go to Admin → Settings → My Account.
3. Find the Two-Factor Authentication section.
4. Click Enable 2FA and follow the same QR code → confirmation → recovery codes flow as regular users.

Admin 2FA is strongly recommended. Admin accounts have the ability to force-disable other users' 2FA and view account data — securing admin access is critical.

Admin 2FA Recovery#

If you (as an admin) are locked out of the admin panel because you lost your authenticator and have no recovery codes, there is no in-app path to recover. You must reset the admin 2FA directly in the database:

# On the server, run this as a user with database access:
php /opt/opterius-mail/artisan tinker

>>> \App\Models\Admin::where('email', 'admin@example.com')->update(['two_factor_secret' => null, 'two_factor_recovery_codes' => null]);

This clears the admin's 2FA secret, allowing login with password only. Re-enable 2FA immediately after regaining access.

Audit Log#

All admin 2FA actions (force-disable, global requirement changes) are recorded in the Opterius Mail admin audit log:

1. Go to Admin → Audit Log.
2. Filter by Action type: 2FA.

Each entry shows the admin who performed the action, the target user, the timestamp, and the admin's IP address.