BD Security Firewall

Two-Factor Authentication (2FA) Setup

Updated March 9, 2026 9 min read

What Is Two-Factor Authentication?

Two-factor authentication (2FA) adds a second layer of security to your WordPress login. After entering your username and password, you must also provide a time-based one-time password (TOTP) generated by an authenticator app on your phone. This means that even if someone steals your password, they cannot log in without physical access to your device.

BD Security Firewall supports the standard TOTP protocol (RFC 6238), which is compatible with all major authenticator apps:

  • Google Authenticator (Android, iOS)
  • Authy (Android, iOS, Desktop)
  • Microsoft Authenticator (Android, iOS)
  • 1Password, Bitwarden, and other password managers with TOTP support

Prerequisites

  1. BD Security Firewall must be installed and activated with a valid license.
  2. An administrator must enable 2FA from Security → Settings (see below).
  3. You need an authenticator app installed on your smartphone or computer.

Step 1: Enable 2FA (Administrator)

Before any user can set up 2FA, an administrator must enable it globally:

  1. Go to Security → Settings in the WordPress admin.
  2. Scroll to the Two-Factor Authentication section.
  3. Turn on Enable Two-Factor Authentication.
  4. Under Enforce for Roles, select which user roles should have access to 2FA. Options include:
    • Administrator (selected by default)
    • Editor
    • Author

    Only users with the selected roles will see the 2FA setup on their profile page and be prompted during login.

  5. Optionally, turn on Force Setup to require all users in the selected roles to configure 2FA. Users who have not set up 2FA will be unable to access any admin page until they complete the setup process.
  6. Click Save Settings.

Step 2: Set Up 2FA on Your Profile (TOTP Method)

Each user sets up 2FA individually from their WordPress profile page. There are two ways this can happen: during login (forced setup) or voluntarily from the profile page.

Option A: Setup from Your Profile Page

  1. Go to Users → Your Profile in the WordPress admin.
  2. Scroll down to the Two-Factor Authentication section.
  3. You will see:
    • Status: “Not configured” (in red)
    • A QR code displayed as an SVG image
    • The secret key displayed as a text code (for manual entry)
  4. Open your authenticator app and either:
    • Scan the QR code using your app’s camera/scan feature, or
    • Manually enter the secret key if scanning is not available. The account will appear as “BD Security:your@email.com” in your authenticator app.
  5. Your authenticator app will now display a 6-digit code that changes every 30 seconds.
  6. Enter the current 6-digit code in the verification field on your profile page.
  7. Click Verify & Enable.
  8. If the code is valid, you will see a green “2FA enabled!” confirmation and your backup codes will be displayed (see the Backup Codes section below).

Option B: Forced Setup During Login

If the administrator has enabled Force Setup and you have not yet configured 2FA, you will be required to set it up the next time you log in:

  1. Enter your username and password as usual and click “Log In.”
  2. Instead of reaching the dashboard, you will see the Set Up Two-Factor Authentication page.
  3. The page displays a QR code and your secret key, just like the profile page setup.
  4. Scan the QR code or enter the secret manually in your authenticator app.
  5. Enter the 6-digit code from your authenticator app.
  6. Optionally, check “Trust this device for 30 days” to skip 2FA on this browser for the next 30 days.
  7. Click Verify & Enable 2FA.
  8. You will be shown your backup codes on the next screen. Save them before continuing.
  9. Click “I’ve Saved My Codes — Continue” to complete login and access the WordPress dashboard.

Note: Even without Force Setup enabled, if a user’s role is in the enforced roles list and they have already set up 2FA, they will be prompted for their code at every login (unless the device is trusted).

Step 3: Logging In with 2FA

Once 2FA is set up, the login flow adds a verification step:

  1. Go to your WordPress login page and enter your username and password.
  2. After successful password authentication, you are redirected to the Two-Factor Authentication verification page.
  3. Enter the current 6-digit code from your authenticator app.
  4. Optionally, check “Trust this device for 30 days” so you will not be asked for a code on this browser for the next 30 days.
  5. Click Verify.
  6. If the code is correct, you are logged in and redirected to the WordPress dashboard.

