# Cloudflare Turnstile en Authentik - Captcha previo a la autenticación

---

### Introducción

Este artículo documenta la integración de **Cloudflare Turnstile** como etapa de captcha **previa** al proceso de autenticación en **Authentik**, con el objetivo de filtrar tráfico automatizado **antes incluso de mostrar el formulario de login**.

La integración se sitúa directamente dentro del *authentication flow* de Authentik, actuando como una barrera inicial que reduce ruido, ataques de fuerza bruta y automatización maliciosa sin introducir fricción innecesaria para usuarios legítimos. No sustituye otros mecanismos (MFA, rate‑limit, CrowdSec), sino que los refuerza desde el primer punto de entrada.

---

### Enfoque general / Arquitectura

El enfoque se basa en insertar una **Captcha Stage** como primera etapa del `default-authentication-flow`:

```
Cliente → Captcha (Cloudflare Turnstile) → Formulario de login → MFA / resto de etapas
```

Características clave del enfoque:

* El captcha se presenta **antes** de solicitar credenciales.
* No se depende de puntuaciones de riesgo (Turnstile no las expone).
* Compatible con modos *Managed* e *Invisible*.
* Integración nativa en Authentik, sin proxies intermedios ni JS personalizado.

Este planteamiento reduce carga en Authentik y en servicios posteriores, descartando tráfico basura desde el primer renderizado de la página.

---

### Requisitos previos

* Instancia funcional de Authentik con acceso al **Admin Interface**.
* Dominio gestionado en Cloudflare.
* Acceso a la sección **Turnstile** en Cloudflare.
* Flujo de autenticación estándar (`default-authentication-flow`) sin modificaciones incompatibles.

---

### Desarrollo

#### Qué se hizo y por qué

Se opta por **Cloudflare Turnstile** frente a reCAPTCHA por varios motivos:

* No requiere interacción explícita en la mayoría de escenarios.
* No depende de tracking invasivo ni cookies de terceros.
* Integración directa soportada por Authentik.
* Menor fricción para usuarios humanos reales.

La decisión de colocarlo **antes del login** es deliberada: cualquier captcha posterior ya implica haber servido HTML sensible (formularios, endpoints, lógica de sesión).

---

#### Configuración utilizada (solo enlaces)

* Documentación oficial de Turnstile:
  [Widgets Turnstile](https://developers.cloudflare.com/turnstile/concepts/widget/)

* Widget Turnstile (Cloudflare Dashboard):
  Creación del widget desde el dominio correspondiente para obtener:

  * **Site Key**
  * **Secret Key**

---

#### Configuración en Authentik (conceptual)

1. Crear una **Captcha Stage** desde:
   *Admin → Flows and Stages → Stages → Create → Captcha Stage*

2. Parámetros relevantes de la etapa:

   * **Public Key** → *Turnstile Site Key*
   * **Private Key** → *Turnstile Secret Key*
   * **Enable Interactive** → Activado si el widget está en modo *Managed* o *Invisible*
   * **JS URL**
     `https://challenges.cloudflare.com/turnstile/v0/api.js`
   * **API URL**
     `https://challenges.cloudflare.com/turnstile/v0/siteverify`

   Las opciones de *score* se dejan por defecto, ya que **no aplican a Turnstile**.

3. Inserción en el flujo:
   *Admin → Flows and Stages → Flows → `default-authentication-flow`*

   En **Stage Bindings**:

   * Añadir la Captcha Stage.
   * Asignarle el **orden más bajo** del flujo para que se ejecute antes que cualquier otra etapa.

---

### Validación

Comprobaciones mínimas tras la integración:

* Acceso al endpoint de login:

  * El captcha aparece **antes** del formulario.
* Tráfico humano normal:

  * No se presentan desafíos visibles en la mayoría de casos.
* Bots y escáneres:

  * No alcanzan el formulario de autenticación.
* Logs de Authentik:

  * Sin errores de validación contra la API de Cloudflare.
* Dashboard de Cloudflare:

  * Métricas de Turnstile registrando solicitudes correctamente.

---

### Decisiones importantes o problemas detectados

* Turnstile **no soporta puntuaciones**, por lo que cualquier lógica basada en umbrales debe descartarse.
* El orden de la etapa es crítico: si no es la primera, pierde sentido.
* No interfiere con MFA ni con autenticación por WebAuthn: actúa antes de todo.

---

### Resumen breve

* Captcha basado en Cloudflare Turnstile.
* Integrado como primera etapa del `default-authentication-flow`.
* Filtrado de bots **antes del login**.
* Sin fricción visible para usuarios legítimos.
* Implementación nativa, limpia y mantenible.

---

### Referencias

* [Cloudflare Turnstile — Documentación oficial](https://developers.cloudflare.com/turnstile/)

* [Authentik — Captcha Stages](https://docs.goauthentik.io/add-secure-apps/flows-stages/stages/captcha/)

* [Protect Authentik with Cloudflare Turnstile - Créditos al autor del vídeo en YouTube](https://www.youtube.com/watch?v=Fe5SttNa2lU)