Drupal Canvas Forms verifies that submissions originate from a human through a CAPTCHA challenge on the forms. CAPTCHA provides a provider-agnostic, site-wide layer. An administrator configures one provider and one enforcement mode, and the setting applies to every Drupal Canvas form. The server verifies the CAPTCHA response of each submission before it accepts the data. CAPTCHA runs in addition to the built-in spam controls, and it runs after them because the CAPTCHA verification requires a network call to the provider.

Prerequisites

• Ensure that an administrator account has the Administer CAPTCHA permission. For more information, visit Managing permissions

Automated anti-spam protections

Drupal Canvas Forms enforces the following protections for unauthenticated endpoints:

Supported Providers

CAPTCHA supports the following providers:

Enforcement modes

CAPTCHA features two modes to verify form setups before the system blocks submissions:

• Monitor: In this report-only mode, Drupal Canvas Forms verifies each submission and logs the result but blocks nothing. Administrators use this mode to confirm that every form includes the CAPTCHA widget and emits valid tokens.
• Enforce: Drupal Canvas Forms rejects any submission that fails verification, which includes submissions from a form that lacks the CAPTCHA widget. In the generated form component, a rejected submission displays a failure message and asks the visitor to try again.

CAPTCHA never locks out real users because of a configuration problem or a provider problem. If an administrator disables CAPTCHA, misconfigures CAPTCHA, or the provider becomes unreachable, Drupal Canvas Forms does not block submissions based on the CAPTCHA signal. The honeypot, rate limit, and challenge token controls continue to apply. Only a definitive verification failure, or an absent token in the Enforce mode, rejects a submission.

Configure CAPTCHA

To configure CAPTCHA:

1. Sign in to the provider and create a site
2. Copy the public site key and the private secret key.

3. Access your site.

4. In the Source CMS administration menu, click Configuration.

5. Click System and select CAPTCHA.

6. Toggle Enable CAPTCHA protection.

7. Choose Monitor for the Mode to start. 

   Note

   Switch to Enforce only after the confirmation that the forms function correctly. For more information refer to Test and enforce CAPTCHA.

8. Select the configured provider for the Provider setting.
9. Enter the key in the Site key field. This value is public and appears on the page.
10. Enter the key in the Secret key field.

Drupal Canvas Forms stores the secret key securely on the server and never displays it again. To replace the secret key, enter a new value and save the configuration. To remove the secret key, select Remove the stored secret. An administrator cannot remove the secret key while CAPTCHA remains enabled. Enter a replacement key first or disable CAPTCHA.

Add the widget to a form

While CAPTCHA remains enabled, the starter code generated on the Connect view includes the CAPTCHA widget. Forms generated or regenerated work with CAPTCHA automatically.

To add the widget to a hand-authored form component, add two lines of code:

1. Add the import at the top of the component with the other imports:

   copy

   import { CanvasFormCaptcha } from 'acquia/captcha';

2. Add the widget inside the form before the submit button:

   copy

   <CanvasFormCaptcha />

The widget locates its own enclosing form and requires no properties. The CAPTCHA settings page displays these two snippets for easy duplication.

Test and enforce Captcha

Turn CAPTCHA on in the Monitor mode first. In this mode, Canvas Forms logs a message for any submission that the system would otherwise reject, which includes submissions to forms that lack the widget. This helps administrators find and fix errors without turning away real visitors. After the logs confirm that all forms submit valid CAPTCHA tokens, change the Mode to Enforce and Save.