Captcha Settings

Overview

The Captcha Settings module provides comprehensive configuration for protecting your forms from automated bot submissions and spam. You can choose between Google reCAPTCHA (v2 or v3) or a built-in math captcha, configure which forms require captcha verification, set up rate limiting to prevent brute force attacks, and test your reCAPTCHA credentials.

Captcha protection is essential for maintaining the integrity of your contact forms, login pages, registration forms, and password reset requests by ensuring that only legitimate human users can submit these forms.

Accessing Captcha Settings

Navigation path: Dashboard > Security > Captcha Settings

Required permission: manage_captcha_settings

Key Features

• Multiple Captcha Types: Choose between reCAPTCHA v2, reCAPTCHA v3, or built-in math captcha
• Form-Specific Protection: Enable captcha on specific forms (contact, login, register, password reset)
• Google reCAPTCHA Integration: Full support for both reCAPTCHA v2 and v3 with credential testing
• Rate Limiting: Prevent brute force attacks with configurable attempt limits
• Flexible Configuration: Adjust minimum scores, time windows, and fallback behavior
• Live Testing: Test reCAPTCHA credentials directly from the admin interface

Main Interface

The Captcha Settings page is organized into six main sections, each focusing on a specific aspect of captcha configuration. All settings are presented in a single form with clearly labeled sections.

Page Layout

• Header: Shows the page title, back button, and "Reset to Defaults" button
• General Settings: Enable/disable captcha and select the type
• Google reCAPTCHA Configuration: Configure API credentials (shown when reCAPTCHA is selected)
• Form Protection: Select which forms require captcha
• Rate Limiting: Configure attempt limits and time windows
• Advanced Options: Set fallback behavior for API failures
• Save Button: Located at the bottom to save all changes at once

Configuration Sections

General Settings

Control the overall captcha system and select the type of captcha to use.

Settings:

• Enable Captcha System (checkbox)

  • Type: Toggle
  • Description: Globally enable or disable captcha protection
  • Default: Enabled
  • Note: When disabled, no forms will show captcha regardless of form-specific settings

• Captcha Type (radio buttons)

  • Type: Single selection
  • Options:
    • Google reCAPTCHA v2: Checkbox challenge - "I'm not a robot"
    • Google reCAPTCHA v3: Invisible - score-based verification
    • Math Captcha: Built-in - simple arithmetic problems
  • Default: Math Captcha
  • Description: Choose the type of captcha verification to use

Google reCAPTCHA Configuration

Configure your Google reCAPTCHA API credentials. This section only appears when reCAPTCHA v2 or v3 is selected.

Settings:

• Site Key (text input)

  • Type: Text
  • Required: Yes (when using reCAPTCHA)
  • Format: Starts with "6Lc..."
  • Description: Your reCAPTCHA site key (public key)
  • Example: 6LcXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Secret Key (password input)

  • Type: Password (toggleable visibility)
  • Required: Yes (when using reCAPTCHA)
  • Format: Starts with "6Lc..."
  • Description: Your reCAPTCHA secret key (private key)
  • Security: Stored encrypted in the database
  • Note: Click the eye icon to show/hide the key

• Minimum Score (range slider)

  • Type: Number (0.0 - 1.0)
  • Required: Yes (for reCAPTCHA v3 only)
  • Default: 0.5
  • Description: Minimum score required to pass verification (v3 only)
  • Range: 0.0 (likely bot) to 1.0 (likely human)
  • Recommendation: 0.5 for balanced protection, 0.7 for stricter verification

• Test reCAPTCHA (button)

  • Type: Action button
  • Description: Test your reCAPTCHA credentials to verify they work
  • Action: Sends a test request to Google's reCAPTCHA API
  • Result: Shows success or error message with details

How to get reCAPTCHA keys:

1. Visit Google reCAPTCHA Admin Console
2. Sign in with your Google account
3. Click "+" to register a new site
4. Fill in the form:
   • Label: Your site name
   • reCAPTCHA type: Choose v2 or v3
   • Domains: Add your domain(s)
5. Accept the terms and submit
6. Copy the Site Key and Secret Key
7. Paste them into the Captcha Settings form

Form Protection

Select which forms should display captcha verification.

Settings:

• Contact Form (checkbox)

  • Type: Toggle
  • Description: Require captcha on the contact us form
  • Default: Enabled
  • Recommendation: Always enable to prevent spam

• Login Form (checkbox)

  • Type: Toggle
  • Description: Require captcha on the admin login form
  • Default: Disabled
  • Recommendation: Enable if experiencing brute force attacks

• Registration Form (checkbox)

  • Type: Toggle
  • Description: Require captcha on user registration
  • Default: Enabled
  • Recommendation: Enable to prevent bot registrations

• Password Reset Form (checkbox)

  • Type: Toggle
  • Description: Require captcha on password reset requests
  • Default: Disabled
  • Recommendation: Enable if experiencing abuse

Rate Limiting

Configure rate limiting to prevent brute force attacks and excessive form submissions.

