Account Merge

Account Merge provides a secure way to link Google sign-in to existing WordPress accounts. Instead of automatic linking, users must verify ownership by entering their existing password.

PRO Feature

Account Merge is a PRO feature. Upgrade to PRO to unlock this functionality.

Why Account Merge?

The Problem

Without Account Merge, automatic email matching could be exploited:

• Attacker creates Google account with victim's email
• Attacker signs in via Google
• Attacker gains access to victim's account

The Solution

Account Merge requires password verification:

• User proves they own the existing account
• Only then are accounts linked
• Prevents unauthorized access

How It Works

User signs in with Google
        ↓
Email matches existing account
        ↓
Show merge modal (not auto-link)
        ↓
User enters existing password
        ↓
    Password correct → Link accounts
        ↓
    Password wrong → Show error

Configuration

Enable Account Merge

1. Go to Settings > OneTap Login
2. Click Users tab
3. Enable Account merge with password verification
4. Save Changes

Settings

Setting	Description
Enable account merge	Toggle feature on/off
Merge modal title	Header text for modal
Merge modal message	Explanation text
Token expiration	Time limit for merge (default: 15 min)

User Experience

Merge Modal

When email matches, user sees:

┌────────────────────────────────────────┐
│       Link Your Accounts               │
│                                        │
│  An account with john@gmail.com        │
│  already exists.                       │
│                                        │
│  Enter your password to link your      │
│  Google account:                       │
│                                        │
│  Password: [________________]          │
│                                        │
│  [  Link Accounts  ]  [ Cancel ]       │
└────────────────────────────────────────┘

Success State

After successful merge:

• Accounts linked
• User logged in
• Success message displayed
• Future Google sign-ins work

Failure States

Scenario	User Message
Wrong password	"Incorrect password. Please try again."
Token expired	"Session expired. Please try again."
Too many attempts	"Too many attempts. Please wait."

Security Features

Password Verification

// Simplified verification logic
$user = get_user_by('email', $google_email);
$password_correct = wp_check_password($entered_password, $user->user_pass);

if ($password_correct) {
    // Link accounts
} else {
    // Show error
}

Time-Limited Token

Merge tokens expire after 15 minutes:

• Prevents leaving merge modal open indefinitely
• User must restart if expired
• Configurable duration

One-Time Use

Each merge token can only be used once:

• Prevents replay attacks
• Invalid after successful use
• Invalid after failed attempts exceed limit

Rate Limiting

Prevent brute force attempts:

• Max 5 attempts per token
• After 5 failures, token invalidated
• User must restart flow

CSRF Protection

Modal form includes:

• WordPress nonce
• Session validation
• Origin checking

Comparison: Auto-Link vs Account Merge

Aspect	Auto-Link (FREE)	Account Merge (PRO)
User friction	None	One password entry
Security	Email trust only	Password verification
Account takeover risk	Possible	Protected
Best for	Trusted environments	Public sites

Use Cases

E-commerce Store

User has:

• Existing account with orders
• Wants to use Google sign-in

Flow:

1. User clicks Google sign-in
2. Sees merge modal
3. Enters password
4. Accounts linked
5. Order history preserved

Membership Site

User has:

• Paid subscription
• Password they may have forgotten

Flow:

1. User tries Google sign-in
2. Sees merge modal
3. Clicks "Forgot password" link
4. Resets password
5. Returns and completes merge

Corporate Portal

User has:

• IT-created account
• Standard login credentials

Flow:

1. User switches to Google sign-in
2. Verifies with existing password
3. Can now use either method

"Forgot Password" Integration

The merge modal includes password reset:

Don't remember your password?
[Reset password →]

Clicking:

1. Closes merge modal
2. Redirects to password reset
3. User receives reset email
4. After reset, can retry merge

Hooks for Developers

Before Merge Attempt

add_filter('onetap_allow_account_merge', function($allow, $user, $google_data) {
    // Custom validation
    if ($user->has_cap('administrator')) {
        return false; // Don't allow admin merges
    }
    return $allow;
}, 10, 3);

After Successful Merge

add_action('onetap_accounts_merged', function($user_id, $google_data) {
    // Log the merge
    update_user_meta($user_id, '_merged_at', current_time('mysql'));

    // Notify user
    // Update CRM
    // etc.
}, 10, 2);

Customize Modal Content

add_filter('onetap_merge_modal_content', function($content, $email) {
    $content['title'] = 'Connect Your Accounts';
    $content['message'] = 'We found an account with ' . $email . '.';
    return $content;
}, 10, 2);

Troubleshooting

Modal Not Appearing

Causes:

1. Account merge disabled
2. No matching email exists
3. JavaScript error

Solutions:

1. Enable account merge setting
2. Verify user exists with that email
3. Check browser console

Password Always Rejected

Causes:

1. Caps lock on
2. Password recently changed
3. Account has no password (social only)

Solutions:

1. Check caps lock
2. Use password reset
3. Set password first

Token Expired Too Quickly

Causes:

1. Short token duration
2. Clock sync issues

Solutions:

1. Increase token expiration
2. Check server time

Modal Closes Unexpectedly

Causes:

1. Click outside modal
2. JavaScript error
3. Form submission error

Solutions:

1. Click carefully
2. Check console errors
3. Review network requests

Security Best Practices

For Site Owners

• Keep token expiration reasonable (15-30 min)
• Enable rate limiting
• Monitor failed merge attempts
• Regular security audits

For Users

• Use strong passwords
• Don't share merge links
• Complete merge promptly
• Report suspicious activity

What If User Can't Merge?

No Password Known

Options:

1. Use password reset
2. Contact support
3. Create new account

Account Locked

Admin should:

1. Unlock account
2. Reset password
3. Guide user through merge

Technical Issues

Support should:

1. Verify user identity manually
2. Link accounts via admin
3. Document for security

Admin Manual Linking

Admins can link accounts manually:

// In user profile or via custom admin action
update_user_meta($user_id, '_onetap_google_id', $google_id);

Use cautiously with proper verification.

Next Steps

• Account Linking - Automatic linking (FREE)
• User Settings - Registration options
• Security Overview - Security measures