← Cloudflare Turnstile / turnstile / tutorials

Integrace Turnstile, WAF a Bot Management

Tento návod vás provede integrací Cloudflare Turnstile, Web Application Firewall (WAF), a Bot Management do stávajícího systému ověřování. Tato kombinace vytvoří spolehlivou obranu proti různým hrozbám včetně automatizovaných útoků a pokusů o zneužití přihlášení.

Aby šlo využít WAF a Bot Management, musí mít váš web DNS směrované přes Cloudflare. Turnstile ale funguje samostatně na jakémkoli webu, tedy i mimo síť Cloudflare. Tento návod popisuje nasazení všech tří produktů, pokud však váš web v síti Cloudflare není, můžete se soustředit jen na Turnstile.

WAF, Bot Management a Turnstile se dobře doplňují, protože každý působí na jiné vrstvě aplikace:

• WAF filtruje škodlivý provoz podle síťových signálů.
• Bot Management analyzuje požadavky, aby odhalil automatizované hrozby a zmírnil jejich dopad.
• Turnstile zkoumá signály z klientské strany a z prohlížeče, aby odlišil lidské uživatele od botů.

Spojením serverových opatření (WAF a Bot Management) s opatřeními na straně klienta (Turnstile) postavíte vícevrstvou obranu, kterou útočníci obcházejí jen velmi obtížně.

• Potřebujete účet Cloudflare s přístupem k WAF a Bot Management (pokud je používáte).
• Existující route v JavaScriptu nebo TypeScriptu, která obsluhuje autentizaci.

Tento návod používá jednoduchý přihlašovací formulář v čistém HTML, aby ukázal, jak Turnstile začlenit do aplikace. Na backendu zpracuje požadavek na přihlášení zjednodušená autentizační routa napsaná v TypeScriptu. Klidně ji nahraďte jazykem, který používáte. Stačí, aby váš jazyk nebo framework dokázal odeslat externí požadavek HTTP na API služby Turnstile, můžete Turnstile začlenit do své aplikace.

Pokud je váš web v síti Cloudflare a máte tarif Enterprise, musíte nastavit WAF a Bot Management.

Tato konfigurace zobrazí výzvu požadavkům s nízkým bot score a využívá síťové signály k odhalení možných hrozeb dříve, než dorazí k vaší aplikaci. Prahovou hodnotu skóre si můžete upravit podle svého případu použití.

Turnstile můžete použít na libovolném webu bez ohledu na to, zda běží v síti Cloudflare:

Turnstile přidává další vrstvu zabezpečení: analyzuje signály z prohlížeče a z klientské strany a doplňuje tak serverové kontroly, které provádí WAF a Bot Management.

Pokud je váš web na Cloudflare, můžete zapnout možnost použít stávající clearance cookie v nastavení Turnstile. Díky této integraci může Turnstile využít clearance cookie při rozhodování, zda má návštěvník dostat výzvu. Integrace je volitelná, doporučujeme ji ale všem, kdo už používají WAF a Bot Management.

Implementace Turnstile v aplikaci má dvě části: widget Turnstile a ověřovací logiku na straně serveru.

Přidejte widget Turnstile do stávajícího přihlašovacího formuláře:

<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>

Nahraďte <YOUR-SITE-KEY> svým skutečným Turnstile site key.

Do stávající autentizační trasy přidejte ověření 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
}

Toto nastavení zajistí, že se token Turnstile ověří na straně serveru ještě před samotným přihlášením, a přidá tak další vrstvu zabezpečení založenou na signálech z klienta.

Po nasazení budete chtít integraci otestovat. Protože vaše bot score bude nízké, výzva se vám pravděpodobně nezobrazí. V případě potřeby ale můžete přidat další pravidla, která přesměrování na stránku s výzvou vynutí. Nabízejí se například tyto možnosti:

1. Přidejte pravidlo WAF, které vaši IP adresu vždy nasměruje na stránku s výzvou.
2. Přidejte pravidlo WAF, které kontroluje přítomnost parametru dotazu, například ?challenge=true.

1. Token Turnstile vždy ověřte na serveru dříve, než začnete kontrolovat přihlašovací údaje.
2. Citlivé údaje, jako je tajný klíč Turnstile, ukládejte do proměnných prostředí.
3. Zaveďte řádné ošetření chyb a logování, abyste odhalili možné bezpečnostní problémy.

Kombinací nástrojů Turnstile, WAF a Bot Management vytvoříte systém, který chrání aplikaci na síťové vrstvě a zároveň přidává další vrstvu ochrany založenou na signálech z klienta. Útočníkům to výrazně ztíží automatizaci útoků na vaše přihlašování.

Chcete-li Turnstile přizpůsobit, více informací najdete v následujících zdrojích:

• Vykreslování na straně klienta. Zjistěte, jak přizpůsobit způsob a okamžik vykreslení Turnstile ve vašem uživatelském rozhraní tak, aby lépe odpovídalo potřebám aplikace i zkušenosti uživatelů.
• Ověřování na straně serveru. Zjistěte, jak funguje API Turnstile včetně parametrů požadavku a jak zpracovat různé typy odpovědí včetně chybových kódů.
• Turnstile Analytics. Zjistěte, jak si v Cloudflare dashboardu zobrazit analytiku Turnstile. Součástí jsou metriky o počtu vydaných výzev i míra vyřešení challenge (CSR).