CAPTCHA
Provides CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) functionality to protect web forms from automated spam submissions.
captcha
Install
composer require 'drupal/captcha:^2.0'
Overview
The CAPTCHA module is a comprehensive spam protection system that adds challenge-response tests to Drupal forms. It provides an API that allows other modules to implement various CAPTCHA types, and comes with a built-in Math CAPTCHA challenge.
CAPTCHA challenges can be added to virtually any Drupal form through the concept of "CAPTCHA Points" - configuration entities that associate forms with specific challenge types. The module includes preconfigured CAPTCHA Points for common forms like user login, registration, and password reset.
Key features include IP whitelisting to bypass challenges for trusted addresses, configurable persistence settings to skip CAPTCHAs after successful responses, administration mode for easy setup, and statistics tracking for blocked submissions. The module integrates with Drupal's page caching system, automatically disabling caching for pages with CAPTCHA challenges.
Developers can create custom CAPTCHA types by implementing hook_captcha(), and can customize CAPTCHA placement within forms using hook_captcha_placement_map().
Features
- Math CAPTCHA challenge - presents simple arithmetic problems (e.g., 5 + 3 = ?) that users must solve
- CAPTCHA Points system - config entities that map form IDs to challenge types with enable/disable status
- Global CAPTCHA mode - optionally add challenges to all forms site-wide
- IP address whitelisting - skip CAPTCHAs for trusted IP addresses or IP ranges
- Persistence settings - configure whether to show CAPTCHAs always or skip after successful response (per form, per form type, or site-wide)
- Administration mode - displays CAPTCHA management links on forms for administrators
- Customizable messages - configure CAPTCHA title, description, and error messages
- Case-sensitive or case-insensitive validation options
- Statistics tracking - count blocked form submissions in status report
- Wrong response logging - optionally log incorrect CAPTCHA responses
- CAPTCHA session management with automatic cleanup via cron
- Integration with Drupal's page caching (disables cache for pages with CAPTCHAs)
- Form element (#type => 'captcha') for programmatic CAPTCHA insertion
- Migration support from Drupal 7
- Developer API with hooks for custom CAPTCHA implementations
Use Cases
Protecting User Registration from Spam Bots
Enable the CAPTCHA Point for user_register_form to require visitors to solve a Math or Image CAPTCHA before creating an account. This effectively blocks automated account creation by spam bots while maintaining a reasonable user experience for legitimate visitors.
Securing Contact Forms
Add CAPTCHA to contact forms to prevent automated spam messages. The module includes a pre-configured CAPTCHA Point for the personal contact form, and you can add additional points for site-wide or custom contact forms.
Protecting Comment Forms
Create CAPTCHA Points for comment forms (comment_*_form) to prevent spam comments. Consider using persistence settings to skip CAPTCHA after one successful response to improve user experience for legitimate commenters.
Site-wide Protection with IP Whitelisting
Enable 'Add CAPTCHA challenges on all forms' for maximum protection, then add your office IP addresses or trusted partner IPs to the whitelist so internal users don't see CAPTCHAs.
Custom Form Protection
Create custom CAPTCHA Points for any form by specifying its form_id. You can find form IDs by enabling administration mode, which displays CAPTCHA management links on all forms showing their form_id.
Implementing Custom CAPTCHA Types
Developers can create custom CAPTCHA challenges by implementing hook_captcha(). Return available types in the 'list' operation and generate challenges in the 'generate' operation. This allows integration with third-party CAPTCHA services or custom challenge types.
Tips
- Grant 'Skip CAPTCHA' permission to administrators and trusted roles to avoid them seeing challenges
- Use administration mode during site building to easily identify form IDs and manage CAPTCHA Points
- For comment forms, set 'Display on separate page' in content type settings for better caching efficiency
- In development environments, add $settings['disable_captcha'] = TRUE; to settings.php to bypass all CAPTCHAs
- Consider persistence settings carefully - 'Skip once successful' improves UX but reduces security
- Use IP whitelisting for known good IPs (office, CI servers) to bypass CAPTCHA
- Monitor the status report for blocked submission statistics if stats are enabled
- Clear the CAPTCHA placement cache after significant form structure changes
Technical Details
Admin Pages 4
/admin/config/people/captcha
Main configuration page for CAPTCHA module settings including default challenge type, global options, persistence behavior, and message customization.
/admin/config/people/captcha/captcha-points
Manage CAPTCHA Points - the associations between forms and CAPTCHA challenge types. Lists all configured CAPTCHA Points with their form IDs, challenge types, and enabled status.
/admin/config/people/captcha/captcha-points/add
Create a new CAPTCHA Point to protect a specific form with a challenge.
/admin/config/people/captcha/examples
Preview page showing examples of all available CAPTCHA challenge types with their current settings. Useful for testing and comparing different CAPTCHA implementations.
Permissions 2
Hooks 3
hook_captcha
Main hook for implementing CAPTCHA challenge types. Modules implement this to provide their own challenges.
hook_captcha_alter
Allows modules to alter a CAPTCHA after it has been generated.
hook_captcha_placement_map
Define custom placement positions for CAPTCHA elements in specific forms.
Troubleshooting 4
This typically occurs with aggressive caching. The CAPTCHA module disables page caching for pages with CAPTCHAs, but other caching mechanisms (Varnish, CDN) may cause issues. Configure your caching layer to bypass cache for forms with CAPTCHAs, or consider using a cacheable CAPTCHA type like reCAPTCHA.
1. Check that the user doesn't have 'Skip CAPTCHA' permission. 2. Verify the CAPTCHA Point exists and is enabled. 3. Clear the CAPTCHA placement cache. 4. Check if the IP is whitelisted.
Clear the CAPTCHA placement cache from the settings page. If the problem persists, implement hook_captcha_placement_map() to specify the exact placement for that form.
CAPTCHA disables page caching for forms with challenges. If you need caching, place CAPTCHA-protected forms on separate pages, use AJAX form loading, or use a cacheable CAPTCHA implementation like reCAPTCHA.
Security Notes 6
- CAPTCHA provides protection against automated attacks but determined attackers may use CAPTCHA-solving services
- The Math CAPTCHA is less secure than image-based CAPTCHAs but more accessible
- Always combine CAPTCHA with other security measures like honeypots and rate limiting
- CAPTCHA session IDs are validated with tokens to prevent reuse attacks
- Whitelisted IPs bypass all CAPTCHA validation - use this feature carefully
- The module logs CAPTCHA session reuse attacks for security monitoring