core.bones.captcha

Classes

CaptchaBone

The CaptchaBone validates reCAPTCHA Enterprise tokens to protect forms from bots.

Module Contents

class core.bones.captcha.CaptchaBone(*, public_key=None, score_threshold=0.5, render_challenge=False, recaptcha_action='', **kwargs)

Bases: viur.core.bones.base.BaseBone

The CaptchaBone validates reCAPTCHA Enterprise tokens to protect forms from bots.

It uses the Google reCAPTCHA Enterprise API and supports both invisible (v3-style score-based) and visible (checkbox widget) challenges via the render_challenge parameter.

The token is submitted by the client as the bone’s field value and verified server-side against the configured site key. A configurable score threshold determines whether invisible challenges pass.

See also

Google reCAPTCHA Enterprise setup <https://cloud.google.com/recaptcha/docs/set-up-non-google-cloud-environments-api-keys> for creating a site key and enabling the API.

Option core.config.Security.captcha_default_public_key for global security settings.

Option core.config.Security.captcha_enforce_always to enforce validation even on development servers.

Initializes a new CaptchaBone.

Parameters:

  • public_key (str) – The reCAPTCHA Enterprise site key shown to the client. Can be omitted if set globally via core.config.Security.captcha_default_public_key.

  • score_threshold (float) – Minimum score (0–1) required for invisible challenges to pass. Ignored when render_challenge is True.

  • render_challenge (bool) – If True, renders a visible checkbox widget instead of running an invisible background check.

  • recaptcha_action (str) – The action name passed to reCAPTCHA for analytics and scoring. Should match the action used on the client side.

  • kwargs (Any)

type = 'captcha'
public_key = None
render_challenge = False
recaptcha_action = ''
score_threshold = 0.5
required = True
serialize(skel, name, parentIndexed)

Serializing the Captcha bone is not possible so it return False

Parameters:

  • skel (viur.core.skeleton.SkeletonInstance)

  • name (str)

  • parentIndexed (bool)

Return type:

bool

unserialize(skel, name)

Stores the public_key in the SkeletonInstance

Parameters:

  • skel (viur.core.skeleton.SkeletonInstance) – The target SkeletonInstance.

  • name – The name of the CaptchaBone in the SkeletonInstance.

Returns:

boolean, that is true, as the Captcha bone is always unserialized successfully.

Return type:

Literal[True]

fromClient(skel, name, data)

Load the reCAPTCHA token from the provided data and validate it with the help of the API.

reCAPTCHA provides the token via callback usually as “g-recaptcha-response”, but to fit into the skeleton logic, we support both names. So the token can be provided as “g-recaptcha-response” or the name of the CaptchaBone in the Skeleton. While the latter one is the preferred name.

Parameters:

  • skel (viur.core.skeleton.SkeletonInstance)

  • name (str)

  • data (dict)

Return type:

None | list[viur.core.bones.base.ReadFromClientError]

structure()

Describes the bone and its settings as an JSON-serializable dict. This function has to be implemented for subsequent, specialized bone types.

Return type:

dict