← Cloudflare Turnstile / turnstile

Начало работы

Turnstile защищает формы вашего сайта от ботов. Работает он в два шага: виджет на JavaScript выполняет проверки в браузере посетителя и выдаёт токен, а затем ваш сервер отправляет этот токен в Cloudflare для подтверждения. В этом руководстве описана настройка обоих шагов.

Перед началом работы вам понадобится:

• Аккаунт Cloudflare
• Сайт или веб-приложение, которое нужно защитить
• Базовые знания HTML и выбранного вами серверного языка

Виджет Turnstile представляет собой экземпляр Turnstile, встроенный в вашу веб-страницу. У каждого виджета есть sitekey (открытый идентификатор, который вы размещаете в своём HTML) и секретный ключ (закрытое значение, которым ваш сервер проверяет токены).

У каждого виджета своя пара sitekey и secret key, а также собственный набор параметров.

Внедрение Turnstile состоит из двух обязательных частей, которые работают вместе:

1. На стороне клиента: Встраивание виджета

   Добавьте виджет Turnstile на веб-страницу, чтобы показывать посетителям проверку и получать токены. Токен представляет собой строку (до 2,048 символов), которая создаётся, когда посетитель проходит проверку.

2. На стороне сервера: Проверка токена

   Отправляйте токены в Cloudflare Siteverify API (конечная точка для валидации токенов Turnstile), чтобы убедиться в их подлинности и целостности.

Turnstile задуман как самостоятельный сервис. Использовать его можно на любом сайте, независимо от того, проксируется ли он через сеть Cloudflare. Благодаря этому виджет гибко разворачивается в мультиоблачных средах, на локальной инфраструктуре и на сайтах, работающих через другие CDN. Клиентский виджет и серверная проверка полностью автономны.

См. Внедрение ниже: там описано, как внедрить Turnstile на вашем сайте.

Чтобы внедрить Turnstile, выполните шаги ниже.

Сначала создайте виджет Turnstile: так вы получите sitekey и secret key.

Выберите подходящий способ внедрения:

Добавьте виджет Turnstile в формы и приложения на своей веб-странице.

См. Встраивание виджета, где подробнее описаны неявный и явный способы рендеринга.

Реализуйте серверную проверку токенов, которые создают ваши виджеты.

См. Проверка токена, чтобы защитить свою реализацию корректной проверкой токена.

Мобильные приложения и реализации на WebView требуют отдельного подхода.

См. Реализация на мобильных устройствах, где описана интеграция в мобильные приложения.

Если сейчас вы используете reCAPTCHA, hCaptcha или другой сервис CAPTCHA, Turnstile заменит его без переделок. Достаточно скопировать наш скрипт и вставить его туда, где сегодня подключён прежний.

См. Переход, где пошагово описан переход с других сервисов CAPTCHA.

• Проверка на стороне сервера обязательна. Токены Turnstile необходимо проверять через Siteverify API: токен может оказаться недействительным, просроченным или уже использованным. Если этого не делать, в вашей реализации останутся серьёзные уязвимости. Без вызова Siteverify настройка Turnstile не завершена, и метрики проверки токенов будут нулевыми в разделе Turnstile Analytics.

• Токен истекает через 300 секунд (5 минут). Каждый токен проверяется только один раз. Вместо просроченного или уже использованного токена нужно запросить новую проверку.

• Берегите секретные ключи: никогда не размещайте их в клиентском коде.
• Регулярно меняйте ключи: используйте для этого API или панель управления.
• Ограничьте список имён хостов: разрешайте виджеты только на доменах, которые вы контролируете.
• Следите за использованием. Нетипичное поведение выявляйте с помощью аналитики.

• Давайте понятные названия. Называйте виджеты по их назначению, например "Форма входа" или "Страница контактов".
• Разделяйте среды: используйте разные виджеты для разработки, промежуточной среды и рабочей среды.
• Ведите учёт того, какой виджет где используется.
• При работе с Terraform держите конфигурации виджетов в системе контроля версий.