recaptcha-and-bot-prevention

# reCAPTCHA and Bot Prevention

Use this skill when adding bot protection to any Salesforce public-facing surface: Web-to-Case, Web-to-Lead, Experience Cloud custom forms, or Headless Identity registration/login flows. It covers the built-in reCAPTCHA toggle for standard web forms, the custom LWC integration pattern for Experience Cloud, and the reCAPTCHA v3 requirement for Headless Identity APIs.

---

## Before Starting

Gather this context before working on anything in this domain:

- Identify which public-facing surfaces exist in the org: standard Web-to-Case/Lead HTML forms, Experience Cloud site pages with custom forms, or Headless Identity endpoints. Each has a different integration path.
- Confirm whether the org already has a Google reCAPTCHA project. You need a site key (client-side) and a secret key (server-side verification) from the Google reCAPTCHA Admin Console. Different surfaces may require different reCAPTCHA versions.
- Understand the spam volume and type. Automated bots submitting hundreds of cases per hour require reCAPTCHA. Sophisticated human-driven spam farms may need additional signals beyond CAPTCHA alone (e.g., honeypot fields, rate limiting, email domain validation).

---

## Core Concepts

### Mode 1: Built-In reCAPTCHA for Web-to-Case and Web-to-Lead

Salesforce provides a native reCAPTCHA v2 checkbox toggle for Web-to-Case and Web-to-Lead HTML generators. When enabled in Setup, the generated HTML snippet includes the reCAPTCHA widget and the verification is handled entirely by Salesforce on form submission. No custom Apex is required. This is the simplest integration path but only works for the standard HTML forms generated by Salesforce, not for custom-built forms or LWC components.

To enable: Setup > Web-to-Case (or Web-to-Lead) > check "Require reCAPTCHA Verification" > regenerate the HTML snippet and deploy it to your external site.

### Mode 2: Custom LWC reCAPTCHA for Experience Cloud

Experience Cloud sites with custom Lightning Web Component forms do not get the built-in reCAPTCHA toggle. You must integrate Google reCAPTCHA manually by: (1) loading the reCAPTCHA JavaScript library via a static resource or the Google CDN (requires CSP Trusted Site configuration), (2) rendering the widget or invoking the reCAPTCHA v3 execute call in the LWC, and (3) sending the token to an Apex controller that calls the Google verification endpoint server-side. The Apex callout to `https://www.google.com/recaptcha/api/siteverify` must use a Named Credential or Remote Site Setting.

### Mode 3: Headless Identity reCAPTCHA v3

Salesforce Headless Identity APIs (passwordless registration, login, and authorization) require reCAPTCHA v3 when the Headless Identity feature is enabled. This is configured in Setup > Identity > Headless Identity Settings. You provide your Google reCAPTCHA v3 site key and secret key. Salesforce enforces token verification on every Headless Identity API call. A minimum score threshold (default 0.5) determines whether the request is treated as human. reCAPTCHA v2 is not supported for Headless Identity.

---

## Common Patterns

### Pattern: Built-In Toggle for Standard Web Forms

**When to use:** The org uses only the standard Salesforce-generated Web-to-Case or Web-to-Lead HTML forms hosted on an external website.

**How it works:**
1. Navigate to Setup > Web-to-Case (or Web-to-Lead).
2. Enable "Require reCAPTCHA Verification."
3. Re-generate the HTML form snippet.
4. Replace the old HTML on your external site with the new snippet.
5. Test submission with reCAPTCHA challenge from a non-cached browser.

**Why not the alternative:** Custom implementations with the Google reCAPTCHA JavaScript API add complexity with no benefit when Salesforce already handles the full verification lifecycle for standard forms.

### Pattern: Custom Apex Verification for Experience Cloud or Custom UIs

**When to use:** The form is a custom LWC on an Experience Cloud site, a custom Aura component, or any non-standard form that cannot use the built-in toggle.

**How it works:**
1. Register a reCAPTCHA site in the Google Admin Console. Choose v2 invisible or v3 depending on UX requirements.
2. Add the Google reCAPTCHA domain to CSP Trusted Sites (Setup > CSP Trusted Sites) and create a Remote Site Setting for `https://www.google.com`.
3. In the LWC, load the reCAPTCHA script and execute it to obtain a token on form submission.
4. Pass the token to an `@AuraEnabled` Apex method.
5. The Apex method makes an HTTP POST to `https://www.google.com/recaptcha/api/siteverify` with the secret key and token.
6. Parse the JSON response. For v3, check that the `score` meets your threshold (0.5+ is typical). For v2, check `success: true`.
7. Only create the record (Case, Lead, custom object) if verification passes.

### Pattern: Layered Bot Defense

**When to use:** High-value public surfaces facing sophisticated attack patterns where reCAPTCHA alone is insufficient.

