Two-Factor Authentication (2FA)

Why Use Two-Factor Authentication?

Password protection isn’t enough:

• Passwords can be stolen through phishing, keyloggers, or data breaches
• Users often reuse passwords across multiple sites
• Brute-force attacks can guess weak passwords

2FA provides critical protection:

• ✅ Protects against stolen passwords
• ✅ Stops unauthorized access even if passwords are compromised
• ✅ Provides audit trail of login attempts
• ✅ Required for many compliance standards (PCI, HIPAA, SOC 2)
• ✅ Increases user confidence in your site’s security

Real-world impact: Sites with 2FA enabled see a 99.9% reduction in successful account compromises.

App-Based 2FA (TOTP)

How It Works

TOTP (Time-based One-Time Password) is the industry standard for 2FA:

1. User enables 2FA and scans a QR code with their authenticator app
2. The app generates 6-digit codes that change every 30 seconds
3. During login, user enters username + password, then the current code
4. Server validates the code matches what it expects for the current time
5. User is granted access if both password and code are correct

Important: All code generation and validation happens locally on your server. No data is sent to third parties.

Supported Authenticator Apps

Any app that supports the TOTP standard (RFC 6238) will work:

Popular options:

• Google Authenticator – iOS | Android
• Microsoft Authenticator – iOS | Android
• Authy – iOS | Android
• 1Password – Built-in TOTP support
• Bitwarden – Built-in TOTP support
• Any TOTP-compatible app

Setting Up App-Based 2FA

For Administrators: Enabling 2FA

1. Navigate to Guard Dog → Login Security
2. Find the Two-Factor Authentication section
3. Check “Enable Two-Factor Authentication”
4. Click Save Changes

For Users: Setting Up Their Account

Once enabled site-wide, each user must set up 2FA on their own account:

1. Go to Users → Your Profile (or Profile in the admin bar)
2. Scroll down to Two-Factor Authentication
3. Click “Enable Two-Factor Authentication”
4. Scan the QR code with your authenticator app:

• Open your authenticator app
• Tap “Add account” or “Scan QR code”
• Point your camera at the QR code on screen
• The account will be added automatically

1. Enter the 6-digit verification code shown in your app
2. Click “Verify and Enable”
3. Save your recovery codes (see below)
4. Click Update Profile

Recovery Codes

When you enable 2FA, you’ll receive 10 single-use recovery codes. These are critical for account recovery if you lose access to your authenticator app.

What to do with recovery codes:

✅ DO:

• Print them and store in a secure location
• Save them in a password manager
• Store them in a secure encrypted file
• Take a photo and store in a secure photo vault
• Keep them with other important security documents

❌ DON’T:

• Email them to yourself (email isn’t secure)
• Store them in plain text on your computer
• Share them with anyone
• Throw them away
• Forget about them

Using a recovery code:

1. When logging in, click “Use Recovery Code” instead of entering a TOTP code
2. Enter one of your recovery codes
3. You’ll be logged in successfully
4. That recovery code is now used and won’t work again

If you run out of recovery codes:

1. Go to your profile while logged in
2. Find the 2FA section
3. Click “Generate New Recovery Codes”
4. Old codes are invalidated, new codes are generated
5. Save the new codes securely

Email-Based 2FA

How It Works

Email-based 2FA sends a verification code to the user’s email address:

1. User enters username and password
2. A 6-digit code is sent to their registered email
3. User enters the code from their email
4. User is granted access

Note: Email 2FA requires configuring an email provider (see Email Provider Configuration).

Setting Up Email-Based 2FA

Prerequisites:

• Email provider must be configured (AWS SES, Resend, or SendGrid)
• Users must have valid email addresses

For Administrators:

1. Configure your email provider in Guard Dog → Settings → Email Provider
2. Go to Guard Dog → Login Security
3. In the Two-Factor Authentication section:

• Check “Enable Email Two-Factor Authentication”
• Select your Email Provider
• Configure provider settings

1. Click Save Changes

For Users:

1. Go to Users → Your Profile
2. Find Email Two-Factor Authentication
3. Check “Enable Email 2FA”
4. Click Update Profile
5. Test by logging out and logging back in

Email 2FA vs App-Based 2FA