Handling Invalid Codes

If you enter an incorrect code:

  • You will see an error message showing how many attempts remain (e.g., “Invalid code. 4 attempt(s) remaining.”).
  • You have a maximum of 5 attempts per login session.
  • After 5 failed attempts, your pending 2FA session is invalidated and you are redirected back to the login page to start over.
  • The pending 2FA session also expires after 5 minutes of inactivity.

Tip: If codes are consistently rejected, make sure your authenticator app’s time is synchronized. TOTP codes are time-sensitive (30-second windows), and a clock skew of more than 90 seconds will cause failures. The plugin allows a tolerance window of plus or minus one time step (90 seconds total).

Backup Codes

When you first enable 2FA, the plugin generates 10 single-use backup codes. These are your emergency access method if you lose your phone or cannot access your authenticator app.

How Backup Codes Work

  • Each backup code is an 8-character alphanumeric string (e.g., A7K3M9P2).
  • Each code can only be used once. After use, it is permanently consumed.
  • Codes are stored as hashes in the database — the plaintext codes are shown only once when generated.
  • You can see how many backup codes you have remaining on your profile page.

Saving Backup Codes

Backup codes are displayed in two situations:

  1. After initial setup — either on the profile page or during the forced login setup flow.
  2. After regeneration — when you click “Regenerate Backup Codes” on your profile page.

Warning: Backup codes are displayed only once and cannot be retrieved later. Copy them to a secure location immediately — a password manager, a printed sheet stored in a safe, or an encrypted file.

Using a Backup Code

  1. On the 2FA verification page during login, click the link “Use a backup code instead” below the code entry field.
  2. The input field switches to accept an 8-character backup code instead of a 6-digit TOTP code.
  3. Enter one of your unused backup codes.
  4. Click Verify.
  5. If valid, you are logged in and that backup code is consumed (cannot be reused).

To switch back to using your authenticator app code, click “Use authenticator code instead”.

Regenerating Backup Codes

If you are running low on backup codes or suspect they have been compromised:

  1. Go to Users → Your Profile.
  2. In the Two-Factor Authentication section, click Regenerate Backup Codes.
  3. Confirm the action when prompted. This invalidates all existing backup codes.
  4. A new set of 10 backup codes is generated and displayed.
  5. Save the new codes immediately.

Trusted Devices

To avoid entering a 2FA code on every login from your regular devices, you can mark a device as “trusted” for 30 days.

How Trusted Devices Work

  • On the 2FA verification page (during login), check the box “Trust this device for 30 days” before clicking Verify.
  • A secure cookie (bdsec_trusted_device) is set in your browser with a 30-day expiration.
  • On subsequent logins from the same browser, the plugin recognizes the trusted device cookie and skips the 2FA prompt.
  • After 30 days, the cookie expires and you will be asked for a 2FA code again.
  • Expired trusted device entries are automatically cleaned up from the database.

Security note: Only trust devices that you physically control. Do not trust shared or public computers. The trusted device cookie is HttpOnly and Secure (on HTTPS sites), but anyone with access to the browser could bypass 2FA during the trust period.

Managing 2FA on Your Profile

Once 2FA is enabled, your profile page shows the following in the Two-Factor Authentication section:

  • Status: A green checkmark with “Active” text.
  • Backup codes remaining: The number of unused backup codes you have left.
  • Regenerate Backup Codes button — generates a new set of 10 codes (invalidates old ones).
  • Disable 2FA button — completely removes 2FA from your account (see below).

Disabling 2FA

To disable two-factor authentication on your account:

  1. Go to Users → Your Profile.
  2. In the Two-Factor Authentication section, click Disable 2FA.
  3. Confirm the action when prompted.
  4. Your TOTP secret, backup codes, and trusted devices are all deleted.
  5. The page reloads showing “Not configured” status with the option to set up 2FA again.

