Skip to content

Require a Turnstile challenge

This guide puts a Cloudflare Turnstile challenge on the auth server’s sign-in, forgot-password and registration forms, so they accept a submission only from someone who passed it.

Turnstile is Cloudflare’s check that a visitor is a person and not a script. You don’t need to serve Goiabada through Cloudflare to use it. Without it, anyone who knows an email address can spend that account’s budget of wrong passwords and block its password sign-in for up to an hour, or spend the address’s budget of reset and registration emails. With it on, a script that can’t pass the challenge can’t spend either. The challenge is off until you turn it on.

  1. In the Cloudflare dashboard, open Turnstile and add a widget.

  2. Add one hostname: the host of the auth server’s public URL, GOIABADA_AUTHSERVER_BASEURL, with no scheme and no port. For https://auth.example.com, that’s auth.example.com. The auth server refuses a token solved on any other host. Don’t add localhost or another local hostname to a production widget.

  3. Choose the Managed mode, where most visitors never have to click anything. Non-interactive and Invisible work too. Don’t opt for pre-clearance: it’s only for sites served through Cloudflare’s proxy. Create the widget.

  4. In the admin console, open Admin, Turnstile. Paste the widget’s site key into Site key and its secret key into Secret key, turn on Require the challenge, click Save, and confirm.

  5. Open the admin console in a private window and click Administration. On the sign-in page, Cloudflare’s widget sits above Sign in, and once it shows a tick, the form signs you in.

The change applies to the next request on every replica, with no restart. Administrators sign in to the admin console through the same form, so they pass the challenge too.

The challenge is on three forms, each with its own widget:

A submission is accepted only with a token Cloudflare verified for the auth server’s host and for that form, so a token solved on one form doesn’t pass on another. A submission without one is refused before any rate limit counts it and before any password is checked, so it spends no budget.

The other steps of a sign-in, the one-time code, recovery codes and consent, and the pages a reset or activation link opens, carry no challenge.

  • The three forms need JavaScript. A visitor whose browser runs no scripts gets no token, and the forms refuse them.
  • Your visitors’ browsers contact Cloudflare. While the challenge is on, the three forms load the widget’s script and frame from https://challenges.cloudflare.com, and their Content-Security-Policy admits that origin to script-src. No other page loads anything from Cloudflare. If you set a policy of your own at a proxy, admit that origin on those three forms. Telling your visitors, and whether to ask them first, is up to you: see Personal data.
  • The auth server calls Cloudflare. It sends each token to Cloudflare’s siteverify endpoint at https://challenges.cloudflare.com, with the secret key, and waits up to 3 seconds for the answer. Let the auth server reach it over HTTPS. Saving a new secret key, or turning the challenge on, needs it too.

When Cloudflare can’t be reached, gives no usable answer within 3 seconds, or refuses the secret key, the three forms work as they do with the challenge off: the rate limits still apply, and no submission is refused for want of an answer. The auth server logs an error, and the goiabada_challenge_verifications_total metric counts it, as unavailable or as misconfigured. Alert on both. A rising misconfigured usually means the secret key was rotated or the widget deleted in Cloudflare: save the widget’s current secret key under Admin, Turnstile.

The auth server asks Cloudflare about at most 64 submissions at a time, and the 3 seconds include any wait for a turn. A submission still waiting when they run out counts as unavailable too, and its error is logged with the reason busy. Many of those mean a flood of submissions: block its source at your proxy or CDN.

The password grant takes a password straight from a client, with no page to show a challenge on, and it shares each account’s budget of wrong passwords with the sign-in form. A public client with the password grant enabled lets anyone send it passwords, so through it a script can still spend an account’s budget and block its sign-in on the form. A confidential client has to prove its secret first. So the challenge stops that only while no public client has the password grant enabled. It’s off by default.

Turn off Require the challenge under Admin, Turnstile and click Save. The keys stay stored, so turning it back on needs no new ones. When nobody can sign in to do that, goiabada-authserver recover --disable-turnstile turns it off from the command line: see Locked out of the admin console.