Google reCAPTCHA on hosted authentication

Hosted sign-in, sign-up, waitlist, magic link, one-time codes, and MFA are public endpoints. Bots hit them the same way they hit any login form. Hosted authentication can now require Google reCAPTCHA v2 or v3, configured per environment as an Authentication > Add-ons add-on.

This is the longer note behind the August 1 changelog entry.

How it works

The add-on stores a site key, secret, optional score threshold (v3), and the protected actions. Selecting no actions protects all of them.

Supported checks:

Sign-in and sign-up
Waitlist
Magic link
One-time code
MFA verification

v2 is a visible checkbox on the flows that can render a widget. v3 is a score (0.0–1.0) without a puzzle; Authdog rejects scores below your minimum and fails closed when validation does not pass.

Tokens are verified server-side. A missing or failed challenge does not proceed when the add-on is enabled for that action.

A later Turnstile add-on covers the same action names. If both add-ons cover the same action, reCAPTCHA is used. Pick one.

Bot protection filters traffic before it authenticates. It complements Lidar and rate limiting; it does not replace them.

Set it up

Create a reCAPTCHA site in the Google admin console and add every domain that serves your Authdog auth pages, including any custom domain. Then, in the Authdog console:

Select the project and environment.
Open Authentication > Add-ons.
Choose Google reCAPTCHA.
Pick v3 or v2. Enter site key and secret.
For v3, set the minimum score.
Select protected actions (or leave empty for all).
Enable, save, and exercise sign-in (and sign-up or MFA if you listed them) on the hosted Account Portal.

The site key is public on the page. The secret is stored in Authdog and used only server-side.

Trust boundaries

Authdog trusts the Google siteverify response for the configured secret. Store the secret only in Authdog. Fail closed means a Google outage or a domain mismatch on the reCAPTCHA site will block those flows.

v2 on magic-link, OTP, or MFA actions does nothing useful — those flows need v3 (or, later, Turnstile invisible). A token from one action must not satisfy another.

Self-hosted deployments that cannot reach Google cannot use this add-on.

Try it

Enable v3 on signin in a non-production environment and complete a hosted sign-in. Full reference: Bot protection. The original release note is in the changelog.