При разработке 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 состоит из следующих шагов:
- Извлечение параметра
hashиз query-строки. - Сортировка всех оставшихся пар
key=valueпо алфавиту и их объединение через символ перевода строки\n. Это формируетdata_check_string. - Вычисление секретного ключа:
HMAC-SHA-256от токена бота с константной строкойWebAppDataв качестве ключа. - Вычисление контрольного HMAC от
data_check_stringс использованием полученного секретного ключа. - Сравнение вычисленного хэша с переданным
hashс использованием функцииhash_equals()для защиты от атак по времени (timing attacks). - Проверка актуальности
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.