Force-Resetting a Password

When a user is locked out of their email account — because they have forgotten their password, their credentials have been compromised, or a 2FA device has been lost — you can reset their password from the admin panel without knowing the current password.

Resetting a Password#

1. Go to Admin → Accounts.
2. Find the account. Use the search field to filter by email address.
3. Click the account email to open the detail view.
4. Click Reset Password.
5. Enter the new password in the New Password field, and again in Confirm Password.
6. Click Save Password.

The new password hash is written to mail_accounts.password immediately. The user can log into webmail (and any IMAP/SMTP client) using the new password right away. No restart or cache flush is needed.

Password Format and Dovecot Compatibility#

The password is stored in a hashed format compatible with your Dovecot configuration. By default, Opterius Mail stores passwords using bcrypt ({BLF-CRYPT}), which Dovecot's SQL auth driver verifies natively.

If your Dovecot is configured to expect SHA512-CRYPT (common on older installations or those migrated from cPanel), set the following in .env:

DOVECOT_PASSWORD_SCHEME=SHA512-CRYPT

Opterius Mail will then store passwords in the corresponding format for all new password saves.

Do not mix password schemes in the same installation. If you change the scheme, existing passwords remain in their original format (Dovecot will reject them). Use the Reset Password action to re-hash them in the new format.

Important: Panel Sync Behaviour#

Password flow in a panel-integrated setup is one-directional:

Opterius Panel  →  (sync)  →  Opterius Mail

Opterius Mail never pushes passwords back to the Panel. This means:

• If you reset a user's password in the Opterius Mail admin panel, the Panel does not know about the change.
• The user's Panel account still shows the old password.
• The next time the Panel syncs this account (e.g., user changes their password in the Panel), the Panel's version overwrites the one you set in Mail.

Best practice: When resetting a password for a panel-integrated account, also reset the password in Opterius Panel so both systems remain consistent. Direct the user to log into the Panel and set a new password through the normal user flow, or use the Panel admin to set it.

If you are in a situation where you must reset the password urgently and cannot immediately update the Panel, inform the user that they will need to update their password in the Panel as well.

2FA Is Not Affected by Password Reset#

Resetting a password does not disable or bypass two-factor authentication. If the user has 2FA enabled (user_two_factor table) and is locked out because they lost their authenticator app, a password reset alone will not restore access.

To handle a 2FA lockout, you must also disable 2FA for the account:

1. Go to Admin → Accounts → [Account] → Security.
2. Click Disable Two-Factor Authentication.
3. Confirm with your admin password.

The user will be able to log in with their (newly reset) password without being prompted for a 2FA code. They can then re-enroll 2FA from webmail → Settings → Security.

CLI Password Reset#

If you need to reset a password without access to the admin panel (e.g., during a recovery scenario where the panel itself is inaccessible), you can do it from the command line:

cd /opt/opterius-mail
php artisan mail:account:password user@example.com "newpassword123"

The Artisan command applies the same password hashing logic as the admin panel and writes directly to the database.

Security Recommendations#

• Use strong, randomly generated passwords when performing a forced reset. A password manager or the system's openssl rand is appropriate:

  openssl rand -base64 16
  

• Inform the user of the temporary password through a secure channel (not email, since their email is what they're locked out of).
• Ask the user to change the password immediately after regaining access.
• If the lockout was due to a suspected compromise rather than a forgotten password, also check the account's recent login history and consider enabling 2FA after access is restored.