跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

验证 token

最后更新 查看 MarkdownAgent 设置

了解如何使用 Siteverify API 在服务器上安全地验证 Turnstile token。

流程

  1. 客户端生成 token:访问者在你的网页上完成 Turnstile 验证挑战。
  2. 将 token 发送到服务器:表单提交中包含 Turnstile token。
  3. 服务器验证 token:你的服务器调用 Cloudflare 的 Siteverify API。
  4. Cloudflare 返回响应:返回 success 或 failure 以及其他数据。
  5. 服务器执行操作:根据验证结果允许或拒绝原始请求。

Siteverify API 概览

Endpointshell
POST https://challenges.cloudflare.com/turnstile/v0/siteverify

请求格式

API 接受 application/x-www-form-urlencoded 和 application/json 请求,但始终返回 JSON 响应。

必需参数

参数 必需 说明
secret 是 Cloudflare 仪表板中小组件的密钥
response 是 客户端小组件生成的 token
remoteip 否 访问者的 IP 地址
idempotency_key 否 你生成的 UUID,用于安全地重试验证请求

Token 特征

  • 最大长度:2048 个字符
  • 有效期:自生成起 300 秒(5 分钟)
  • 单次使用:每个 token 只能验证一次
  • 自动过期:token 会自动过期,且无法重复使用

Turnstile 签发的验证 token 有效期为五分钟。如果用户在此时间之后提交表单,该 token 将被视为已过期。在这种情况下,服务器端验证 API 会返回失败,响应中的 error-codes 字段将包含 timeout-or-duplicate。

为确保验证成功,访问者必须在五分钟有效期内发起请求,并将 token 提交到你的后端。否则,需要刷新 Turnstile 小组件以生成新的 token。可以使用 turnstile.reset 函数执行此操作。


基本验证示例

JSON

const SECRET_KEY = "your-secret-key";

async function validateTurnstile(token, remoteip) {
    try {
        const response = await fetch(
            "https://challenges.cloudflare.com/turnstile/v0/siteverify",
            {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                },
                body: JSON.stringify({
                    secret: SECRET_KEY,
                    response: token,
                    remoteip: remoteip,
                }),
            },
        );

        const result = await response.json();
        return result;
    } catch (error) {
        console.error("Turnstile validation error:", error);
        return { success: false, "error-codes": ["internal-error"] };
    }
}

表单数据

const SECRET_KEY = "your-secret-key";

async function validateTurnstile(token, remoteip) {
    const formData = new FormData();
    formData.append("secret", SECRET_KEY);
    formData.append("response", token);
    formData.append("remoteip", remoteip);

    try {
        const response = await fetch(
            "https://challenges.cloudflare.com/turnstile/v0/siteverify",
            {
                method: "POST",
                body: formData,
            },
        );

        const result = await response.json();
        return result;
    } catch (error) {
        console.error("Turnstile validation error:", error);
        return { success: false, "error-codes": ["internal-error"] };
    }
}

// Usage in form handler
async function handleFormSubmission(request) {
    const body = await request.formData();
    const token = body.get("cf-turnstile-response");
    const ip =
        request.headers.get("CF-Connecting-IP") ||
        request.headers.get("X-Forwarded-For") ||
        "unknown";

    const validation = await validateTurnstile(token, ip);

    if (validation.success) {
        // Token is valid - process the form
        console.log("Valid submission from:", validation.hostname);
        return processForm(body);
    } else {
        // Token is invalid - reject the submission
        console.log("Invalid token:", validation["error-codes"]);
        return new Response("Invalid verification", { status: 400 });
    }
}
<?php
function validateTurnstile($token, $secret, $remoteip = null) {
    $url = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';

    $data = [
        'secret' => $secret,
        'response' => $token
    ];

    if ($remoteip) {
        $data['remoteip'] = $remoteip;
    }

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($data),
        CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 10,
    ]);

    $response = curl_exec($ch);
    $error = curl_error($ch);
    curl_close($ch);

    if ($response === false || $error !== '') {
        return ['success' => false, 'error-codes' => ['internal-error']];
    }

    return json_decode($response, true);

}

// Usage
$secret_key = 'your-secret-key';
$token = $_POST['cf-turnstile-response'] ?? '';
$remoteip = $_SERVER['HTTP_CF_CONNECTING_IP'] ??
$_SERVER['HTTP_X_FORWARDED_FOR'] ??
$_SERVER['REMOTE_ADDR'];