Feature	App-Based TOTP	Email-Based
Security	Very High	High
Convenience	High (always have phone)	Medium (need email access)
Setup	Requires app install	No setup needed
Works offline	Yes	No (needs email delivery)
Delivery speed	Instant	1-30 seconds
Dependencies	None	Email provider, internet
Best for	Power users, admins	Casual users, clients

Recommendation: Use app-based 2FA for administrators and high-privilege users. Email-based 2FA is fine for regular users.

Enforcing 2FA

1. Go to Guard Dog → Login Security
2. Find “Enforce Two-Factor Authentication”
3. Check the box to enable enforcement
4. Set a Grace Period (days) – Users have this many days to enable 2FA
5. Click Save Changes

You can require all users to enable 2FA:

Mandatory 2FA for All Users

What happens:

• Users without 2FA will see a notice upon login
• They can still access the site during the grace period
• After the grace period, they must enable 2FA before accessing the site
• They’ll be redirected to their profile to set up 2FA

Grace Period

The grace period gives users time to set up 2FA without being locked out:

• 0 days – Immediate enforcement (not recommended)
• 7 days – One week (recommended default)
• 14 days – Two weeks (for larger organizations)
• 30 days – One month (for gradual rollout)

Best practice: Set a grace period of at least 7 days and send an announcement to all users before enabling enforcement.

The 2FA Login Flow

Standard Login (Password + App-Based 2FA)

1. User navigates to login page
2. User enters username and password
3. (If CAPTCHA is enabled, complete CAPTCHA)
4. User clicks “Log In”
5. 2FA verification screen appears
6. User opens their authenticator app
7. User enters the 6-digit code
8. User clicks “Verify”
9. User is logged in

Login with Email-Based 2FA

1. User navigates to login page
2. User enters username and password
3. (If CAPTCHA is enabled, complete CAPTCHA)
4. User clicks “Log In”
5. 2FA verification screen appears
6. User receives email with 6-digit code
7. User enters the code from email
8. User clicks “Verify”
9. User is logged in

Login with Recovery Code

1. User navigates to login page
2. User enters username and password
3. 2FA verification screen appears
4. User clicks “Use Recovery Code”
5. User enters one of their recovery codes
6. User is logged in
7. Recovery code is consumed and can’t be used again

Managing 2FA

Viewing Who Has 2FA Enabled

Currently, you need to check individual user profiles to see their 2FA status. A user list view may be added in a future version.

Disabling 2FA for a User

As an administrator, to disable 2FA for another user:

1. Go to Users → All Users
2. Click Edit on the user’s row
3. Scroll to Two-Factor Authentication
4. Click “Disable Two-Factor Authentication”
5. Click Update User

This is useful if:

• A user lost their device and recovery codes
• You need to help a locked-out user
• An employee left and you’re disabling their account

As a user, to disable your own 2FA:

1. Go to Users → Your Profile
2. Scroll to Two-Factor Authentication
3. Enter your current 2FA code or recovery code
4. Click “Disable Two-Factor Authentication”
5. Click Update Profile

Resetting 2FA Completely

If you need to start fresh:

1. Disable 2FA on your account
2. Save your profile
3. Re-enable 2FA
4. Scan the new QR code (old codes won’t work)
5. Save new recovery codes

Troubleshooting

“Invalid verification code” Error

Possible causes:

1. Time sync issue – Server and phone clocks out of sync
2. Wrong code – Code expired (they change every 30 seconds)
3. Typing error – Entered code incorrectly
4. Wrong account – Using code from different account in app

Solutions:

1. Check phone time:

• Ensure phone is set to automatic time/timezone
• Synchronize authenticator app time (check app settings)

1. Wait for new code:

• Codes change every 30 seconds
• Wait for a fresh code to appear
• Enter it immediately

1. Try again carefully:

• Enter the 6 digits exactly as shown
• Don’t include spaces
• Make sure you’re looking at the right account in your app

1. Use a recovery code:

• Click “Use Recovery Code”
• Enter one of your saved recovery codes

Lost Access to Authenticator App

Option 1: Use Recovery Code

• Click “Use Recovery Code” at 2FA prompt
• Enter one of your recovery codes
• Log in successfully
• Go to profile and disable/re-enable 2FA with new device

Option 2: Administrator Assistance

• Contact a site administrator
• They can disable 2FA on your account
• Log in with just password
• Re-enable 2FA with your new device

Option 3: Database Access

• Access your database (phpMyAdmin)
• Find your user in wp_usermeta table
• Delete the row where meta_key = _guard_dog_totp_enabled
• This disables 2FA for your account