**How it works:**
1. Enable reCAPTCHA as the first line of defense.
2. Add a honeypot hidden field to catch naive bots that fill every input.
3. Implement server-side rate limiting per IP or session in Apex using Platform Cache or a custom object counter.
4. Validate email domains against a denylist of disposable email providers.
5. Use Transaction Security policies to flag bulk record creation from a single source.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Standard Web-to-Case/Lead HTML form | Enable the built-in reCAPTCHA toggle | Zero code, maintained by Salesforce, handles full verification |
| Experience Cloud custom LWC form | Custom reCAPTCHA v2 invisible or v3 via Apex verification | No built-in option exists; LWC must load the script and verify server-side |
| Headless Identity registration/login | Configure reCAPTCHA v3 in Headless Identity Settings | Required by Salesforce; v2 is not supported for Headless Identity |
| High-volume spam despite reCAPTCHA | Layer honeypot + rate limiting + email validation | Sophisticated bots can solve reCAPTCHA; defense in depth is required |
| Internal-only forms behind authentication | Skip reCAPTCHA entirely | Authenticated users are already identity-verified; CAPTCHA adds friction with no security benefit |

---

## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. **Inventory public surfaces** -- list every unauthenticated entry point in the org: Web-to-Case, Web-to-Lead, Experience Cloud guest-accessible pages, Headless Identity endpoints, and any public Apex REST services.
2. **Choose the reCAPTCHA version per surface** -- use the Decision Guidance table above. Standard web forms get the built-in toggle, Experience Cloud custom forms get v2 invisible or v3 with Apex verification, Headless Identity mandates v3.
3. **Register reCAPTCHA keys** -- create a project in the Google reCAPTCHA Admin Console. Generate separate site key / secret key pairs for each reCAPTCHA version needed. Store secrets securely using Named Credentials or Custom Metadata (never hardcode in Apex).
4. **Implement per surface** -- follow the appropriate pattern from Common Patterns above. For custom implementations, configure CSP Trusted Sites and Remote Site Settings before writing any code.
5. **Test with bot simulation** -- verify that submissions without a valid token are rejected. For v3, test with a low score threshold to confirm score-based rejection works. Test that legitimate users can submit without friction.
6. **Add layered defenses where needed** -- for high-value surfaces, add honeypot fields, rate limiting, and email validation as described in the Layered Bot Defense pattern.
7. **Monitor and tune** -- review spam volume after deployment. If reCAPTCHA v3 scores are too permissive (many bots scoring above threshold), lower the threshold or switch to v2 invisible for that surface.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] Every unauthenticated public-facing surface has reCAPTCHA or an equivalent bot-mitigation control
- [ ] Google reCAPTCHA secret keys are stored in Named Credentials or Custom Metadata, not hardcoded in Apex
- [ ] CSP Trusted Sites include `https://www.google.com` and `https://www.gstatic.com` for custom implementations
- [ ] Remote Site Setting exists for `https://www.google.com` for server-side Apex verification callouts
- [ ] reCAPTCHA v3 score threshold is configured and tested (not left at default without validation)
- [ ] Headless Identity Settings specify reCAPTCHA v3 (not v2) if Headless Identity is in use
- [ ] Web-to-Case/Lead HTML snippets have been regenerated after enabling the reCAPTCHA toggle
- [ ] Form submissions without a valid token are rejected with a user-friendly error

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Regenerate HTML after enabling reCAPTCHA toggle** -- enabling "Require reCAPTCHA Verification" in Web-to-Case/Lead does not retroactively add the widget to already-deployed HTML forms. You must regenerate the snippet and redeploy it. Old forms without the widget will have all submissions silently rejected.
2. **CSP blocks reCAPTCHA script loading in Experience Cloud** -- Experience Cloud sites enforce Content Security Policy headers. If you do not add `https://www.google.com` and `https://www.gstatic.com` to CSP Trusted Sites, the reCAPTCHA JavaScript will fail to load with no visible error to the user, just a broken or absent widget.
3. **Headless Identity rejects v2 tokens** -- if you register a reCAPTCHA v2 key and configure it in Headless Identity Settings, API calls will fail with a generic error. The documentation states v3 is required, but the error message does not specify the version mismatch.
4. **reCAPTCHA tokens expire in 2 minutes** -- a token generated by the client-side reCAPTCHA widget is valid for 120 seconds. If your form has a long completion time or the Apex callout is queued behind other processing, the verification call to Google will return `timeout-or-duplicate`. Regenerate the token immediately before submission, not on page load.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| Bot prevention configuration checklist | Surface-by-surface inventory of which reCAPTCHA mode is applied and which layered defenses are enabled |
| Apex verification class | Server-side reCAPTCHA token verification Apex class with Named Credential callout and score threshold handling |
| CSP and Remote Site metadata | CSP Trusted Site and Remote Site Setting entries needed for reCAPTCHA script loading and verification |

---

## Related Skills

- secure-coding-review-checklist -- use when preparing for an AppExchange security review that includes reCAPTCHA-protected surfaces
- experience-cloud-security -- use for broader Experience Cloud security hardening beyond bot prevention
- session-management-and-timeout -- use for session-level security controls that complement bot prevention at the authentication layer