reCAPTCHA
Integra el servicio Google reCAPTCHA con el módulo CAPTCHA de Drupal para proteger formularios contra spam y abuso.
recaptcha
Install
composer require 'drupal/recaptcha:8.x-3.4'
composer require 'drupal/recaptcha:8.x-3.2'
Overview
El módulo reCAPTCHA proporciona integración con el servicio web reCAPTCHA de Google, ofreciendo protección avanzada contra bots para formularios de Drupal. Utiliza la API Google No CAPTCHA reCAPTCHA (reCAPTCHA v2), que emplea un motor de análisis de riesgos avanzado y CAPTCHAs adaptativos para distinguir entre usuarios humanos y software automatizado.
Este módulo extiende el módulo CAPTCHA proporcionando reCAPTCHA como una opción de tipo CAPTCHA. Una vez configurado con las claves de sitio y secretas de Google, los administradores pueden asignar protección reCAPTCHA a cualquier formulario gestionado por el módulo CAPTCHA, incluyendo inicio de sesión, registro, restablecimiento de contraseña, formularios de contacto y más.
El módulo soporta múltiples temas de widget (claro y oscuro), tipos de CAPTCHA (imagen y audio para accesibilidad), varios tamaños (normal y compacto), e incluye un mecanismo de respaldo para navegadores con JavaScript deshabilitado. Para regiones donde los servicios de Google están restringidos, el módulo ofrece un modo global que utiliza endpoints alternativos de reCAPTCHA (recaptcha.net en lugar de google.com).
Features
- Integración con Google reCAPTCHA v2 (No CAPTCHA reCAPTCHA) con análisis de riesgos avanzado
- Temas de widget configurables (claro/oscuro) para personalización visual
- Soporte para tipos de CAPTCHA de imagen y audio para cumplimiento de accesibilidad
- Tamaños de widget normal y compacto para adaptarse a diferentes diseños de formularios
- Soporte de respaldo para navegadores con JavaScript deshabilitado mediante elemento noscript
- Modo global para regiones donde google.com es inaccesible (usa recaptcha.net)
- Opción de verificación de hostname para seguridad mejorada cuando la validación de dominio está deshabilitada en la configuración de Google
- Respaldo automático a Math CAPTCHA cuando las claves de reCAPTCHA no están configuradas
- Soporte multiidioma con detección automática de idioma
- Compatibilidad total con el sistema de caché de Drupal - formularios CAPTCHA cacheables
- Soporte de migración desde instalaciones de Drupal 6 y Drupal 7
- Integración perfecta con el sistema de protección de formularios del módulo CAPTCHA
Use Cases
Proteger formularios de inicio de sesión contra ataques de fuerza bruta
Habilita reCAPTCHA en el formulario de inicio de sesión de usuario para prevenir ataques automatizados de fuerza bruta de contraseñas. Navega a la configuración de CAPTCHA, añade un punto CAPTCHA para 'user_login_form' y selecciona 'reCAPTCHA' como tipo de desafío. Esto añade el análisis de riesgos de Google para detectar y bloquear intentos de inicio de sesión automatizados mientras permite a los usuarios legítimos iniciar sesión con fricción mínima.
Prevenir spam en formularios de contacto
Aplica protección reCAPTCHA a formularios de contacto para bloquear envíos de spam de bots. Configura un punto CAPTCHA para tu formulario de contacto y asigna reCAPTCHA. El análisis de riesgos invisible desafiará envíos sospechosos mientras la mayoría de usuarios legítimos pasan sin ver un desafío CAPTCHA.
Asegurar el registro de usuarios
Protege el formulario de registro de usuarios de la creación automatizada de cuentas habilitando reCAPTCHA. Esto previene que los bots creen cuentas falsas que podrían usarse para spam, abuso o ataques de relleno de credenciales.
Implementación de CAPTCHA compatible con accesibilidad
Usa la opción de tipo CAPTCHA de audio para proporcionar una alternativa accesible para usuarios con discapacidad visual. Configura los ajustes del widget para habilitar desafíos de audio, asegurando el cumplimiento de requisitos de accesibilidad mientras mantienes la protección contra spam.
Despliegue en China o regiones restringidas
Para sitios que sirven usuarios en regiones donde google.com está bloqueado (como China), habilita la opción 'Usar reCAPTCHA globalmente'. Esto cambia todas las solicitudes de reCAPTCHA para usar el dominio recaptcha.net, que es accesible en estas regiones mientras proporciona la misma protección.
Coincidir el diseño del sitio con la selección de tema
Elige entre temas de reCAPTCHA claro y oscuro para coincidir con el diseño visual de tu sitio. Para sitios con tema oscuro, selecciona la opción de tema 'Oscuro' para asegurar que el widget CAPTCHA se integre perfectamente con tu estética de diseño.
Tips
- Siempre prueba la configuración de reCAPTCHA en una ventana de navegador incógnito/privado para evitar estados en caché
- Usa la opción de tamaño 'Compacto' para formularios en barras laterales o diseños angostos donde el espacio es limitado
- Habilita el respaldo noscript solo si necesitas soportar usuarios con JavaScript deshabilitado - añade markup extra
- El tema oscuro funciona bien con sitios con modo oscuro habilitado pero puede verse discordante en fondos claros
- Registra claves reCAPTCHA separadas para entornos de desarrollo y producción para evitar problemas de puntuación
- Monitorea tu consola de administración de Google reCAPTCHA para patrones de tráfico y ajusta la configuración si ves tasas de fallo altas
- Considera usar reCAPTCHA v3 para protección invisible si está disponible a través de otros módulos
Technical Details
Admin Pages 1
/admin/config/people/captcha/recaptcha
Configura los ajustes de Google reCAPTCHA para tu sitio Drupal. Esta página permite a los administradores ingresar credenciales API y personalizar la apariencia y comportamiento de los widgets reCAPTCHA mostrados en formularios protegidos.
Permissions 1
Hooks 4
hook_captcha
Implementa el hook del módulo CAPTCHA para registrar reCAPTCHA como un tipo de CAPTCHA y generar el elemento de formulario reCAPTCHA. Devuelve la lista de tipos de CAPTCHA disponibles en la operación 'list' y construye el widget reCAPTCHA completo con callback de validación en la operación 'generate'.
hook_theme
Registra el hook de tema recaptcha_widget_noscript para renderizar el contenido de respaldo noscript cuando JavaScript está deshabilitado.
hook_library_info_build
Construye dinámicamente definiciones de biblioteca para cada idioma habilitado. Crea bibliotecas JavaScript externas apuntando a la API de reCAPTCHA de Google con URLs específicas de idioma. Usa el dominio google.com o recaptcha.net basándose en el ajuste de configuración 'use_globally'.
hook_help
Proporciona contenido de página de ayuda para el módulo reCAPTCHA explicando su propósito, características e instrucciones de configuración paso a paso.
Troubleshooting 7
Verifica que tanto la clave de sitio como la clave secreta estén correctamente configuradas en los ajustes de reCAPTCHA. Revisa la consola del navegador por errores de JavaScript. Asegúrate de que el módulo CAPTCHA tenga reCAPTCHA asignado al formulario específico. Limpia todas las cachés después de los cambios de configuración.
Esto ocurre cuando la clave de sitio o la clave secreta está vacía o es inválida. Navega a los ajustes de reCAPTCHA e ingresa credenciales API válidas obtenidas de la consola de administración de reCAPTCHA de Google.
El dominio que hace las solicitudes no coincide con los dominios registrados en tu configuración de Google reCAPTCHA. Añade el dominio a tu configuración de Google reCAPTCHA, o habilita 'Validación de nombre de dominio local' en los ajustes del módulo si 'Verificar el origen de las soluciones reCAPTCHA' está deshabilitado en la configuración de Google.
Asegúrate de que tu servidor pueda hacer conexiones HTTPS salientes a google.com (o recaptcha.net si usas el modo global). El servidor necesita comunicarse con el endpoint de verificación de Google. Revisa las reglas del firewall y la configuración del proxy.
El paquete de certificados CA del servidor puede estar desactualizado y no poder verificar el certificado SSL de Google. Actualiza los certificados CA del servidor o configura PHP/cURL para usar un paquete de certificados actualizado.
Habilita la casilla 'Usar reCAPTCHA globalmente' en los ajustes de reCAPTCHA. Esto cambia el endpoint de la API de www.google.com a www.recaptcha.net, que es accesible en regiones restringidas.
El módulo incluye JavaScript que maneja el re-renderizado de reCAPTCHA para formularios AJAX. Asegúrate de que la biblioteca recaptcha/recaptcha esté correctamente adjunta. El behavior reinicia el widget CAPTCHA en elementos ya procesados.
Security Notes 6
- Nunca expongas tu clave secreta en código del lado del cliente o repositorios públicos - solo debe usarse del lado del servidor
- Habilita 'Validación de nombre de dominio local' cuando 'Verificar el origen de las soluciones reCAPTCHA' está deshabilitado en la configuración de Google para prevenir el robo de claves y uso en dominios no autorizados
- Las claves reCAPTCHA son específicas del dominio - asegúrate de que tus claves de producción estén registradas para todos los dominios incluyendo variantes www y sin www
- El módulo valida respuestas del lado del servidor usando la API de Google - la validación solo del lado del cliente es insuficiente
- Considera habilitar el registro detallado durante la configuración inicial para monitorear fallos de verificación y sus causas
- El respaldo a Math CAPTCHA cuando faltan las claves asegura que los formularios permanezcan protegidos incluso si la configuración de reCAPTCHA está incompleta