01 /
为什么 Mini App 前端 initData 必须在后端做 HMAC 验签
前端传入的 window.Telegram.WebApp.initData 绝对不可直接信任,攻击者只需打开浏览器控制台或拦截网络请求,就能任意篡改其中的 user JSON 字段冒充他人或管理员 UID。后端必须对 initData 原始查询字符串做 URL 解码、按键字典序拼接 data_check_string,并用 HMAC-SHA256("WebAppData", BOT_TOKEN) 派生密钥完成签名比对及 auth_date 有效期校验,验证通过后才能颁发业务登录态。
在 Telegram Mini App(TMA 小程序)免登流程中,initData 是客户端向服务端证明用户身份的凭证。Telegram 客户端拉起小程序时,会使用对应 Bot 的 Token 派生密钥对所有参数生成 hash 签名;任何跳过后端密码学验签、直接信任前端解析结果的接口,都会直接暴露越权登录与资产被盗风险。
网页端放开限制
iOS 受限于商店规则,需登录 web.telegram.org 打开 Disable filtering 后重启 App。
官方语言包与缓存
通过官方语言包链接一键汉化并关闭无限制媒体下载,清理缓存不丢云端消息。
频道评论与防转发
频道绑定讨论组即可开评论,开启 Restrict Saving Content 可禁止转发下载视频。
Bot 与小程序安全链路
生产级 Bot 走单实例 Webhook + 限流队列,Mini App 后端必须做 initData HMAC 验签。
02 /
标准后端验签步骤与 Node.js / Python / Go 示例
无论服务端使用哪种语言,Telegram 官方定义的 initData 验签算法都严格遵循以下 5 个步骤,参数解码时机与 HMAC 密钥顺序必须完全一致:
1. 解析查询字符串并剥离 hash:将前端提交的 initData 按 URL 查询参数解析,提取 hash 字段并从待校验参数集合中删除,其余所有字段(如 query_id、user、auth_date、signature 等)完整保留。
2. 按 key 字母升序拼接 data_check_string:对剩余键值对按 key 做 ASCII 升序排列,使用 URL 解码后的原始值拼成 key=value,再以换行符 \n 连接为 data_check_string(末尾不留换行符)。
3. 派生密钥 secret_key:以固定字符串 "WebAppData" 作为 HMAC 密钥、你的 BOT_TOKEN 作为消息体,计算 HMAC-SHA256 得到 32 字节原始二进制密钥 secret_key。
4. 计算签名并恒定时间比对:以 secret_key 为密钥、data_check_string 为消息体再次计算 HMAC-SHA256,转为小写十六进制字符串后,使用恒定时间比对函数与 hash 校验,防止计时侧信道攻击。
5. 校验 auth_date 时间戳防重放:将 auth_date 转为整数 Unix 秒级时间戳,确认当前服务器时间与 auth_date 的差值在允许窗口内(登录换票建议 300 至 3600 秒,并预留 60 秒以内时钟偏差)。
Node.js(原生 node:crypto)验签实现:
import crypto from 'node:crypto';
export function verifyInitData(initData, botToken, maxAgeSec = 3600) {
const params = new URLSearchParams(initData);
const hash = params.get('hash');
if (!hash) return null;
params.delete('hash');
const checkStr = [...params.entries()]
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
.map(([k, v]) => `${k}=${v}`)
.join('\n');
const secret = crypto.createHmac('sha256', 'WebAppData').update(botToken).digest();
const calcHex = crypto.createHmac('sha256', secret).update(checkStr).digest('hex');
if (
hash.length !== calcHex.length ||
!crypto.timingSafeEqual(Buffer.from(calcHex), Buffer.from(hash.toLowerCase()))
) return null;
const authDate = Number(params.get('auth_date') || 0);
const now = Math.floor(Date.now() / 1000);
if (!authDate || now - authDate > maxAgeSec || authDate - now > 60) return null;
return JSON.parse(params.get('user') || '{}');
}Python(hmac + urllib.parse)验签实现:
import hashlib, hmac, json, time
from urllib.parse import parse_qsl
def verify_init_data(init_data: str, bot_token: str, max_age: int = 3600):
pairs = dict(parse_qsl(init_data, strict_parsing=True))
tg_hash = pairs.pop("hash", None)
if not tg_hash:
return None
check_str = "\n".join(f"{k}={pairs[k]}" for k in sorted(pairs))
secret = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
calc_hex = hmac.new(secret, check_str.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(calc_hex, tg_hash.lower()):
return None
auth_date = int(pairs.get("auth_date", 0))
now = int(time.time())
if auth_date <= 0 or now - auth_date > max_age or auth_date - now > 60:
return None
return json.loads(pairs.get("user", "{}"))Go(crypto/hmac + net/url)验签实现:
func VerifyInitData(initData, botToken string, maxAgeSec int64) (url.Values, error) {
vals, err := url.ParseQuery(initData)
if err != nil { return nil, err }
tgHash := vals.Get("hash")
if tgHash == "" { return nil, errors.New("missing hash") }
vals.Del("hash")
keys := make([]string, 0, len(vals))
for k := range vals { keys = append(keys, k) }
sort.Strings(keys)
lines := make([]string, 0, len(keys))
for _, k := range keys { lines = append(lines, k+"="+vals.Get(k)) }
mac1 := hmac.New(sha256.New, []byte("WebAppData"))
mac1.Write([]byte(botToken))
mac2 := hmac.New(sha256.New, mac1.Sum(nil))
mac2.Write([]byte(strings.Join(lines, "\n")))
calcHex := hex.EncodeToString(mac2.Sum(nil))
if !hmac.Equal([]byte(calcHex), []byte(strings.ToLower(tgHash))) {
return nil, errors.New("invalid hash")
}
authDate, _ := strconv.ParseInt(vals.Get("auth_date"), 10, 64)
now := time.Now().Unix()
if authDate <= 0 || now-authDate > maxAgeSec || authDate-now > 60 {
return nil, errors.New("expired initData")
}
return vals, nil
}03 /
时间过期校验、代理篡改与签名泄露排查
严正警告:绝不能把 BOT_TOKEN 放在小程序前端代码或客户端打包产物中用于本地验签。 部分开发者为了省掉后端登录接口,把 BOT_TOKEN 写死在前端 JS、环境变量前缀(如 VITE_BOT_TOKEN)或移动端本地代码里。一旦上线,任何抓包者或反编译人员都能直接拿到完整 BOT_TOKEN,随后按照完全相同的 HMAC-SHA256 算法自行签发任意用户(包括管理员 UID、高净值账号)的合法 initData,直接盗刷积分、余额或业务资产。
误区一:只传 initDataUnsafe 给后端。 Telegram SDK 暴露的 window.Telegram.WebApp.initDataUnsafe 只是方便前端渲染昵称与头像的未签名对象,本身不包含 hash 校验依据。如果后端直接读取 initDataUnsafe.user 放行登录,攻击者用 curl 改个数字 UID 就能越权访问任意账户。前端必须把完整的 window.Telegram.WebApp.initData 原始字符串放进 Authorization 请求头或 POST Body 提交。
误区二:URL 编码未还原或 HMAC 参数顺序写反。 实际接入中,绝大多数验签失败集中在两个细节:一是未对 user 参数做 URL 解码,或者前端请求库对已编码的 initData 进行了二次编码,导致 data_check_string 原文与 Telegram 签名时不一致;二是将 HMAC_SHA256("WebAppData", BOT_TOKEN) 的密钥与消息顺序写反,或误把十六进制字符串而非 32 字节原始摘要传给第二步。
误区三:忽略 auth_date 窗口与服务器对时。 不检查 auth_date 会让泄露的 initData 长期有效,形成重放攻击漏洞。建议前端仅在打开小程序或登录态过期时,将 initData 发给 /api/auth/tma 接口(校验窗口设为 300 至 900 秒),换取后端签发的短效 JWT 或 Session;同时在服务器启用 NTP 自动对时,防止时钟偏差误拦正常用户。

04 /
Mini App 上线前安全检查清单
在 Telegram Mini App 正式上线前,建议按以下清单逐项复核鉴权链路:
- 密钥隔离:检查前端编译产物(dist/)、Sourcemaps 与代码仓库历史,确认不存在 BOT_TOKEN。
- 唯一入口:确认所有资产、下单及读写接口仅信任后端验签后颁发的 JWT/Session,拒绝裸传 uid 或 initDataUnsafe。
- 多端回归:分别在 iOS、Android 及 Desktop 桌面端使用含中文、Emoji 昵称和特殊字符的账号测试验签,确保编解码无差异。
- 防重放与对时:确认生产环境开启了 auth_date 过期拦截与恒定时间比对,且容器或宿主机系统时间已同步。
- 多 Bot 隔离:若同一后端服务多个小程序,需按请求上下文隔离对应 BOT_TOKEN,避免跨 Bot 混用密钥。
正在开发 Telegram Mini App 并对接免登与收款系统?如果你需要协助排查多端鉴权故障、设计防重放风控网关,或对接 Telegram Stars、TON 与 USDT 支付回调,可以前往 AnyTele 技术服务与定制开发 了解实战方案与接入支持。
05 /
高频问题速答
Q1:部分 Telegram 用户没有设置 @username,后端应该拿什么作为唯一标识?
A:只有 user.id(即 Telegram 数字 UID)是全局唯一且永久不变的主键。username、first_name 和 last_name 均允许为空或随时修改,数据库建表与资产归属必须绑定 user.id。
Q2:initData 里出现了 signature 字段,会影响 HMAC-SHA256 验签吗?
A:Bot API 8.0 起 initData 新增了基于 Ed25519 的 signature 字段,用于第三方服务在不接触 BOT_TOKEN 时校验身份。如果你的后端仍使用 BOT_TOKEN 走 HMAC-SHA256 验签,切勿手动剔除 signature,必须与其他非 hash 参数一起按字母序拼接进 data_check_string,否则签名校验会失败。
Q3:每次业务 API 请求都要带 initData 验签,还是登录后换 JWT?
A:建议仅在初始化阶段提交一次 initData 换取业务侧的 JWT 或 Session Cookie,后续请求直接校验会话凭证即可。这样既能将 auth_date 窗口压短以防重放,也能避免用户停留页面超时后触发鉴权报错。
参考资料
功能规则参照下列官方说明,实操步骤由 AnyTele 整理。