Settings:

• Enable Rate Limiting (checkbox)

  • Type: Toggle
  • Description: Enable rate limiting for form submissions
  • Default: Enabled
  • Note: Works independently of captcha

• Max Attempts (number input)

  • Type: Number
  • Required: Yes (when rate limiting enabled)
  • Default: 5
  • Range: 1-100
  • Description: Maximum number of failed attempts allowed
  • Recommendation: 3-5 for login, 5-10 for contact forms

• Time Window (number input)

  • Type: Number (minutes)
  • Required: Yes (when rate limiting enabled)
  • Default: 15
  • Range: 1-1440 (24 hours)
  • Description: Time window for counting attempts
  • Example: 5 attempts in 15 minutes

• Lockout Duration (number input)

  • Type: Number (minutes)
  • Required: Yes (when rate limiting enabled)
  • Default: 30
  • Range: 1-1440 (24 hours)
  • Description: How long to block after exceeding max attempts
  • Note: User must wait this duration before trying again

Advanced Options

Configure fallback behavior and additional settings.

Settings:

• Fallback on API Failure (select dropdown)

  • Type: Dropdown
  • Options:
    • Allow: Allow form submission if reCAPTCHA API is unavailable
    • Block: Block form submission if reCAPTCHA API is unavailable
    • Use Math Captcha: Fall back to built-in math captcha
  • Default: Use Math Captcha
  • Description: What to do when reCAPTCHA API is unreachable
  • Recommendation: Use Math Captcha for best user experience

• Log Failed Attempts (checkbox)

  • Type: Toggle
  • Description: Log all failed captcha attempts to security events
  • Default: Enabled
  • Note: Helps identify attack patterns

• Show Error Messages (checkbox)

  • Type: Toggle
  • Description: Show detailed error messages to users
  • Default: Enabled
  • Note: Disable for production to avoid revealing system details

Common Tasks

Setting Up Google reCAPTCHA v2

1. Navigate to Security > Captcha Settings
2. In General Settings, select Google reCAPTCHA v2
3. In Google reCAPTCHA Configuration:
   • Enter your Site Key
   • Enter your Secret Key
4. Click Test reCAPTCHA to verify credentials
5. In Form Protection, enable captcha for desired forms
6. Click Save Changes

Setting Up Google reCAPTCHA v3

1. Navigate to Security > Captcha Settings
2. In General Settings, select Google reCAPTCHA v3
3. In Google reCAPTCHA Configuration:
   • Enter your Site Key
   • Enter your Secret Key
   • Set Minimum Score (0.5 recommended)
4. Click Test reCAPTCHA to verify credentials
5. In Form Protection, enable captcha for desired forms
6. Click Save Changes

Using Built-in Math Captcha

1. Navigate to Security > Captcha Settings
2. In General Settings, select Math Captcha
3. In Form Protection, enable captcha for desired forms
4. Configure Rate Limiting settings
5. Click Save Changes

Configuring Rate Limiting

1. Navigate to Security > Captcha Settings
2. In Rate Limiting:
   • Enable Rate Limiting
   • Set Max Attempts (e.g., 5)
   • Set Time Window (e.g., 15 minutes)
   • Set Lockout Duration (e.g., 30 minutes)
3. Click Save Changes

Testing reCAPTCHA Configuration

1. Navigate to Security > Captcha Settings
2. Ensure Site Key and Secret Key are entered
3. Click Test reCAPTCHA button
4. Wait for the test result:
   • Success: Green message "reCAPTCHA credentials are valid"
   • Error: Red message with error details
5. If error, verify:
   • Keys are correct and not swapped
   • Domain is registered in reCAPTCHA console
   • Server can reach Google's API

Resetting to Default Settings

1. Navigate to Security > Captcha Settings
2. Click Reset to Defaults button in the header
3. Confirm the action in the dialog
4. All settings will be restored to default values

Validation Rules

The system validates all settings before saving:

• Site Key: Required when using reCAPTCHA, must start with "6Lc"
• Secret Key: Required when using reCAPTCHA, must start with "6Lc"
• Minimum Score: Required for v3, must be between 0.0 and 1.0
• Max Attempts: Required when rate limiting enabled, must be 1-100
• Time Window: Required when rate limiting enabled, must be 1-1440
• Lockout Duration: Required when rate limiting enabled, must be 1-1440

Permissions

To access and manage captcha settings, users need:

• manage_captcha_settings: Full access to view and modify all captcha settings

Security Considerations

Best Practices

1. Use reCAPTCHA v3 for Better UX: Invisible verification provides better user experience
2. Enable on Critical Forms: Always protect contact, login, and registration forms
3. Keep Secret Key Secure: Never expose your secret key in client-side code
4. Monitor Failed Attempts: Review security events regularly for attack patterns
5. Set Appropriate Scores: Balance security and user experience (0.5 is a good start)
6. Configure Rate Limiting: Use rate limiting as an additional layer of protection
7. Test After Changes: Always test forms after changing captcha settings
8. Use Fallback: Configure fallback behavior for API failures