QR Code Won’t Scan

Solutions:

1. Increase screen brightness – QR codes need good contrast
2. Use manual entry:

• Below the QR code, click “Can’t scan?”
• You’ll see a text secret key
• In your auth app, choose “Manual entry”
• Enter the secret key shown

1. Try a different device – Use tablet instead of phone
2. Try a different app – Google Authenticator vs Authy

Email Codes Not Arriving

Possible causes:

1. Email provider not configured – Check Settings → Email Provider
2. Wrong email address – User’s email in profile is incorrect
3. Spam filter – Email went to spam folder
4. Email delivery delay – Provider slowness

Solutions:

1. Check email provider:

• Go to Guard Dog → Settings → Email Provider
• Verify provider is configured correctly
• Test email sending

2. Check spam folder:

• Look in spam/junk mail
• Add sender to safe list

3. Check user email:

• Verify user’s email address is correct in their profile

4. Use app-based 2FA instead:

• More reliable than email delivery

Locked Out Without Recovery Codes

If you’re locked out:

Option 1: Disable Plugin via FTP

1. Access your site via FTP or File Manager
2. Navigate to /wp-content/plugins/
3. Rename guard-dog to guard-dog-disabled
4. Log in with just your password
5. Rename folder back to guard-dog
6. Reconfigure 2FA

Option 2: Database Edit

1. Access phpMyAdmin or database tool
2. Go to the wp_usermeta table
3. Find row where:

• user_id = your user ID
• meta_key = _guard_dog_totp_enabled

1. Delete that row
2. 2FA is now disabled for your account

Best Practices

1. Enable 2FA on admin accounts first – Protect the most privileged users
2. Test thoroughly – Set up on a test account before enforcing
3. Communicate clearly – Tell users why 2FA is being enabled
4. Provide instructions – Share this documentation with users
5. Have a recovery plan – Know how to help locked-out users
6. Use appropriate grace periods – Don’t surprise users
7. Keep recovery codes safe – Treat them like passwords
8. Use app-based for admins – More secure than email
9. Generate new recovery codes periodically – Part of security hygiene
10. Document your process – Keep internal notes on 2FA procedures

Advanced Topics

TOTP Technical Details

Guard Dog uses the TOTP standard (RFC 6238):

• Algorithm: HMAC-SHA1
• Code length: 6 digits
• Time step: 30 seconds
• Time drift tolerance: ±1 time step (30 seconds before/after)

This ensures compatibility with all standard authenticator apps.

Security Considerations

2FA is very secure, but not unbreakable:

✅ Protects against:

• Stolen passwords
• Phishing attacks
• Brute-force attacks
• Database breaches
• Keyloggers

❌ Doesn’t protect against:

• Sophisticated phishing (fake 2FA prompts)
• Malware on user’s device
• Social engineering to get recovery codes
• Physical access to unlocked devices

Additional protections:

• Combine with IP whitelisting for admin users
• Use strong, unique passwords (2FA isn’t an excuse for weak passwords)
• Enable login attempt limiting
• Monitor activity logs for suspicious behavior

Backup Authentication Methods

Always have multiple ways to authenticate:

1. Primary: App-based TOTP
2. Backup: Recovery codes
3. Emergency: Database access to disable 2FA
4. Admin help: Administrator can disable for locked-out users

Never rely on a single method without backups.

FAQ

Q: Is 2FA required?
A: No, it’s optional, but highly recommended for security.

Q: Can I use different authenticator apps?
A: Yes, any TOTP-compatible app works.

Q: Do recovery codes expire?
A: No, they work forever unless you generate new ones.

Q: How many recovery codes do I get?
A: 10 single-use codes.

Q: Can I generate new recovery codes?
A: Yes, anytime from your profile. Old codes are invalidated.

Q: What happens if I change phones?
A: Use a recovery code to log in, then set up 2FA on the new phone.

Q: Can I have 2FA on multiple devices?
A: Yes, scan the same QR code on multiple devices.

Q: Does 2FA slow down login?
A: Minimal impact – adds 5-10 seconds to enter the code.

Q: Can I require 2FA only for admins?
A: Currently enforcement is all-or-nothing. Role-based enforcement may come in future versions.

Q: Does 2FA work with WooCommerce?
A: Yes, 2FA protects WordPress user authentication which WooCommerce uses.