Під час розробки Telegram Mini Apps розробники-початківці часто припускаються критичної помилки: беруть дані користувача безпосередньо з JS SDK через об'єкт window.Telegram.WebApp.initDataUnsafe і довіряють їм на бекенді. Оскільки клієнтський код виконується в браузері (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.