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

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 и устаревшие маршруты, остаются без изменений.
• Виджету нужен 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 вместе с rate limiting rules, а при наличии лицензии и с bot rules.
8. Удаляйте прежнюю интеграцию CAPTCHA и её ключи только после того, как новый сценарий проверен.

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

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

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

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

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

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

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

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

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

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

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

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

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

Совместимость

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

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

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

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.

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