← Все продукты

Turnstile

Turnstile, виджет проверки от Cloudflare, выдаёт токен, когда браузер посетителя проходит набор неинтерактивных проверок. Затем бэкенд сайта подтверждает этот токен через API siteverify. На этой странице описаны режимы виджета, жизненный цикл токена, документированные лимиты и требования к интеграции.

Управление документом

Дана
Технический писатель, Integrity Czech Republic s.r.o.

Обзор

Turnstile служит механизмом проверки для веб-форм и эндпоинтов: вместо интерактивной головоломки он выполняет набор проверок в браузере посетителя. При успешном прохождении создаётся токен; сайт отправляет его со своего бэкенда на эндпоинт siteverify Cloudflare и получает подтверждение, что проверка пройдена именно для этого сайта.

Turnstile можно использовать на любом сайте. Проксирование через Cloudflare не требуется, тарифный план для зоны Cloudflare тоже не нужен.

Cloudflare указывает, что Turnstile не показывает изображений или текста для распознавания (https://developers.cloudflare.com/turnstile/, дата обращения 2026-08-28). В режиме Managed посетителю может быть предложено одно действие, например установка флажка. Доля посетителей, которым предлагается такое действие, зависит от сайта и здесь не приводится: долю решённых проверок для вашего развёртывания показывает аналитика виджета.

Влияние трения в форме на конверсию зависит от сайта и методики измерения, поэтому цифр здесь нет. Если этот показатель важен, измерьте долю завершённых отправок на своих формах до внедрения и после него.

Архитектура

Внедрение Turnstile состоит из трёх частей:

1. Виджет. Небольшой компонент на JavaScript, встроенный в страницу и настроенный с помощью открытого sitekey. Он выполняет проверки прямо в браузере: вычисления proof of work на JavaScript, проверку согласованности браузерного окружения и поведенческие сигналы. Сайт при этом не обязан работать через Cloudflare.
2. Токен. При успешной проверке виджет записывает токен в форму или возвращает его через функцию обратного вызова. Токен подтверждает, что проверка пройдена для конкретного sitekey.
3. Проверка на стороне сервера. Бэкенд отправляет токен вместе с секретным ключом на https://challenges.cloudflare.com/turnstile/v0/siteverify. Ответ сообщает об успехе или неудаче, содержит коды ошибок, имя хоста и метку времени проверки. Бэкенд должен принимать отправленное действие только после успешной валидации.

Защиту даёт именно серверный шаг. Токен в запросе, который никто не проверяет, ничего не доказывает: тело запроса контролирует клиент. По документации Cloudflare токен действует 300 секунд и проверяется один раз, поэтому повторная валидация того же токена завершается ошибкой (https://developers.cloudflare.com/turnstile/get-started/server-side-validation/, дата обращения 2026-08-28). idempotency_key можно передать, если тот же токен нужно проверить ещё раз при повторной попытке.

В зонах, проксируемых через Cloudflare, Turnstile может дополнительно выдавать pre-clearance. Посетитель, прошедший виджет, в течение срока действия clearance не получает проверок от правил WAF и Bot Management.

Возможности

Модель настройки

Объект конфигурации и есть виджет: он определяется значением sitekey и связан с секретным ключом. Настройки виджета:

• Режим. Managed, Non-interactive или Invisible.
• Имена хостов. Домены, на которых виджету разрешено отображаться. Имя хоста возвращается в ответе проверки, и бэкенд должен его сверять.
• Ограничение по доменам. Применяется ли строгая проверка имени хоста.
• Pre-clearance. Выпускает ли виджет clearance и на какую область он распространяется.
• Внешний вид и запуск. Отображается ли виджет всегда или только когда нужно взаимодействие, и выполняется ли проверка при отрисовке или по запросу.

На стороне клиента для каждого экземпляра виджета задаются action (метка, по которой видно, с какой формы получен токен) и cdata (непрозрачное значение, которое возвращается в ответе валидации). Оба значения возвращает siteverify, и оба нужно проверять: они привязывают токен к операции, для которой он выдан.

Cloudflare публикует тестовые sitekey и секретные ключи, которые всегда проходят проверку, всегда её проваливают или всегда требуют действия посетителя. Используйте их в автотестах вместо того, чтобы отключать проверку в тестовых окружениях: отключённая ветка проверки нередко попадает и на боевой сайт.

Лимиты и ограничения

Документированные ограничения (проверено 2026-08-31 по https://developers.cloudflare.com/turnstile/plans/):

Поведение токена, по материалам https://developers.cloudflare.com/turnstile/get-started/server-side-validation/, дата обращения 2026-08-28: токен действителен 300 секунд, и проверить его можно только один раз, если не передан idempotency_key.

Дополнительные ограничения:

• Cloudflare не публикует месячную квоту на запросы к siteverify. Не закладывайте в архитектуру конкретное месячное значение, а любые такие цифры из сторонних источников считайте непроверенными.
• Лимиты на виджеты и имена хостов сверх стандартных значений доступны только по договору Enterprise. Первым обычно исчерпывается лимит из 10 имён хостов на виджет, потому что домены со временем накапливаются.
• Turnstile защищает именно те эндпоинты, где отображается виджет и где проверяется токен. На эндпоинты без виджета, включая мобильные API и устаревшие маршруты, Turnstile не влияет.
• Виджету нужен JavaScript в браузере. Клиенты, которые не выполняют JavaScript, не смогут получить токен, поэтому для эндпоинта, обслуживающего таких клиентов, нужен другой механизм защиты.
• Клиенты без браузера, в том числе серверные потребители API, пройти проверку не могут. Поэтому не ставьте Turnstile перед эндпоинтом, предназначенным для обмена между машинами.
• Pre-clearance работает только там, где защищаемый сайт проксируется через Cloudflare.
• Turnstile возвращает решение по сеансу браузера. Он не аутентифицирует пользователя и не подтверждает, что отправленное содержимое легитимно.
• Соответствие конкретного развёртывания требованиям приватности и регуляторов зависит от того, как сайт обрабатывает данные вокруг виджета, и от правовой оценки. Документация продукта не может подтвердить соответствие за оператора сайта. Исходные данные для такой оценки дают собственные заявления Cloudflare о том, какие данные собирает Turnstile.

Доступность по планам

Развёртывание

Предварительные требования.

• Определите, какие эндпоинты подвергаются злоупотреблениям и что на это указывает: фальшивые регистрации, попытки credential stuffing, спам в комментариях или в форме обратной связи, злоупотребление купонами и промокодами.
• Определите все сервисы, которые принимают затронутые отправки формы. Часто одна форма отправляет данные сразу нескольким бэкендам, и проверку должен выполнять каждый бэкенд, который принимает это действие.
• Отметьте, к каким из этих эндпоинтов обращаются и небраузерные клиенты: пройти проверку они не могут.
• Зафиксируйте базовые показатели: количество отправок, долю завершённых проверок и выбранный выше показатель злоупотреблений.
• Определите, какую существующую интеграцию с CAPTCHA нужно заменить и какие участки кода к ней обращаются.
• Определите, где будет храниться секретный ключ, и убедитесь, что его нет ни в одном клиентском бандле или репозитории.

Поэтапная проверка. Начните с одного эндпоинта, где злоупотребления видны отчётливо. Виджет и серверную проверку внедряйте вместе, а первое время только записывайте результаты проверки в журнал, не отклоняя отправленные формы. Посмотрите, какая доля обращений приходит с действительным токеном, с недействительным и вовсе без токена. Прежде чем включать отклонение, убедитесь с помощью тестовых ключей Cloudflare, что путь отказа отрабатывает правильно.

Настройка.

1. Создавайте по одному виджету на логическое приложение, а не на каждую форму, и настраивайте для него имена хостов.
2. Укажите action для каждой формы, чтобы токены можно было соотнести с ней, и проверяйте его в ответе валидации.
3. Реализуйте серверную проверку в каждом сервисе, который принимает защищённые отправки. Отсутствующий или недействительный токен считайте поводом отклонить запрос.
4. Проверьте hostname и action в ответе siteverify, а не только поле success.
5. Режим виджета выбирайте отдельно для каждой формы: invisible или non-interactive там, где это допускает уровень злоупотреблений, и managed там, где не допускает.
6. Обрабатывайте на клиенте функции обратного вызова для истечения срока действия токена и для ошибок, чтобы посетитель, который долго заполняет форму, получал новый токен, а не непонятную ошибку.
7. Если сайт проксируется через Cloudflare, включите pre-clearance и используйте Turnstile вместе с правилами ограничения частоты запросов, а при наличии лицензии и с правилами для ботов.
8. Удаляйте прежнюю интеграцию CAPTCHA и её ключи только после того, как новый сценарий проверен.

Переключение. Включайте отклонение непроверенных отправок по одному эндпоинту за раз и на каждом шаге следите за долей успешных прохождений. Прежний механизм защиты держите включённым, пока эндпоинт не будет проверен, и только затем убирайте его.

Верификация.

• Убедитесь, что отправка без токена отклоняется на стороне сервера. Проверяйте это прямым обращением к эндпоинту, а не через форму.
• Убедитесь, что повторно предъявленный токен отклоняется при втором использовании.
• Убедитесь, что секретный ключ не попадает ни в один клиентский ресурс.
• Убедитесь, что доля заполнений защищённых форм не вышла за пределы обычного диапазона.
• Убедитесь, что метрика злоупотреблений, зафиксированная на этапе подготовки, изменилась в ожидаемую сторону, и проверьте, не переместилась ли активность на соседний эндпоинт.
• Проверьте поведение в браузерах и вспомогательных технологиях из вашей матрицы поддержки.

Откат. Отключите отклонение на бэкенде: прежнее поведение приёма вернётся без выпуска новой версии фронтенда. Виджет пусть продолжает отображаться, пока вы разбираетесь в причине. Кодовый путь предыдущего механизма защиты сохраняйте до тех пор, пока не убедитесь в стабильности развёртывания.

Вопросы эксплуатации

Отслеживайте по каждому виджету долю решённых проверок и долю неудачных валидаций. Рост числа неудачных валидаций обычно означает не усиление атак, а ошибку на стороне клиента, истёкший токен в длинной форме или изменение порядка отправки формы.

После развёртывания следите за смещением активности. Когда защищённая форма становится слишком дорогой для атакующего, нагрузка обычно уходит на незащищённую точку входа: мобильный API или устаревший путь. Включите такие точки входа в проверку.

Меняйте секретный ключ по заранее заданному графику, а также после любого инцидента, затронувшего бэкенд. Храните его вместе с остальными секретами, а не в файлах конфигурации.

Проектируя многошаговые формы, учитывайте срок жизни токена. Токен, выданный в начале длинного сценария, к моменту отправки формы может выйти за пределы своих 300 секунд. В этом случае запускайте проверку заново прямо перед отправкой.

Следите за тем, сколько имён хостов настроено на каждом виджете, и сверяйтесь с документированным лимитом: если виджет уже достиг предела, добавление домена завершится ошибкой на этапе настройки, а не во время работы.

Заранее предусмотрите такие сбои: релиз фронтенда, из которого пропало поле с токеном; релиз бэкенда, переставший вызывать siteverify; изменение политики безопасности контента, которое блокирует скрипт виджета; список имён хостов виджета, в котором нет нового домена или который достиг задокументированного предела.

Известные особенности

• Виджет без серверной проверки не защищает ни от чего. Это самая частая ошибка интеграции, и по интерфейсу её не видно: форма по-прежнему отображается и отправляется.
• Проверка только success игнорирует привязку к имени хоста и действию, поэтому токен, полученный на одной форме или на одном сайте, можно повторно использовать на другом в течение срока его действия.
• Токен действует 300 секунд и используется один раз, если не передан ключ идемпотентности. Длинные формы и логика повторных попыток должны учитывать оба ограничения.
• В режиме Managed возможно одно взаимодействие, например установка флажка. Задач с картинками или текстом здесь нет, но утверждать, что взаимодействия не будет никогда, неверно.
• Клиенты, которые не выполняют JavaScript, токен получить не могут. Это затрагивает инструменты доступности, часть встроенных браузеров и легитимную автоматизацию.
• Turnstile защищает те эндпоинты, где он развёрнут. Это только один уровень защиты: эндпоинты без виджета остаются незащищёнными.
• Pre-clearance требует, чтобы сайт работал через проксирование Cloudflare, и на сайты, размещённые в другом месте, не распространяется.
• Число виджетов и имён хостов ограничено: 20 виджетов на аккаунт и 10 имён хостов на виджет на стандартном тарифе. Если домены добавляются со временем, лимит на имена хостов будет достигнут раньше любого другого задокументированного ограничения.

Взаимодействие с другими продуктами

В проксируемой зоне pre-clearance от Turnstile учитывают и пользовательские правила WAF, и правила Bot Management. Поэтому посетитель, прошедший проверку один раз, в течение срока действия clearance повторную проверку не получает.

Turnstile сочетается с правилами ограничения частоты запросов, которые ограничивают число обращений к эндпоинту независимо от результата проверки, и с правилами для ботов, которые срабатывают по результатам классификации. Все три механизма отвечают за разные свойства трафика и обычно применяются вместе.

Для вызова siteverify достаточно обычного HTTPS-запроса, поэтому его можно выполнить из любого бэкенда, в том числе из Cloudflare Worker перед origin-сервером. Тогда валидация происходит на границе сети, а не в приложении.

Ephemeral ID, которые возвращает siteverify, можно сопоставлять с признаками злоупотреблений на стороне приложения, не сохраняя при этом ни адрес, ни постоянный идентификатор.

Turnstile не зависит от настроек DNS и зоны, поэтому его можно развернуть на сайте с любым хостингом, а позже, если сайт переедет, дополнить проксированием Cloudflare.

Часто задаваемые вопросы

Обязателен ли вызов на стороне сервера? Да. Без вызова siteverify токен остаётся непроверенными данными от клиента, и виджет не даёт никакой защиты.

Сколько действует токен и можно ли проверить его дважды? Cloudflare указывает срок действия 300 секунд и одну проверку на токен. Передавайте idempotency_key при повторной попытке проверки того же токена.

Обязательно ли сайт должен работать через Cloudflare? Нет. Виджет и siteverify работают на любом сайте. Проксирование через Cloudflare нужно только для pre-clearance.

Как заменить интеграцию с reCAPTCHA? На стороне клиента виджет поддерживает неявную и явную отрисовку, а на сервере меняются адрес проверки и секретный ключ. Обе стороны нужно менять вместе, а прежние ключи удалять только после того, как новый путь проверен.

Источники

• https://developers.cloudflare.com/turnstile/, дата обращения 2026-08-28.
• https://developers.cloudflare.com/turnstile/plans/, дата обращения 2026-08-31.
• https://developers.cloudflare.com/turnstile/concepts/widget/, дата обращения 2026-08-28.
• https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/, дата обращения 2026-08-28.
• https://developers.cloudflare.com/turnstile/get-started/server-side-validation/, дата обращения 2026-08-28.
• https://developers.cloudflare.com/turnstile/concepts/pre-clearance-support/, дата обращения 2026-08-28.
• https://developers.cloudflare.com/turnstile/concepts/ephemeral-id/, дата обращения 2026-08-28.
• https://developers.cloudflare.com/turnstile/troubleshooting/testing/, дата обращения 2026-08-28.

Снимок содержимого: 2026-08-28. Ограничения перепроверены 2026-08-31.

История изменений