$validation = validateTurnstile($token, $secret_key, $remoteip);

if ($validation['success']) {
// Valid token - process form
echo "Form submission successful!";
// Process your form data here
} else {
// Invalid token - show error
echo "Verification failed. Please try again.";
error_log('Turnstile validation failed: ' . implode(', ', $validation['error-codes']));
}
?>
import requests

def validate_turnstile(token, secret, remoteip=None):
    url = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'

    data = {
        'secret': secret,
        'response': token
    }

    if remoteip:
        data['remoteip'] = remoteip

    try:
        response = requests.post(url, data=data, timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.RequestException as e:
        print(f"Turnstile validation error: {e}")
        return {'success': False, 'error-codes': ['internal-error']}

# Usage with Flask
from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET_KEY = 'your-secret-key'

@app.route('/submit-form', methods=['POST'])
def submit_form():
    token = request.form.get('cf-turnstile-response')
    remoteip = request.headers.get('CF-Connecting-IP') or \
               request.headers.get('X-Forwarded-For') or \
               request.remote_addr

    validation = validate_turnstile(token, SECRET_KEY, remoteip)

    if validation['success']:
        # Valid token - process form
        return jsonify({'status': 'success', 'message': 'Form submitted successfully'})
    else:
        # Invalid token - reject submission
        return jsonify({
            'status': 'error',
            'message': 'Verification failed',
            'errors': validation['error-codes']
        }), 400
import org.springframework.web.client.RestTemplate;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;

@Service
public class TurnstileService {
private static final String SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
private final String secretKey = "your-secret-key";
private final RestTemplate restTemplate = new RestTemplate();

    public TurnstileResponse validateToken(String token, String remoteip) {
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);

        MultiValueMap<String, String> params = new LinkedMultiValueMap<>();
        params.add("secret", secretKey);
        params.add("response", token);
        if (remoteip != null) {
            params.add("remoteip", remoteip);
        }

        HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(params, headers);

        try {
            ResponseEntity<TurnstileResponse> response = restTemplate.postForEntity(
                SITEVERIFY_URL, request, TurnstileResponse.class);
            return response.getBody();
        } catch (Exception e) {
            TurnstileResponse errorResponse = new TurnstileResponse();
            errorResponse.setSuccess(false);
            errorResponse.setErrorCodes(List.of("internal-error"));
            return errorResponse;
        }
    }

}

// Controller usage
@PostMapping("/submit-form")
public ResponseEntity<?> submitForm(
@RequestParam("cf-turnstile-response") String token,
HttpServletRequest request) {

    String remoteip = request.getHeader("CF-Connecting-IP");
    if (remoteip == null) {
        remoteip = request.getHeader("X-Forwarded-For");
    }
    if (remoteip == null) {
        remoteip = request.getRemoteAddr();
    }

    TurnstileResponse validation = turnstileService.validateToken(token, remoteip);

    if (validation.isSuccess()) {
        // Valid token - process form
        return ResponseEntity.ok("Form submitted successfully");
    } else {
        // Invalid token - reject submission
        return ResponseEntity.badRequest()
            .body("Verification failed: " + validation.getErrorCodes());
    }

}
using System.Text.Json;

public class TurnstileService
{
    private readonly HttpClient _httpClient;
    private readonly string _secretKey = "your-secret-key";
    private const string SiteverifyUrl = "https://challenges.cloudflare.com/turnstile/v0/siteverify";

