Проверка initData в Telegram Mini App на Python: код и ошибки

Когда Mini App обращается к вашему серверу, вам нужно убедиться, что запрос действительно пришёл из Telegram от конкретного пользователя, а не от злоумышленника, который подставил чужой user_id. Для этого Telegram подписывает строку initData, а сервер проверяет подпись.

Как устроена проверка

Mini App получает Telegram.WebApp.initData — строку вида query_id=...&user=...&auth_date=...&hash=.... Проверка делается так:

1. Разобрать строку на пары ключ-значение (значения декодируются из URL).
2. Убрать поле hash, остальные пары отсортировать по ключу и склеить в строку ключ=значение, разделяя переводом строки.
3. Вычислить секретный ключ: HMAC-SHA256, где ключ — строка WebAppData, а сообщение — токен бота.
4. Вычислить HMAC-SHA256 строки из шага 2 с этим секретом и сравнить результат (в hex) с полученным hash.
5. Проверить, что auth_date не старше разумного срока.

Рабочий код

import hashlib
import hmac
import json
import time
from urllib.parse import parse_qsl


def validate_init_data(init_data: str, bot_token: str, max_age: int = 3600) -> dict:
    """Возвращает данные Mini App, если подпись верна и данные свежие, иначе бросает ValueError."""
    pairs = dict(parse_qsl(init_data, keep_blank_values=True))
    received_hash = pairs.pop("hash", None)
    if not received_hash:
        raise ValueError("нет hash")

    check_string = "\n".join(f"{k}={v}" for k, v in sorted(pairs.items()))
    secret_key = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
    expected = hmac.new(secret_key, check_string.encode(), hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, received_hash):
        raise ValueError("подпись не совпала")
    if time.time() - int(pairs.get("auth_date", 0)) > max_age:
        raise ValueError("данные устарели")

    if "user" in pairs:
        pairs["user"] = json.loads(pairs["user"])
    return pairs

Мы прогнали этот код на подписанном образце, на подмене данных, на чужом токене и на устаревшем auth_date: корректные данные принимаются, остальные отклоняются.

Как передать initData на сервер

Фронтенд отправляет строку в заголовке запроса, а сервер проверяет её на каждом обращении:

fetch("/api/me", { headers: { Authorization: "tma " + Telegram.WebApp.initData } });

Префикс tma — распространённая договорённость, а не требование Telegram. Пример проверки в aiohttp:

from aiohttp import web


async def me(request: web.Request) -> web.Response:
    auth = request.headers.get("Authorization", "")
    if not auth.startswith("tma "):
        raise web.HTTPUnauthorized()
    try:
        data = validate_init_data(auth[4:], BOT_TOKEN)
    except ValueError:
        raise web.HTTPUnauthorized()
    return web.json_response({"user_id": data["user"]["id"]})

В FastAPI та же функция подключается как зависимость (Depends), которая читает заголовок и вызывает validate_init_data.

Типичные ошибки

• Проверка на клиенте. Подпись должна проверяться только на сервере: токен бота нельзя отдавать во фронтенд.
• Сравнение через ==. Используйте hmac.compare_digest, чтобы не открыть атаку по времени ответа.
• Забытый auth_date. Без проверки срока старые перехваченные данные работают вечно.
• Неправильный порядок ключей или лишние поля в строке проверки. Поле hash в строку не входит, остальные идут отсортированными по алфавиту.
• Не тот токен. Подпись привязана к токену конкретного бота. Если у вас несколько ботов, храните токен вместе с приложением.
• Доверие к initDataUnsafe. Это те же данные без проверки. Использовать их для авторизации нельзя.

Где это пригодится

Проверка initData нужна любому Mini App, который хранит данные пользователя: избранное, подписки на уведомления, сохранённые поиски. Так устроены Mini App в наших проектах: Da Nang House и HotTrip. Если вы строите бота или Mini App, посмотрите услугу «Telegram-боты и Mini App».