Common Security Issues

1. Swapped Keys: Site key and secret key are reversed
2. Domain Mismatch: Domain not registered in reCAPTCHA console
3. Exposed Secret Key: Secret key visible in client-side code
4. Too Lenient Score: Minimum score too low (< 0.3) allows bots
5. No Rate Limiting: Missing rate limiting allows brute force attacks
6. Disabled Logging: Can't track attack patterns without logs

Troubleshooting

reCAPTCHA Not Showing

Problem: Captcha doesn't appear on forms

Solutions:

1. Verify captcha is enabled in General Settings
2. Check that form protection is enabled for the specific form
3. Ensure Site Key is correct
4. Check browser console for JavaScript errors
5. Verify domain is registered in reCAPTCHA console
6. Clear browser cache and reload

"Invalid Site Key" Error

Problem: Error message about invalid site key

Solutions:

1. Verify you're using the correct site key (not secret key)
2. Check that the key starts with "6Lc"
3. Ensure domain matches reCAPTCHA console registration
4. Verify key is for the correct reCAPTCHA version (v2 or v3)
5. Try regenerating keys in reCAPTCHA console

"Failed to Verify" Error

Problem: Captcha verification fails even with correct input

Solutions:

1. Test reCAPTCHA credentials using the Test button
2. Verify secret key is correct
3. Check server can reach Google's API (firewall/proxy issues)
4. Ensure system time is synchronized (NTP)
5. Check for rate limiting by Google (too many requests)
6. Review server logs for detailed error messages

Rate Limiting Blocking Legitimate Users

Problem: Users getting locked out too frequently

Solutions:

1. Increase Max Attempts (e.g., from 3 to 5)
2. Increase Time Window (e.g., from 10 to 15 minutes)
3. Decrease Lockout Duration (e.g., from 60 to 30 minutes)
4. Review security events to identify false positives
5. Consider using reCAPTCHA v3 instead of strict rate limiting

Math Captcha Too Easy/Hard

Problem: Math captcha is too simple or too complex

Solutions:

1. Math captcha difficulty is fixed (simple addition/subtraction)
2. Consider switching to reCAPTCHA for better bot detection
3. Combine with rate limiting for additional protection
4. Review code to adjust difficulty if needed (requires development)

API Failure Fallback Not Working

Problem: Forms blocked when reCAPTCHA API is down

Solutions:

1. Check Fallback on API Failure setting
2. Set to "Use Math Captcha" or "Allow" for better availability
3. Monitor API status at Google Status Dashboard
4. Consider implementing retry logic
5. Review server logs for connection issues

Test reCAPTCHA Button Not Working

Problem: Test button doesn't respond or shows error

Solutions:

1. Ensure both Site Key and Secret Key are entered
2. Check that keys are not swapped
3. Verify server has internet access
4. Check firewall allows connections to google.com
5. Review browser console for JavaScript errors
6. Try testing from a different browser

Tips and Best Practices

Choosing the Right Captcha Type

• reCAPTCHA v3: Best for user experience, invisible verification
• reCAPTCHA v2: Good balance of security and usability
• Math Captcha: Simple, no external dependencies, but less secure

Optimizing reCAPTCHA v3 Score

• 0.9-1.0: Very strict, may block legitimate users
• 0.7-0.9: Strict, good for high-security forms
• 0.5-0.7: Balanced, recommended for most use cases
• 0.3-0.5: Lenient, may allow some bots
• 0.0-0.3: Very lenient, not recommended

Form-Specific Recommendations

• Contact Form: Always enable, use v3 with 0.5 score
• Login Form: Enable if under attack, use v2 or rate limiting
• Registration: Always enable, use v3 with 0.5 score
• Password Reset: Enable if experiencing abuse, use v2

Rate Limiting Guidelines

• Login Forms: 3-5 attempts in 15 minutes, 30-60 minute lockout
• Contact Forms: 5-10 attempts in 15 minutes, 15-30 minute lockout
• Registration: 3-5 attempts in 30 minutes, 60 minute lockout
• Password Reset: 3 attempts in 60 minutes, 60 minute lockout

Monitoring and Maintenance

1. Review security events weekly for failed captcha attempts
2. Monitor reCAPTCHA usage in Google Admin Console
3. Adjust minimum score based on false positive/negative rates
4. Test forms regularly to ensure captcha is working
5. Keep reCAPTCHA keys secure and rotate periodically
6. Update fallback settings based on API reliability

Related Documentation

• Security Settings - General security configuration
• Security Events - Monitoring security events
• Audit Logs - Tracking system changes
• IP Whitelist - IP-based access control
• Contact Messages - Managing contact form submissions

Support

If you encounter issues with captcha settings:

1. Check this documentation for troubleshooting steps
2. Review security events for error details
3. Test reCAPTCHA credentials using the Test button
4. Check server logs for detailed error messages
5. Contact support with:
   • Captcha type being used
   • Error messages received
   • Steps to reproduce the issue
   • Browser and device information