Skip to main content

Google reCAPTCHA

Community-contributed integration

This integration is community-maintained. Reference: ory/integrates/fraud-bot-protection/recaptcha.

Google reCAPTCHA is a CAPTCHA service that comes in three variants: v2 (checkbox and image challenges), v3 (invisible scoring from 0.0 to 1.0), and Enterprise (additional signals).

How it works​

  1. Registration / login UI embeds the reCAPTCHA client widget (v2 or v3); widget returns a token (g-recaptcha-response).
  2. Form submits to Ory's flow with the token.
  3. Ory Action on registration.after / login.after with can_interrupt: true calls the handler.
  4. Handler POSTs to https://www.google.com/recaptcha/api/siteverify with the token + Secret Key.
  5. For v3, handler also checks the returned score against a threshold (typical: 0.5).
  6. On fail, handler returns an error and Ory blocks.

Notable​

  • Two keys: Site Key (public) and Secret Key (server).
  • The token reaches the webhook in transient_payload, which exists only once the user submits the flow. Keep the action on the after trigger with can_interrupt: true: a before action runs when Ory Kratos Identities creates the flow and never sees the token.
  • reCAPTCHA v3 returns a score (0.0–1.0); higher = more human. Tune threshold per flow risk profile.
  • reCAPTCHA Enterprise has a different API surface (recaptchaenterprise.googleapis.com) and returns richer signals.

Resources​