reCAPTCHA
Integrates Google reCAPTCHA service with Drupal's CAPTCHA module to protect forms from spam and abuse.
recaptcha
Install
composer require 'drupal/recaptcha:8.x-3.4'
composer require 'drupal/recaptcha:8.x-3.2'
Overview
The reCAPTCHA module provides integration with Google's reCAPTCHA web service, offering advanced bot protection for Drupal forms. It uses the Google No CAPTCHA reCAPTCHA API (reCAPTCHA v2), which employs an advanced risk analysis engine and adaptive CAPTCHAs to distinguish between human users and automated software.
This module extends the CAPTCHA module by providing reCAPTCHA as a CAPTCHA type option. Once configured with site and secret keys from Google, administrators can assign reCAPTCHA protection to any form managed by the CAPTCHA module, including user login, registration, password reset, contact forms, and more.
The module supports multiple widget themes (light and dark), CAPTCHA types (image and audio for accessibility), various sizes (normal and compact), and includes a fallback mechanism for browsers with JavaScript disabled. For regions where Google services are restricted, the module offers a global mode that uses alternative reCAPTCHA endpoints (recaptcha.net instead of google.com).
Features
- Google reCAPTCHA v2 (No CAPTCHA reCAPTCHA) integration with advanced risk analysis
- Configurable widget themes (light/dark) for visual customization
- Support for image and audio CAPTCHA types for accessibility compliance
- Normal and compact widget sizes to fit different form layouts
- JavaScript-disabled browser fallback support via noscript element
- Global mode for regions where google.com is inaccessible (uses recaptcha.net)
- Hostname verification option for enhanced security when domain validation is disabled in Google settings
- Automatic fallback to Math CAPTCHA when reCAPTCHA keys are not configured
- Multi-language support with automatic language detection
- Full compatibility with Drupal's caching system - cacheable CAPTCHA forms
- Migration support from Drupal 6 and Drupal 7 installations
- Seamless integration with CAPTCHA module's form protection system
Use Cases
Protecting User Login Forms from Brute Force Attacks
Enable reCAPTCHA on the user login form to prevent automated brute force password attacks. Navigate to CAPTCHA settings, add a CAPTCHA point for 'user_login_form', and select 'reCAPTCHA' as the challenge type. This adds Google's risk analysis to detect and block automated login attempts while allowing legitimate users to log in with minimal friction.
Preventing Spam on Contact Forms
Apply reCAPTCHA protection to contact forms to block spam submissions from bots. Configure a CAPTCHA point for your contact form and assign reCAPTCHA. The invisible risk analysis will challenge suspicious submissions while most legitimate users pass through without seeing a CAPTCHA challenge.
Securing User Registration
Protect the user registration form from automated account creation by enabling reCAPTCHA. This prevents bots from creating fake accounts that could be used for spam, abuse, or credential stuffing attacks.
Accessibility-Compliant CAPTCHA Implementation
Use the audio CAPTCHA type option to provide an accessible alternative for visually impaired users. Configure the widget settings to enable audio challenges, ensuring compliance with accessibility requirements while maintaining spam protection.
Deploying in China or Restricted Regions
For sites serving users in regions where google.com is blocked (such as China), enable the 'Use reCAPTCHA globally' option. This switches all reCAPTCHA requests to use recaptcha.net domain, which is accessible in these regions while providing the same protection.
Matching Site Design with Theme Selection
Choose between light and dark reCAPTCHA themes to match your site's visual design. For dark-themed sites, select the 'Dark' theme option to ensure the CAPTCHA widget blends seamlessly with your design aesthetic.
Tips
- Always test reCAPTCHA configuration in an incognito/private browser window to avoid cached states
- Use the 'Compact' size option for forms in sidebars or narrow layouts where space is limited
- Enable noscript fallback only if you need to support users with JavaScript disabled - it adds extra markup
- The dark theme works well with dark-mode enabled sites but may appear jarring on light backgrounds
- Register separate reCAPTCHA keys for development and production environments to avoid score issues
- Monitor your Google reCAPTCHA admin console for traffic patterns and adjust settings if seeing high failure rates
- Consider using reCAPTCHA v3 for invisible protection if available through other modules
Technical Details
Admin Pages 1
/admin/config/people/captcha/recaptcha
Configure Google reCAPTCHA settings for your Drupal site. This page allows administrators to enter API credentials and customize the appearance and behavior of reCAPTCHA widgets displayed on protected forms.
Permissions 1
Hooks 4
hook_captcha
Implements the CAPTCHA module's hook to register reCAPTCHA as a CAPTCHA type and generate the reCAPTCHA form element. Returns the list of available CAPTCHA types on 'list' operation and builds the complete reCAPTCHA widget with validation callback on 'generate' operation.
hook_theme
Registers the recaptcha_widget_noscript theme hook for rendering the noscript fallback content when JavaScript is disabled.
hook_library_info_build
Dynamically builds library definitions for each enabled language. Creates external JavaScript libraries pointing to Google's reCAPTCHA API with language-specific URLs. Uses google.com or recaptcha.net domain based on the 'use_globally' configuration setting.
hook_help
Provides help page content for the reCAPTCHA module explaining its purpose, features, and step-by-step configuration instructions.
Troubleshooting 7
Verify that both Site key and Secret key are correctly configured in the reCAPTCHA settings. Check browser console for JavaScript errors. Ensure the CAPTCHA module has reCAPTCHA assigned to the specific form. Clear all caches after configuration changes.
This occurs when Site key or Secret key is empty or invalid. Navigate to the reCAPTCHA settings and enter valid API credentials obtained from Google's reCAPTCHA admin console.
The domain making requests doesn't match domains registered in your Google reCAPTCHA settings. Either add the domain to your Google reCAPTCHA configuration, or enable 'Local domain name validation' in the module settings if 'Verify the origin of reCAPTCHA solutions' is disabled in Google settings.
Ensure your server can make outbound HTTPS connections to google.com (or recaptcha.net if using global mode). The server needs to communicate with Google's verification endpoint. Check firewall rules and proxy configuration.
The server's CA certificate bundle may be outdated and unable to verify Google's SSL certificate. Update the server's CA certificates or configure PHP/cURL to use an updated certificate bundle.
Enable the 'Use reCAPTCHA globally' checkbox in the reCAPTCHA settings. This switches the API endpoint from www.google.com to www.recaptcha.net, which is accessible in restricted regions.
The module includes JavaScript that handles reCAPTCHA re-rendering for AJAX forms. Ensure the recaptcha/recaptcha library is properly attached. The behavior resets the CAPTCHA widget on already-processed elements.
Security Notes 6
- Never expose your Secret key in client-side code or public repositories - it should only be used server-side
- Enable 'Local domain name validation' when 'Verify the origin of reCAPTCHA solutions' is disabled in Google settings to prevent key theft and use on unauthorized domains
- reCAPTCHA keys are domain-specific - ensure your production keys are registered for all domains including www and non-www variants
- The module validates responses server-side using Google's API - client-side validation alone is insufficient
- Consider enabling verbose logging during initial setup to monitor for verification failures and their causes
- The fallback to Math CAPTCHA when keys are missing ensures forms remain protected even if reCAPTCHA configuration is incomplete