Understanding and Configuring Login with 2FA (v7.2.2+)

Because a broken configuration can lock out every password-based user, including the administrator who enables the feature, verify all of the following BEFORE setting ENABLE_EMAIL_2FA to Y:

1. The Email Server card shows connected on the Status Monitor page (SMTP or Graph API).
   • Metric Insights blocks the save automatically if this check fails.
2. Notifications ON/OFF system-wide is ON.
   • The setting controls all queued email, including 2FA codes. Treat any environment where it's OFF; e.g., dev or staging, as unsafe for 2FA.
3. Every local-password and LDAP user has a current, correct email address. LDAP-synced addresses can go stale, with no bypass if one is missing or wrong.

Access Admin > System > System Variables

1. Enter 2FA in the search field.
2. EMAIL_2FA_ALLOWED_ATTEMPTS: Controls how many incorrect code entries are allowed before the challenge is rejected and the user must restart from the password step.
   • The default is 3. Exceeding this limit also counts toward the existing FAILED_LOGIN_ALLOWED_ATTEMPTS account-lockout threshold.
3. EMAIL_2FA_CODE_EXPIRE_SECONDS: Controls how many seconds an emailed code remains valid before it expires.
   • The default is 600 (10 minutes), and the accepted range is 60 to 600 seconds. After a code expires, the user must restart login.
4. ENABLE_EMAIL_2FA: Set to Y to require an emailed one-time code as a second step for local-password and LDAP logins.
   • Set to N to leave the login flow unchanged for all authentication methods. Allowed values are Y and N; the default is N. This is an instance-wide setting.
5. [Save] and [Commit Changes]

Before relying on 2FA in production, test the full login flow end-to-end with a real password or LDAP test user:

1. Verify that the Prerequisites have been met and 2FA is configured.
2. Open the login page and enter the test user's correct credentials.
3. Confirm the code-entry step appears and a 6-digit code arrives at the user's email within the expiration window as displayed on the screenshot.
4. Enter the code and confirm the start page opens.
5. Log out and log back in to confirm the code is required again on every login.

This section covers the most common scenarios where 2FA can fail once it is already on:

• Issue 1: The mail server was fine at setup, but breaks later.
  • Why it may happen: Metric Insights only checks the Email Server at setup and does not keep re-checking once 2FA is on. If the mail server goes down, is misconfigured, or codes start landing in spam, users stop receiving codes even though ENABLE_EMAIL_2FA is still Y.
  • Solution: Monitor the Email Server card on the Status Monitor page on an ongoing basis, not just before enabling 2FA.
• Issue 2: Email configuration changes after setup.
  • Why it may happen:  If SMTP/Graph API settings, credentials, or the sending domain change after 2FA is enabled, the same silent-failure risk applies. The 2FA code is queued asynchronously, so a broken mail server raises no error at login.
  • Solution: Re-check the Email Server card whenever email configuration changes on a 2FA-enabled instance.
• Issue 3: A production backup is restored into a dev or staging environment.
  • Why it may happen: Dev/staging instances often have email notifications disabled or an invalid mail server. A restored backup carries over ENABLE_EMAIL_2FA = Y, so every password-based login is blocked immediately.
  • Solution: Check ENABLE_EMAIL_2FA and Email Server connectivity as a standard step after any backup restore.