Captcha

This documentation outlines the CAPTCHA protection implemented in the Harmoney application to guard the white label authentication flows against automated abuse. Harmoney uses Cloudflare Turnstile as its CAPTCHA provider.

How it works

When CAPTCHA protection is enabled for a white label, a Cloudflare Turnstile widget is rendered on the protected pages and the user must pass the challenge before their request is accepted:

1. The page renders the Turnstile widget using the white label's public site key.
2. When the challenge is completed, Turnstile returns a response token to the browser.
3. On submitting the form, the token is sent to the Harmoney back-end.
4. The back-end verifies the token server-side by calling the Turnstile siteverify endpoint with the white label's secret key. The request only proceeds when verification succeeds.

If CAPTCHA is enabled but the token is missing or cannot be validated, the request is rejected.

When CAPTCHA protection is disabled, no widget is shown and the requests proceed without a challenge.

warning

The widget is loaded from Cloudflare, so the Content Security Policy of the environment must allow https://challenges.cloudflare.com in both script-src (to load the Turnstile script) and frame-src (the widget renders the challenge in an iframe). Without it the browser blocks the widget and no token is ever generated, so every protected request is rejected.

Protected pages

Page	Protected request
Registration	Creating a registration.
SMS registration	Requesting the registration SMS.
Login	Submitting the username, the first step of the login flow.
Forgot password	Requesting a password reset.
Direct sales landing page	Starting a flow as an anonymous visitor. Visitors that are already authenticated are not challenged again.

Configuration overview

CAPTCHA protection is configured per white label. The settings live on the white label's settings.captcha object and can be edited through the Details card on the white label detail page (or via configuration import/export).

White label

Setting	Technical name	Description
Captcha enabled	enabled	Whether CAPTCHA protection is enabled for this white label's public pages, listed under Protected pages.
Captcha site key	siteKey	Public Cloudflare Turnstile site key used to render the CAPTCHA widget. Required when CAPTCHA is enabled.
Captcha secret key	secretKey	Cloudflare Turnstile secret key used to verify CAPTCHA tokens. Required when CAPTCHA is enabled.
Captcha verification URL	url	Base URL of the Cloudflare Turnstile verification endpoint. Defaults to https://challenges.cloudflare.com when left empty.

The site key and secret key are obtained from the Cloudflare Turnstile dashboard when creating a Turnstile widget for the white label's domain.

When Captcha enabled is turned on, the site key and secret key become required in the form. The verification URL is optional and only needs to be set to override the default Cloudflare Turnstile endpoint.

Example settings.captcha configuration:

{
  "enabled": true,
  "siteKey": "0x4AAAAAAA_example_site_key",
  "secretKey": "0x4AAAAAAA_example_secret_key",
  "url": "https://challenges.cloudflare.com"
}

note

CAPTCHA protection applies to the pages listed under Protected pages. The same site key and secret key are used for all of them.