    public TurnstileService(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task<TurnstileResponse> ValidateTokenAsync(string token, string remoteip = null)
    {
        var parameters = new Dictionary<string, string>
        {
            { "secret", _secretKey },
            { "response", token }
        };

        if (!string.IsNullOrEmpty(remoteip))
        {
            parameters.Add("remoteip", remoteip);
        }

        var postContent = new FormUrlEncodedContent(parameters);

        try
        {
            var response = await _httpClient.PostAsync(SiteverifyUrl, postContent);
            var stringContent = await response.Content.ReadAsStringAsync();

            return JsonSerializer.Deserialize<TurnstileResponse>(stringContent);
        }
        catch (Exception ex)
        {
            return new TurnstileResponse
            {
                Success = false,
                ErrorCodes = new[] { "internal-error" }
            };
        }
    }
}

// Controller usage
[HttpPost("submit-form")]
public async Task<IActionResult> SubmitForm([FromForm] string cfTurnstileResponse)
{
    var remoteip = HttpContext.Request.Headers["CF-Connecting-IP"].FirstOrDefault() ??
                   HttpContext.Request.Headers["X-Forwarded-For"].FirstOrDefault() ??
                   HttpContext.Connection.RemoteIpAddress?.ToString();

    var validation = await _turnstileService.ValidateTokenAsync(cfTurnstileResponse, remoteip);

    if (validation.Success)
    {
        // Valid token - process form
        return Ok("Form submitted successfully");
    }
    else
    {
        // Invalid token - reject submission
        return BadRequest($"Verification failed: {string.Join(", ", validation.ErrorCodes)}");
    }
}

高级验证技术

Idempotency keys for retry operationjs
const crypto = require("crypto");

async function validateWithRetry(token, remoteip, maxRetries = 3) {
    const idempotencyKey = crypto.randomUUID();

    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            const formData = new FormData();
            formData.append("secret", SECRET_KEY);
            formData.append("response", token);
            formData.append("remoteip", remoteip);
            formData.append("idempotency_key", idempotencyKey);

            const response = await fetch(
                "https://challenges.cloudflare.com/turnstile/v0/siteverify",
                {
                    method: "POST",
                    body: formData,
                },
            );

            const result = await response.json();

            if (response.ok) {
                return result;
            }

            // If this is the last attempt, return the error
            if (attempt === maxRetries) {
                return result;
            }

            // Wait before retrying (exponential backoff)
            await new Promise((resolve) =>
                setTimeout(resolve, Math.pow(2, attempt) * 1000),
            );
        } catch (error) {
            if (attempt === maxRetries) {
                return { success: false, "error-codes": ["internal-error"] };
            }
        }
    }
}
Enhanced validation with custom checksjs
async function validateTurnstileEnhanced(
    token,
    remoteip,
    expectedAction = null,
    expectedHostname = null,
) {
    const validation = await validateTurnstile(token, remoteip);

    if (!validation.success) {
        return {
            valid: false,
            reason: "turnstile_failed",
            errors: validation["error-codes"],
        };
    }

    // Check if action matches expected value (if specified)
    if (expectedAction && validation.action !== expectedAction) {
        return {
            valid: false,
            reason: "action_mismatch",
            expected: expectedAction,
            received: validation.action,
        };
    }

    // Check if hostname matches expected value (if specified)
    if (expectedHostname && validation.hostname !== expectedHostname) {
        return {
            valid: false,
            reason: "hostname_mismatch",
            expected: expectedHostname,
            received: validation.hostname,
        };
    }

    // Check token age (warn if older than 4 minutes)
    const challengeTime = new Date(validation.challenge_ts);
    const now = new Date();
    const ageMinutes = (now - challengeTime) / (1000 * 60);

    if (ageMinutes > 4) {
        console.warn(`Token is ${ageMinutes.toFixed(1)} minutes old`);
    }

    return {
        valid: true,
        data: validation,
        tokenAge: ageMinutes,
    };
}

// Usage
const result = await validateTurnstileEnhanced(
    token,
    remoteip,
    "login", // expected action
    "example.com", // expected hostname
);

if (result.valid) {
    // Process the request
    console.log("Validation successful:", result.data);
} else {
    // Handle validation failure
    console.log("Validation failed:", result.reason);
}

API 响应格式

Examplejson
{
  "success": true,
  "challenge_ts": "2022-02-28T15:14:30.096Z",
  "hostname": "example.com",
  "error-codes": [],
  "action": "login",
  "cdata": "sessionid-123456789",
  "metadata": {
    "ephemeral_id": "x:9f78e0ed210960d7693b167e"
  }
}
Examplejson
{
  "success": false,
  "error-codes": ["invalid-input-response"]
}

响应字段

字段 说明
success 指示验证是否成功的布尔值
challenge_ts 完成验证挑战时的 ISO 8601 时间戳
hostname 提供验证挑战的主机名
error-codes 错误代码数组(验证失败时)
action 来自客户端的自定义操作标识符
cdata 来自客户端的自定义数据负载
metadata.ephemeral_id 设备指纹 ID(仅限 Enterprise)

