Cloudflare Turnstile

Configuring Cloudflare Turnstile CAPTCHA for login protection.

Nuxt Secure uses Cloudflare Turnstile to protect the login form from automated attacks. Users must pass a CAPTCHA challenge before their credentials are verified.

Setup

1. Open the Cloudflare dashboard

   Log in to your Cloudflare dashboard and navigate to Turnstile in the sidebar.

2. Add a new site

   Click Add Site, enter a name, and provide the domain where Nuxt Secure will be deployed. Cloudflare will generate a Site Key and a Secret Key.

3. Add the keys to your .env file

   .env

   NUXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
   TURNSTILE_SECRET_KEY=your-secret-key
   

How it works

The @nuxtjs/turnstile module (^1.1.1) is listed in the modules array of nuxt.config.ts. It automatically registers a <NuxtTurnstile> component and reads the site key from turnstile.siteKey (populated from NUXT_PUBLIC_TURNSTILE_SITE_KEY).

When the user submits the login form:

1. The browser includes a turnstileToken generated by the Turnstile widget.
2. The server API handler receives the token along with the user’s credentials.
3. The server sends the token to Cloudflare’s verification endpoint before processing the login:

server/api/auth/login.post.ts

const verifyUrl = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'
const turnstileResponse = await fetch(verifyUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: `secret=${config.turnstile.secretKey}&response=${turnstileToken}`
})

4. If verification fails, the server responds with HTTP 400 and the message "Fallo en la validación del captcha." — no further login processing occurs.

Local development

For local development, use Cloudflare’s official test keys. These always pass verification without contacting Cloudflare’s servers:

.env

NUXT_PUBLIC_TURNSTILE_SITE_KEY=1x00000000000000000000AA
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA

These test keys are provided by Cloudflare for development and CI use. Do not use them in production.

Without valid Turnstile keys, the CAPTCHA widget will not render and all login attempts will fail. Make sure both NUXT_PUBLIC_TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY are set before running the application.

Key reference

Variable	Visibility	Purpose
NUXT_PUBLIC_TURNSTILE_SITE_KEY	Public (browser)	Renders the Turnstile widget in the login form.
TURNSTILE_SECRET_KEY	Server only	Verifies the CAPTCHA token submitted with each login request.