如何正确验证 Telegram Bot Web App 用户数据-php教程-PHP中文网

如何正确验证 Telegram Bot Web App 用户数据

本文详解 Telegram Web App 用户身份验证的完整实现流程，重点解决因换行符、二进制哈希处理不当导致的 hash 校验失败问题，并提供可直接运行的 PHP 完整示例代码。

本文详解 telegram web app 用户身份验证的完整实现流程，重点解决因换行符、二进制哈希处理不当导致的 `hash` 校验失败问题，并提供可直接运行的 php 完整示例代码。

Telegram Bot 的 Web App 在启动时会通过 tgWebAppData 向后端传递用户授权数据（如 user, auth_date, hash 等），但该数据必须严格验证，否则存在伪造风险。官方文档要求：将除 hash 外的所有键值对按字典序排序、以 Unix 换行符连接成字符串，再用基于 Bot Token 生成的密钥进行 HMAC-SHA256 签名比对。

常见错误包括：

使用 urldecode() 而非 rawurldecode() —— 导致 + 被误转为空格；
用 implode('\n', ...)（双斜杠）拼接，实际应为 " "（单斜杠，表示真实换行）；
hash_hmac() 默认返回十六进制字符串，但密钥计算需原始二进制输出（第4参数设为 true）；
未对计算出的签名结果调用 bin2hex()，导致与前端传来的 hash（必为小写十六进制字符串）类型不匹配；
未清除 hash 字段后再排序拼接，导致校验串污染。

✅ 正确实现步骤如下：

安全解码并提取原始参数
使用 rawurldecode() 解析 tgWebAppData，避免 URL 编码歧义（如空格、+）。
分离 hash 并清理数据数组
遍历参数数组，精准定位 hash= 开头项，提取其值，并将该项置空（后续用 array_filter() 清除）。
排序 + 换行拼接
对剩余参数调用 sort()（注意：PHP 的 sort() 是字典序升序，符合 Telegram 要求），再用 implode(" ", $arr) 生成标准校验字符串。

生成密钥与签名

$secret_key = hash_hmac('sha256', $bot_token, 'WebAppData', true); // 二进制密钥
$computed_hash = bin2hex(hash_hmac('sha256', $data_check_string, $secret_key, true));

恒定时间比对
使用 strcmp() 或 hash_equals()（更推荐）进行防时序攻击的字符串比较：

if (hash_equals($check_hash, $computed_hash)) {
    echo "✅ Valid Telegram user";
} else {
    http_response_code(403);
    echo "❌ Invalid or tampered data";
}

⚠️ 重要注意事项：

auth_date 必须在 24 小时内（建议服务端校验时间戳有效性）；
所有字段值（如 user JSON）需保持原始编码，不可二次 JSON 编码或修改结构；
生产环境务必启用 HTTPS，且 Web App 启动链接必须通过 https://t.me/your_bot/webapp?startapp=... 触发；
建议封装为独立函数，并添加日志记录（如校验失败时记录 $data_check_string 和 $computed_hash 用于调试）。

完整可运行示例（含健壮性增强）：

<?php $bot_token = "5368097647:AAFU8jBho71pglrzDeGw6LawrVuMmxaxpEQ";

// 获取原始 tgWebAppData（通常来自 POST 或 GET）
$data_check_string = $_POST['a'] ?? $_GET['a'] ?? '';
if (empty($data_check_string)) {
    die("❌ Missing data");
}

// 1. 原始解码 & 拆分
$data_check_arr = explode('&', rawurldecode($data_check_string));
$check_hash = null;

// 2. 提取并移除 hash
foreach ($data_check_arr as $key => $val) {
    if (str_starts_with($val, 'hash=')) {
        $check_hash = substr($val, 5); // 去掉 'hash='
        unset($data_check_arr[$key]);
        break;
    }
}

if ($check_hash === null) {
    die("❌ Missing hash parameter");
}

// 3. 清理、排序、拼接
$data_check_arr = array_values(array_filter($data_check_arr)); // 重索引 + 过滤空值
sort($data_check_arr);
$data_check_string = implode("
", $data_check_arr);

// 4. 计算签名
$secret_key = hash_hmac('sha256', $bot_token, 'WebAppData', true);
$computed_hash = bin2hex(hash_hmac('sha256', $data_check_string, $secret_key, true));

// 5. 安全比对
if (hash_equals($check_hash, $computed_hash)) {
    echo "✅ Authentication successful. Welcome!";
} else {
    http_response_code(403);
    echo "❌ Signature verification failed.";
}

遵循以上规范，即可稳定、安全地完成 Telegram Web App 用户身份验证。