Overview

Users can become locked out when 2FA verification fails repeatedly, email access is lost, or codes expire. Administrators can quickly restore access using these recovery procedures.

Common Lockout Scenarios

Scenario 1: Too Many Failed Attempts

User exceeded maximum failed 2FA attempts
Account temporarily locked for security
Typically: 5 attempts = 15 minute lockout

Scenario 2: Lost Email Access

User no longer has access to email

Can’t receive verification codes

Email address needs updating

Scenario 3: Email Delivery Issues

Verification codes not arriving

SMTP or email configuration problems

User can’t proceed with login

Quick Recovery: Disable 2FA

Method 1: WordPress Admin Panel

Step 1: Navigate to user:

• Log into WordPress admin as Administrator

• Go to Users → All Users

• Find locked-out user

• Click “Edit”

Step 2: Disable 2FA:

Scroll to “Two-Factor Authentication” section

Current Status: ✅ Enabled (User is locked out)

Actions:

[Disable 2FA for this User]

[Reset Failed Attempts Counter]

[Send New Verification Code]

Step 3: Choose action:

For lockout: Click “Reset Failed Attempts Counter”

For email issues: Click “Disable 2FA for this User”

For immediate access: Click “Disable 2FA” + “Update User”

Step 4: Notify user:

Contact user via phone/Slack/alternative method:

“Your account access has been restored.

Please log in and update your settings.”

Method 2: Database Direct Edit

If you can’t access admin panel:

-- Connect to MySQL database via phpMyAdmin or command line

-- Find user ID
SELECT ID, user_login, user_email 
FROM wp_users 
WHERE user_login = 'locked_username';

-- Disable 2FA for user (replace 123 with actual user ID)
DELETE FROM wp_usermeta 
WHERE user_id = 123 
AND meta_key = 'attrua_2fa_enabled';

-- Reset failed attempts
DELETE FROM wp_usermeta 
WHERE user_id = 123 
AND meta_key = 'attrua_2fa_failed_attempts';

-- Clear lockout timestamp
DELETE FROM wp_usermeta 
WHERE user_id = 123 
AND meta_key = 'attrua_2fa_locked_until';

Method 3: WP-CLI

For command-line access:

Disable 2FA for specific user
wp user meta delete locked_username attrua_2fa_enabled

Reset failed attempts
wp user meta delete locked_username attrua_2fa_failed_attempts

Remove lockout timestamp
wp user meta delete locked_username attrua_2fa_locked_until

Verify changes
wp user meta list locked_username --keys=attrua_2fa*

Preventing Future Lockouts

Update User Email Address

If email was the problem:

• Users → All Users → Edit User

• Update “Email” field with correct address

• Click “Update User”

• Have user verify new email

• Re-enable 2FA with correct email

Configure Backup Contact Methods

Set up admin notification:

Users → Two-Factor Authentication → Settings

Admin Notifications:

☑ Notify admin when user locked out

Admin Email: admin@example.com

This alerts you immediately when lockouts occur

Adjust Lockout Settings

More lenient settings:

Users → Two-Factor Authentication → Security

Failed Attempt Settings:

Maximum attempts: [10] (default: 5)

Lockout duration: [30] minutes (default: 15)

This gives users more chances before lockout

Provide Recovery Codes

Generate backup codes:

• Edit user profile

• Go to “Two-Factor Authentication” section

• Click “Generate Recovery Codes”

• Give codes to user to store securely

User can use these codes if email fails:

Code 1: ABCD-EFGH-IJKL-MNOP

Code 2: QRST-UVWX-YZAB-CDEF

(each code single-use only)

Bulk Lockout Recovery

Multiple Users Locked Out

Scenario: Email server failure locked out many users

Mass reset via database:

-- Reset ALL 2FA lockouts (use with caution!)
DELETE FROM wp_usermeta 
WHERE meta_key IN (
    'attrua_2fa_locked_until',
    'attrua_2fa_failed_attempts'
);

-- This clears lockouts but keeps 2FA enabled
-- Users can try again immediately

Mass notification:

• Use Users → Bulk Operations → Bulk Email

• Select affected role(s)

• Send message:

“We experienced email delivery issues.

Your account lockout has been cleared.

Please try logging in again.”

When User is Administrator

Locked-Out Admin Recovery

Problem: Only admin locked out, no other admins exist

Solution 1: Create New Admin via Database

-- Create emergency admin account
INSERT INTO wp_users (
    user_login, user_pass, user_email, 
    user_registered, user_status
) VALUES (
    'emergency_admin',
    MD5('TemporaryPassword123!'),  -- Change immediately after login
    'emergency@example.com',
    NOW(),
    0
);

-- Get the new user ID (will be highest number)
SELECT ID FROM wp_users WHERE user_login = 'emergency_admin';

-- Grant administrator role (replace 999 with actual user ID)
INSERT INTO wp_usermeta (user_id, meta_key, meta_value) 
VALUES (999, 'wp_capabilities', 'a:1:{s:13:"administrator";b:1;}');

INSERT INTO wp_usermeta (user_id, meta_key, meta_value) 
VALUES (999, 'wp_user_level', '10');

Then log in as emergency_admin and disable 2FA for original admin.

Solution 2: Emergency Access Code

Add to wp-config.php temporarily:

// EMERGENCY: Disable ALL 2FA
define('ATTRUA_DISABLE_2FA', true);

// After regaining access:
// 1. Remove this line
// 2. Re-enable 2FA
// 3. Update admin email if needed

Logging and Auditing

Track Lockout Events

Check audit log:

Users → Audit Log

Filter by:

Event Type: “2FA Failed Attempt”

Event Type: “User Locked Out”

Event Type: “2FA Disabled by Admin”

Review patterns:

• Frequent lockouts may indicate attack

• Multiple users = email configuration issue

• Same user repeatedly = training needed

Document Recovery Actions

Keep records:

Date: 2025-12-13

User: john.doe

Issue: Locked out after 5 failed 2FA attempts

Action: Reset attempts counter via admin panel

Resolved By: admin

Follow-up: Updated user email, provided recovery codes

User Education

Prevent Lockouts Through Training

Communicate to users:

Email template:

Subject: Important: Two-Factor Authentication Tips

To avoid account lockouts:

• Keep your email address current

• Save recovery codes in safe place

• Check spam folder for verification codes

• Don’t try more than 3 times if code fails

• Contact helpdesk immediately if issues

Recovery codes: [Provide if applicable]

Helpdesk: support@example.com or ext. 1234

Best Practices