Note: Administrators can also manage 2FA for other users by editing their profile. If the “Force Setup” setting is enabled, a user who disables 2FA will be required to set it up again on their next login.

Administrator Controls

Administrators have additional capabilities for managing 2FA across the site:

Managing Other Users’ 2FA

Administrators can view and manage 2FA for any user by going to Users → All Users, clicking a user’s name, and scrolling to the Two-Factor Authentication section. From there, an admin can:

  • See whether the user has 2FA enabled
  • See how many backup codes the user has remaining
  • Regenerate backup codes for the user
  • Disable 2FA for the user

Global 2FA Settings

From Security → Settings, administrators control:

  • Master switch: Enable or disable the entire 2FA system.
  • Role enforcement: Choose which roles can use 2FA (Administrator, Editor, Author).
  • Forced setup: Require users in selected roles to set up 2FA or allow it to be optional.

Disabling the master switch does not delete any user’s 2FA configuration — it simply bypasses the 2FA check during login. Re-enabling it will immediately restore 2FA requirements for all configured users.

Technical Details

For those interested in the implementation details:

  • TOTP algorithm: HMAC-SHA1 with a 30-second time step and 6-digit codes, per RFC 6238.
  • Secret key: 20-byte (160-bit) random secret, base32-encoded (32 characters). Generated using PHP’s random_bytes() for cryptographic security.
  • Secret storage: TOTP secrets are encrypted with AES-256-CBC using WordPress salts before being stored in user meta (_bdsec_2fa_secret). They are never stored in plaintext.
  • Code verification window: The current time step plus or minus 1 step (total window of 90 seconds) to account for minor clock drift.
  • Backup code storage: Backup codes are hashed with wp_hash() before storage. Only the hashes are stored in the database — the plaintext codes exist only in memory during generation and display.
  • Pending session: When a user passes password authentication but needs 2FA, a pending session token is stored as a WordPress transient with a 5-minute TTL. The user has up to 5 attempts to enter a valid code before the session is invalidated.
  • Trusted device cookie: A 64-character random hash stored as an HttpOnly, Secure cookie with a 30-day expiration. The hash is also stored in user meta for server-side validation.
  • QR code generation: QR codes are generated as inline SVG using a pure-PHP QR code generator (no external service or API calls).
  • Provisioning URI: Follows the otpauth://totp/ standard with the issuer set to “BD Security” — this is what your authenticator app reads from the QR code.

Troubleshooting

My authenticator app codes are not being accepted

  • Ensure your device’s clock is accurate. Go to your phone’s settings and enable automatic date/time. TOTP codes are time-sensitive, and even a 2-minute clock drift can cause failures.
  • Make sure you are entering the code from the correct account in your authenticator app (look for “BD Security” as the issuer).
  • Codes change every 30 seconds. If a code is about to expire, wait for the next one.

I lost my phone and cannot access my authenticator app

  • Use one of your backup codes to log in (see “Using a Backup Code” above).
  • Once logged in, go to your profile page, disable 2FA, then set it up again with your new device.
  • If you have no backup codes left, contact a site administrator to disable 2FA on your account.

I am an administrator and locked out with no backup codes

  • Connect to your site via FTP, SSH, or your hosting control panel’s file manager.
  • Option 1: Rename the plugin folder from bestdid-security to bestdid-security-disabled to deactivate the plugin. Log in normally, then rename it back and reconfigure 2FA.
  • Option 2: Access your database via phpMyAdmin or WP-CLI and delete the _bdsec_2fa_enabled user meta entry for your user ID.

The QR code is not displaying

  • The QR code is rendered as an inline SVG image. If it does not appear, your browser may be blocking inline SVG content.
  • As a fallback, use the secret key displayed below the QR code area and enter it manually into your authenticator app.