Integrating Google reCAPTCHA with Drupal forms
Public forms are an obvious target for automated spam. A Drupal contact, quote, registration, or event form can attract bot submissions that consume staff time, pollute analytics, and expose endpoints to abuse. The useful goal is not to make every visitor prove their humanity; it is to stop low-quality traffic while keeping legitimate enquiries easy to send.
Drupal provides a flexible form and challenge framework, while the contributed reCAPTCHA module connects it to Google's bot-detection service. Together, they let editors attach a CAPTCHA challenge to selected forms without replacing the site's content model or rebuilding every form in custom JavaScript.
The setup below suits Drupal 10 and 11 sites managed through Composer and Drush, although menu labels can vary by release. It also considers Australian privacy, accessibility, and mobile use, rather than treating spam prevention as a purely technical checkbox.
Choosing the right reCAPTCHA mode
Google offers several protection modes, and the right choice depends on the form's traffic, risk, and audience. A Drupal administrator should select a mode before adding keys because each option uses a different challenge and validation flow.
| Mode | Visitor experience | Practical use | Main trade-off |
|---|---|---|---|
| reCAPTCHA v2 checkbox | A visible “I'm not a robot” box | Low-volume contact and registration forms | Adds one interaction but is familiar and easy to explain |
| reCAPTCHA v2 invisible | Usually no checkbox, although risk analysis may show a challenge | Public forms where a visible prompt is likely to cause abandonment | The Google badge remains unless its removal is approved |
| reCAPTCHA v3 | No puzzle; the server receives a score from 0.0 to 1.0 | High-volume forms with enough traffic to tune a threshold | Requires monitoring because genuine users can receive a low score |
For most Australian sites starting with spam protection, the v2 checkbox is the least mysterious option. It gives users in Sydney, Melbourne, Brisbane, and regional areas a clear task and works with touch screens on intermittent mobile connections. V3 can suit a busy Australian small-business quote service, but it should be introduced only when someone can review score data and adjust the threshold.
Installing the Drupal modules
Install the CAPTCHA framework and its Google adapter. The CAPTCHA module handles challenge rendering and form validation; the reCAPTCHA module supplies the Google-specific challenge type. Check each project's Drupal compatibility before upgrading a production website, since contributed modules can lag behind a new core release.
For a Composer-managed site, run the following from the site's Composer root, then enable both modules with Drush. If Drush is not installed, the modules can also be enabled from Extend in the Drupal admin interface.
composer require drupal/captcha drupal/recaptcha
drush pm:enable captcha recaptcha -y
After enabling, open Configuration > People > CAPTCHA, usually at /admin/config/people/captcha. Add a challenge type and choose reCAPTCHA. Keep one carefully named configuration for production rather than copying it across sites; the secret key must not be shared in screenshots, support tickets, or public configuration exports.
Registering and configuring the keys
Create the keys in the Google reCAPTCHA admin console. Choose the reCAPTCHA version planned for the Drupal challenge, register the production hostname, and copy the generated site key and secret key. Domain matching is exact: a key registered for example.com.au may not cover www.example.com.au unless both are accepted, and every staging hostname needs its own permission.
Paste the public site key and confidential secret into the reCAPTCHA challenge settings in Drupal. Select v2 checkbox, v2 invisible, or v3 as appropriate. V3 also needs a rejection threshold, often starting near 0.5, but the correct value depends on observed traffic rather than a universal rule.
Create separate credentials for local development, staging, and production. The site key is embedded in page markup and is not a password; the secret is sent from the Drupal server to Google and must remain server-side. If configuration is exported to Git or another repository, exclude or override the secret with your deployment secret store.
Applying protection to Drupal forms
Start with a core contact form. Go to Structure > Contact forms, edit the relevant form, and look for CAPTCHA protection or challenge settings in its form settings. Choose the configured reCAPTCHA challenge, save, clear caches if required, and confirm that the widget appears before the submit button.
For a Webform, open the form in the Webform interface, locate its CAPTCHA or protection settings, and select reCAPTCHA. Apply protection to forms that attract valuable enquiries or repeated abuse, such as account creation, support requests, event bookings, and quote requests. A quiet internal filter may not need the same friction as a public purchase or contact form.
Custom entity forms and other Form API forms can receive the CAPTCHA element through a form alter. The typical structure is shown below; the challenge plugin identifier should match the installed reCAPTCHA module release. The module must still validate the Google response on the server.
$form['captcha'] = [
'#type' => 'captcha',
'#captcha_type' => 'recaptcha',
];
For AJAX or multi-step forms, rebuild the widget whenever the form changes because each response token is short-lived and can be used only once.
Testing and troubleshooting the integration
Test the protected form as an editor would use it. Submit it from Chrome and Safari on a phone and desktop, then submit again with an expired, reused, or invalid response. Automated tests should use Google's official test credentials rather than production keys, so real submissions do not pollute analytics or cause a domain block.
If the widget is missing, check HTTPS, JavaScript errors, browser extensions, and Content Security Policy directives for https://www.google.com/recaptcha/ and https://www.gstatic.com/recaptcha/. An “invalid key” message usually means the site key and secret belong to different reCAPTCHA versions, the wrong environment was loaded, or the hostname does not match. For v3, investigate genuine low scores before lowering the threshold, as VPNs, shared addresses, and mobile networks can alter the result.
Check server logs without recording access tokens, secret keys, or the full form body. A log entry should be enough to show whether verification succeeded, failed, timed out, or returned a missing response. Re-test after a Drupal, CAPTCHA, reCAPTCHA, PHP, or JavaScript update, and monitor rejected submissions for sudden changes in volume.
Privacy, accessibility, and launch recommendations
reCAPTCHA sends request data to Google, which can include an IP address, cookies, and browser signals, and Drupal also sends the visitor's response to Google's verification service. Explain this third-party processing in the site's privacy policy, collect only the personal information the form genuinely needs, and assess cookie handling before enabling the service across an Australian website.
Where the Privacy Act 1988 applies, consider the Australian Privacy Principles, including purpose, disclosure, security, and accountability for overseas processing. Google may process information outside Australia, so document the provider and transfer arrangements rather than assuming the CAPTCHA makes a form compliant. The Spam Act 2003 is separate: a contact form does not create marketing consent, and commercial email may still require consent, sender identification, and a working unsubscribe process.
Accessibility is equally important. The Australian Government Digital Service Standard references WCAG 2.1 AA, and private sites should aim for the same usability level. Keep visible labels, keyboard focus, error messages, and an accessible alternative such as the v2 audio challenge. V3 is less visibly disruptive, but its score-based rejection can be harder for a person to understand.
Use these launch controls for a durable Drupal form-protection setup:
- Begin with the v2 checkbox on a low-volume public form, measure completion and spam reduction, and expand protection only where evidence supports it.
- Use v3 for a busy form only after assigning an owner to review score distributions and false positives.
- Keep production, staging, and local keys separate, and inject the secret through the deployment environment rather than committing it.
- Offer a genuine phone or email route for visitors who cannot complete the challenge, especially for high-value local enquiries.
- Re-test keyboard, screen-reader, mobile, and privacy behaviour after updates, and keep a short record of key ownership and rotation dates.
A successful integration rejects automated submissions without creating an unexplained barrier for customers. Keep the challenge configuration, monitoring responsibility, privacy notice, and testing schedule together so the protection remains effective as the Drupal site changes.