集成 Turnstile、WAF 和 Bot Management

本教程将指导您如何将 Cloudflare Turnstile、Web 应用程序防火墙 (WAF) 和 Bot Management 集成到现有的身份验证系统中。这种组合可对各种威胁（包括自动化攻击和恶意登录尝试）建立起强大的防御。

要使用 WAF 和 Bot Management，您站点的 DNS 必须指向并经过 Cloudflare。然而，Turnstile 可以独立使用在任何站点上，包括那些不在 Cloudflare 网络上的站点。本教程将涵盖如何实施这三种产品，但如果您的站点不在 Cloudflare 网络上，您可以只关注 Turnstile。

WAF、Bot Management 和 Turnstile 通过在应用程序的不同层级运行，来很好地协同工作：

• WAF 基于网络信号过滤恶意流量。
• Bot Management 分析请求以识别并缓解自动化威胁。
• Turnstile 检查客户端和浏览器信号，以区分人类用户和 bot。

通过结合服务器端（WAF 和 Bot Management）和客户端（Turnstile）安全措施，您可以结合多层防御来创建一个攻击者难以绕过的保护系统。

• 您必须拥有一个可以访问 WAF 和 Bot Management（如果使用）的 Cloudflare 账户。
• 现有基于 JavaScript/TypeScript 的处理身份验证的路由。

本教程使用一个以纯 HTML 编写的简单登录表单，来演示如何将 Turnstile 集成到您的应用程序中。在后端，一个以 TypeScript 编写的存根 (stubbed out) 身份验证路由将处理登录请求。您可以使用您选择的语言替换它。只要您的语言或框架能够向 Turnstile API 发起外部 HTTP 请求，您就可以将 Turnstile 集成到您的应用程序中。

如果您的网站在 Cloudflare 网络上并订阅了企业版 (Enterprise) 套餐，您必须配置 WAF 和 Bot Management。

此配置对 bot 分数较低的请求发起质询，利用网络信号在潜在威胁到达您的应用程序之前进行识别。您可以根据您的具体用例自定义分数阈值。

Turnstile 可以在任何网站上使用，无论它是否在 Cloudflare 的网络上：

Turnstile 通过分析浏览器和客户端信号来添加额外的安全层，补充了 WAF 和 Bot Management 执行的服务器端检查。

如果您的网站在 Cloudflare 上，您可以在 Turnstile 的设置中启用使用现有 clearance cookie 的选项。此集成允许 Turnstile 使用 clearance cookie 作为其判断用户是否应接受质询的一部分。此集成是可选的，但如果您已经在使用 WAF 和 Bot Management，则推荐使用。

在应用程序中实施 Turnstile 包含两个部分：Turnstile 小组件和服务器端验证逻辑。

将 Turnstile 小组件添加到您现有的登录表单中：

<form id="login-form">
	<input type="text" id="username" placeholder="用户名" required />
	<input type="password" id="password" placeholder="密码" autocomplete="off" required />
	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>
	<button type="submit">登录</button>
</form>

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

将 <YOUR-SITE-KEY> 替换为您的实际 Turnstile site key。

在您现有的身份验证路由中，添加 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;
}

// 假设这是一个 TypeScript 路由处理程序。
// 您可以根据您的语言或框架
// 将其替换为不同的实现
export async function onRequestPost(context) {
	const { request, env } = context;
	const { username, password, token } = await request.json();

	// 验证 Turnstile 令牌
	const secretKey = env.TURNSTILE_SECRET_KEY;
	const ip = request.headers.get("CF-Connecting-IP");
	const turnstileValid = await validateTurnstileToken(ip, token, secretKey);
	if (!turnstileValid) {
		// 返回登录页面并显示错误消息
		return Response.redirect("/login", 302, {
			headers: {
				Location: "/login?error=invalid-turnstile-token",
			},
		});
	}

	// 在此处执行您现有的身份验证逻辑
	const isValidLogin = await checkCredentials(username, password);

	if (isValidLogin) {
		return new Response(JSON.stringify({ message: "登录成功" }), {
			status: 200,
			headers: { "Content-Type": "application/json" },
		});
	} else {
		return new Response(JSON.stringify({ error: "凭据无效" }), {
			status: 401,
			headers: { "Content-Type": "application/json" },
		});
	}
}

async function checkCredentials(
	username: string,
	password: string,
): Promise<boolean> {
	// 您现有的凭证检查逻辑
}

此设置可确保在继续登录过程之前，在服务器端验证 Turnstile 令牌，从而基于客户端信号添加了额外的安全层。

部署后，您需要测试您的集成。因为您的 bot 分数可能很低，所以您可能不会收到质询。但是，您可以根据需要添加额外规则以强制重定向到质询页面。执行此操作的一些选项有：

1. 添加一条 WAF 规则，始终将您的 IP 地址转发到质询页面。
2. 添加一条 WAF 规则，检查是否存在查询参数，例如 ?challenge=true。

1. 在检查凭证之前，始终先在服务器端验证 Turnstile 令牌。
2. 使用环境变量来存储敏感信息，例如您的 Turnstile 密匙。
3. 实施妥善的错误处理和日志记录，以监控潜在的安全问题。

通过将 Turnstile 与 WAF 和 Bot Management 结合使用，您可以在网络层保护您的应用程序，同时还可以使用客户端信号提供额外的保护层。这种方法使得恶意行为者极难对您的登录系统进行自动化攻击。

如果您有兴趣自定义 Turnstile，请参阅以下资源以获取更多信息：

• 客户端渲染。了解如何自定义 Turnstile 在用户界面中的渲染方式和时机，以更好地满足您应用程序的需求和用户体验。
• 服务器端验证。了解 Turnstile 的 API 的工作原理（包括请求参数），以及如何处理不同类型的响应（包括错误代码）。
• Turnstile 分析 (Turnstile Analytics)。了解如何在 Cloudflare 仪表板中查看 Turnstile 的分析。这包括有关发出的质询数量以及质询解决率 (CSR) 的指标。