设置与开发

Telegram 小程序 initData 怎么验签?后端 HMAC-SHA256 实战

详解 Telegram Mini App(TMA 小程序)用户免登身份校验规范,拆解前端 initData 传参隐患与后端 HMAC-SHA256 验签算法、auth_date 防重放攻击及 Node.js/Python/Go 实现要点。

Telegram 小程序 initData 怎么验签?后端 HMAC-SHA256 实战(设置与开发封面图)
设置与开发Telegram 实战文章

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 签名;任何跳过后端密码学验签、直接信任前端解析结果的接口,都会直接暴露越权登录与资产被盗风险。

相关配图 · 配置架构客户端环境配置、频道防搬运与开发集成图解
STEP 01

网页端放开限制

iOS 受限于商店规则,需登录 web.telegram.org 打开 Disable filtering 后重启 App。

STEP 02

官方语言包与缓存

通过官方语言包链接一键汉化并关闭无限制媒体下载,清理缓存不丢云端消息。

STEP 03

频道评论与防转发

频道绑定讨论组即可开评论,开启 Restrict Saving Content 可禁止转发下载视频。

STEP 04

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 整理。