← Cloudflare Turnstile / turnstile / tutorials

Интеграция Turnstile, WAF и Bot Management

Это руководство покажет, как интегрировать Cloudflare Turnstile, Web Application Firewall (WAF), а также Bot Management в существующую систему аутентификации. Такое сочетание надёжно защищает от разных угроз, включая автоматизированные атаки и вредоносные попытки входа.

Для работы WAF и Bot Management DNS вашего сайта должен проходить через Cloudflare. При этом Turnstile можно использовать отдельно на любом сайте, в том числе вне сети Cloudflare. В руководстве описаны все три продукта, но если ваш сайт не в сети Cloudflare, ограничьтесь разделом про Turnstile.

WAF, Bot Management и Turnstile хорошо дополняют друг друга, потому что работают на разных уровнях приложения:

• WAF фильтрует вредоносный трафик по сетевым сигналам.
• Bot Management анализирует запросы, чтобы выявлять автоматизированные угрозы и снижать их влияние.
• Turnstile анализирует сигналы клиентской стороны и браузера, чтобы отличить людей от ботов.

Сочетая серверные меры защиты (WAF и Bot Management) с клиентскими (Turnstile), вы выстраиваете несколько рубежей обороны, которые злоумышленнику трудно обойти.

• Вам потребуется учётная запись Cloudflare с доступом к WAF и Bot Management (если он используется).
• Существующий маршрут на JavaScript или TypeScript, который обрабатывает аутентификацию.

В этом руководстве используется простая форма входа на чистом HTML, чтобы показать интеграцию Turnstile в приложение. На бэкенде запрос на вход обрабатывает заглушка маршрута аутентификации на TypeScript. Вы можете заменить её на любой другой язык. Достаточно, чтобы ваш язык или фреймворк умел отправлять внешний HTTP-запрос к API Turnstile, вы можете интегрировать Turnstile в своё приложение.

Если ваш сайт работает в сети Cloudflare и подключён к плану Enterprise, необходимо настроить WAF и Bot Management.

При такой настройке запросы с низким bot score получают проверку: сетевые сигналы помогают выявить возможные угрозы до того, как запрос дойдёт до приложения. Порог оценки можно изменить под свою задачу.

Turnstile можно использовать на любом сайте независимо от того, находится ли он в сети Cloudflare:

Turnstile добавляет дополнительный уровень защиты: он анализирует сигналы браузера и клиентской стороны и дополняет серверные проверки, которые выполняют WAF и Bot Management.

Если ваш сайт работает в Cloudflare, вы можете включить параметр, который позволяет использовать уже существующий cookie-файл clearance в настройках Turnstile. Благодаря этой интеграции Turnstile учитывает cookie clearance, когда решает, показывать ли пользователю проверку. Интеграция необязательна, но рекомендуется, если вы уже используете WAF и Bot Management.

Интеграция Turnstile в приложение состоит из двух частей: виджета Turnstile и серверной логики валидации.

Добавьте виджет Turnstile в существующую форму входа:

<form id="login-form">
	<input type="text" id="username" placeholder="Username" required />
	<input type="password" id="password" placeholder="Password" autocomplete="off" required />
	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>
	<button type="submit">Log in</button>
</form>

<script
	src="https://challenges.cloudflare.com/turnstile/v0/api.js"
	async
	defer
></script>

Замените <YOUR-SITE-KEY> на ваш настоящий site key Turnstile.

В существующий маршрут аутентификации добавьте проверку Turnstile:

async function validateTurnstileToken(
	ip: string,
	token: string,
	secret: string,
): Promise<boolean> {
	const response = await fetch(
		"https://challenges.cloudflare.com/turnstile/v0/siteverify",
		{
			method: "POST",
			headers: { "Content-Type": "application/json" },
			body: JSON.stringify({ ip, secret, response: token }),
		},
	);

	const outcome = await response.json();
	return outcome.success;
}

// Assume that this is a TypeScript route handler.
// You may replace this with a different implementation,
// based on your language or framework
export async function onRequestPost(context) {
	const { request, env } = context;
	const { username, password, token } = await request.json();

	// Validate Turnstile token
	const secretKey = env.TURNSTILE_SECRET_KEY;
	const ip = request.headers.get("CF-Connecting-IP");
	const turnstileValid = await validateTurnstileToken(ip, token, secretKey);
	if (!turnstileValid) {
		// Return back to the login page with an error message
		return Response.redirect("/login", 302, {
			headers: {
				Location: "/login?error=invalid-turnstile-token",
			},
		});
	}

	// Perform your existing authentication logic here
	const isValidLogin = await checkCredentials(username, password);

	if (isValidLogin) {
		return new Response(JSON.stringify({ message: "Login successful" }), {
			status: 200,
			headers: { "Content-Type": "application/json" },
		});
	} else {
		return new Response(JSON.stringify({ error: "Invalid credentials" }), {
			status: 401,
			headers: { "Content-Type": "application/json" },
		});
	}
}

async function checkCredentials(
	username: string,
	password: string,
): Promise<boolean> {
	// Your existing credential checking logic
}

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

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

1. Добавьте правило WAF, которое всегда направляет ваш IP-адрес на страницу проверки.
2. Добавьте правило WAF, которое проверяет наличие параметра запроса, например ?challenge=true.

1. Всегда проверяйте токен Turnstile на сервере, прежде чем сверять учётные данные.
2. Храните конфиденциальные данные, например секретный ключ Turnstile, в переменных окружения.
3. Реализуйте корректную обработку ошибок и логирование, чтобы отслеживать возможные проблемы с безопасностью.

Связка Turnstile с WAF и Bot Management защищает приложение на сетевом уровне и добавляет ещё один рубеж, построенный на клиентских сигналах. При такой схеме автоматизировать атаку на вашу систему входа заметно сложнее.

Если вы хотите настроить Turnstile под себя, обратитесь к материалам ниже:

• Рендеринг на стороне клиента. Узнайте, как настроить способ и момент отрисовки Turnstile в интерфейсе, чтобы виджет лучше соответствовал задачам приложения и удобству пользователей.
• Проверка на стороне сервера. Узнайте, как работает API Turnstile, какие параметры принимает запрос и как обрабатывать разные типы ответов, включая коды ошибок.
• Turnstile Analytics. Узнайте, как просматривать аналитику Turnstile в Cloudflare dashboard. Она включает метрики по количеству выданных проверок, а также доля решённых проверок (CSR).