Валидация initData в Telegram Mini App на PHP: защита от подмены user.id и активация MainButton

При разработке Telegram Mini Apps начинающие разработчики часто совершают критическую ошибку: берут данные пользователя напрямую из JS SDK через объект window.Telegram.WebApp.initDataUnsafe и доверяют им на бэкенде. Поскольку клиeнтский код исполняется в браузере (WebView), злоумышленник может открыть страницу приложения вне Telegram, подделать объект user.id, подставить чужой идентификатор и получить доступ к чужим данным или балансу.

Для защиты Telegram передает подписанную строку initData. В этой статье мы разберем, как устроен спуфинг клиентских данных, реализуем строгую валидацию HMAC-SHA-256 с timing-safe сравнением на PHP и настроим управление MainButton на фронтенде только после подтверждения авторизации сервером.

Уязвимость initDataUnsafe и подделка payload

Объект initDataUnsafe распарсен на стороне JS и не содержит никаких гарантий подлинности. Любой пользователь может открыть DevTools или отправлять запросы напрямую к вашему API, сгенерировав поддельный JSON с любым user.id.

Пример фальшивой строки, которую атакующая сторона может передать на ваш сервер под видом легитимного initData:

query_id=AAH12345&user=%7B%22id%22%3A99999999%2C%22first_name%22%3A%22Attacker%22%2C%22username%22%3A%22hacker%22%7D&auth_date=1710000000&hash=fake_hash_value_string

Если сервер принимает параметр user.id из запроса без проверки подписи hash, система скомпрометирована. Чтобы этого избежать, сервер должен принимать только сырую строку initData и выполнять криптографическую проверку.

Алгоритм HMAC-SHA-256 валидации на бэкенде

Проверка подлинности Telegram initData состоит из следующих шагов:

  1. Извлечение параметра hash из query-строки.
  2. Сортировка всех оставшихся пар key=value по алфавиту и их объединение через символ перевода строки \n. Это формирует data_check_string.
  3. Вычисление секретного ключа: HMAC-SHA-256 от токена бота с константной строкой WebAppData в качестве ключа.
  4. Вычисление контрольного HMAC от data_check_string с использованием полученного секретного ключа.
  5. Сравнение вычисленного хэша с переданным hash с использованием функции hash_equals() для защиты от атак по времени (timing attacks).
  6. Проверка актуальности auth_date, чтобы исключить повторное использование старых перехваченных строк (Replay Attack).

Реализация авторизационного эндпоинта на PHP

Создадим обработчик /api/auth.php, который принимает initData, выполняет валидацию и возвращает HTTP-статус 200 OK при успехе или 401 Unauthorized при ошибке.

<?php
declare(strict_types=1);

header('Content-Type: application/json');

$botToken = getenv('BOT_TOKEN');
if (!$botToken) {
http_response_code(500);
echo json_encode(['ok' => false, 'error' => 'Server configuration error']);
exit;
}

$rawInput = file_get_contents('php://input');
$data = json_decode($rawInput, true);

if (json_last_error() !== JSON_ERROR_NONE || empty($data['initData'])) {
http_response_code(400);
echo json_encode(['ok' => false, 'error' => 'Invalid JSON or missing initData']);
exit;
}

$initDataRaw = $data['initData'];
parse_str($initDataRaw, $parsedData);

if (!isset($parsedData['hash'], $parsedData['auth_date'])) {
http_response_code(401);
echo json_encode(['ok' => false, 'error' => 'Missing required HMAC parameters']);
exit;
}

$receivedHash = $parsedData['hash'];
$authDate = (int)$parsedData['auth_date'];
unset($parsedData['hash']);

// Проверка на устаревшие данные (максимум 24 часа = 86400 сек)
if ((time() - $authDate) > 86400) {
http_response_code(401);
echo json_encode(['ok' => false, 'error' => 'Authentication data is expired']);
exit;
}

// Формирование data_check_string
$dataCheckArray = [];
foreach ($parsedData as $key => $value) {
$dataCheckArray[] = $key . '=' . $value;
}
sort($dataCheckArray);
$dataCheckString = implode("
", $dataCheckArray);

// Генерация HMAC-SHA-256
$secretKey = hash_hmac('sha256', $botToken, 'WebAppData', true);
$calculatedHash = hash_hmac('sha256', $dataCheckString, $secretKey);

// Timing-safe сравнение хэшей
if (!hash_equals($calculatedHash, $receivedHash)) {
http_response_code(401);
echo json_encode(['ok' => false, 'error' => 'Invalid HMAC signature']);
exit;
}

$userData = json_decode($parsedData['user'] ?? '{}', true);

// Запрос успешен, создаем сессию или выдаем JWT
http_response_code(200);
echo json_encode([
'ok' => true,
'user' => [
'id' => $userData['id'] ?? null,
'first_name' => $userData['first_name'] ?? '',
'username' => $userData['username'] ?? ''
]
]);

Безопасное управление MainButton на фронтенде

Пока сервер не подтвердил валидность initData и не вернул HTTP 200, интерфейс приложения должен оставаться заблокированным. Главную кнопку интерфейса Telegram.WebApp.MainButton следует удерживать скрытой или отключенной, чтобы предотвратить любые целевые действия неавторизованного пользователя.

Пример безопасного JS-скрипта инициализации Mini App:

document.addEventListener('DOMContentLoaded', async () => {
const tg = window.Telegram?.WebApp;

if (!tg) {
console.error('Telegram WebApp SDK not found');
return;
}

tg.ready();
tg.expand();

// По умолчанию скрываем и отключаем MainButton
tg.MainButton.hide();
tg.MainButton.disable();

const initData = tg.initData;

if (!initData) {
alert('Ошибка: запуск разрешен только внутри Telegram Mini App');
return;
}

try {
const response = await fetch('/api/auth.php', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({ initData: initData })
});

const result = await response.json();

if (response.status === 200 && result.ok) {
// Активируем интерфейс только после успешного 200 OK от API
tg.MainButton.setText('Оформить заказ');
tg.MainButton.show();
tg.MainButton.enable();

tg.MainButton.onClick(() => {
alert(`Авторизован пользователь ID: ${result.user.id}`);
});
} else {
tg.MainButton.hide();
alert(`Ошибка авторизации: ${result.error || 'Доступ запрещен'}`);
}
} catch (error) {
tg.MainButton.hide();
console.error('Network or auth error:', error);
alert('Не удалось связаться с сервером авторизации');
}
});

Тестирование защиты от подделки с помощью cURL

Чтобы проверить, как бэкенд реагирует на поддельный payload с некорректной signature, выполните следующую cURL-команду из терминала:

curl -X POST https://your-domain.com/api/auth.php \
-H "Content-Type: application/json" \
-d '{
"initData": "query_id=AAG12345&user=%7B%22id%22%3A99999999%2C%22first_name%22%3A%22FakeUser%22%7D&auth_date=1710000000&hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}'

Сервер выполнит перерасчет HMAC для подставленного user.id=99999999, зафиксирует расхождение с переданным hash и вернет HTTP-ответ status 401 Unauthorized:

{
"ok": false,
"error": "Invalid HMAC signature"
}

Таким образом, даже если злоумышленник изменит хотя бы один символ в user.id, auth_date или любом другом поле, он не сможет подобрать подпись بدون знания токена вашего бота, хранящегося на бэкенде.

Если вы разрабатываете сложные решения для Telegram или вам нужна масштабируемая инфраструктура для Mini Apps, ознакомьтесь с решениями от BotCreator.

Новые статьи — в Telegram

Разбираем, что автоматизировать в бизнесе и как это работает на практике. Без спама.