错误代码参考

错误代码 说明 所需操作
missing-input-secret 未提供 secret 参数 确保包含 secret key
invalid-input-secret Secret key 无效或已过期 在 Cloudflare 仪表板中检查你的 secret key
missing-input-response 未提供 response 参数 确保包含 token
invalid-input-response Token 无效、格式错误或已过期 用户应重试验证挑战
bad-request 请求格式错误 检查请求格式和参数
timeout-or-duplicate Token 已验证过 每个 token 只能使用一次
internal-error 发生内部错误 重试该请求

实施

Example implementationjs
class TurnstileValidator {
    constructor(secretKey, timeout = 10000) {
        this.secretKey = secretKey;
        this.timeout = timeout;
    }

    async validate(token, remoteip, options = {}) {
        // Input validation
        if (!token || typeof token !== "string") {
            return { success: false, error: "Invalid token format" };
        }

        if (token.length > 2048) {
            return { success: false, error: "Token too long" };
        }

        // Prepare request
        const controller = new AbortController();
        const timeoutId = setTimeout(() => controller.abort(), this.timeout);

        try {
            const formData = new FormData();
            formData.append("secret", this.secretKey);
            formData.append("response", token);

            if (remoteip) {
                formData.append("remoteip", remoteip);
            }

            if (options.idempotencyKey) {
                formData.append("idempotency_key", options.idempotencyKey);
            }

            const response = await fetch(
                "https://challenges.cloudflare.com/turnstile/v0/siteverify",
                {
                    method: "POST",
                    body: formData,
                    signal: controller.signal,
                },
            );

            const result = await response.json();

            // Additional validation
            if (result.success) {
                if (
                    options.expectedAction &&
                    result.action !== options.expectedAction
                ) {
                    return {
                        success: false,
                        error: "Action mismatch",
                        expected: options.expectedAction,
                        received: result.action,
                    };
                }

                if (
                    options.expectedHostname &&
                    result.hostname !== options.expectedHostname
                ) {
                    return {
                        success: false,
                        error: "Hostname mismatch",
                        expected: options.expectedHostname,
                        received: result.hostname,
                    };
                }
            }

            return result;
        } catch (error) {
            if (error.name === "AbortError") {
                return { success: false, error: "Validation timeout" };
            }

            console.error("Turnstile validation error:", error);
            return { success: false, error: "Internal error" };
        } finally {
            clearTimeout(timeoutId);
        }
    }
}

// Usage
const validator = new TurnstileValidator(process.env.TURNSTILE_SECRET_KEY);

const result = await validator.validate(token, remoteip, {
    expectedAction: "login",
    expectedHostname: "example.com",
});

if (result.success) {
    // Process the request
} else {
    // Handle failure
    console.log("Validation failed:", result.error);
}

测试

您可以使用测试密钥通过 Siteverify API 来测试使用测试站点密钥(sitekey)生成的虚拟令牌。您的生产环境密钥将拒绝虚拟令牌。

有关更多信息,请参阅测试。


最佳实践

安全

  • 安全地存储 secret key。使用环境变量或安全的密钥管理方式。
  • 每次请求都要验证 token。切勿仅信任客户端验证。
  • 检查其他字段。在指定操作和主机名时,也要验证它们。
  • 监控滥用行为,并记录验证失败和异常模式。
  • 使用 HTTPS。始终通过安全连接进行验证。
  • 仅在后端环境中调用 Siteverify API。如果你在前端客户端代码中暴露 secret key 来调用 Siteverify,攻击者就能绕过安全检查。请确保客户端代码将验证 token 发送到后端,并且只有后端会调用 Siteverify API。

性能

  • 设置合理的超时时间。不要无限期等待 Siteverify 响应。
  • 实现重试逻辑并处理暂时性网络问题。
  • 如果你的流程需要,可缓存同一 token 的验证结果。
  • 监控 API 延迟,并跟踪 Siteverify 响应时间。

错误处理

  • 为 API 故障设置回退行为。
  • 使用对用户友好的提示。不要向用户暴露内部错误详情。
  • 正确记录错误以便调试,同时避免暴露密钥。
  • 实施速率限制,以防验证请求泛滥。

这篇文档对您有帮助吗?