Виджет авторизации Telegram (Login Widget) позволяет пользователям входить на сайт в один клик без ввода паролей и SMS. Однако передаваемый клиентом набор данных (id, name, username, auth_date) открыт для подделки. Единственный способ убедиться, что данные пришли от Telegram, а не из Postman или поддельной формы — валидация подписи HMAC-SHA-256 на бэкенде.
В этой статье мы подробно разберем алгоритм проверки подписи Login Widget, нюансы работы с таймштампом auth_date, а также напишем чистый валидатор на PHP и готовый контроллер для Yii2, обрабатывающий регистрацию, вход и привязку Telegram-аккаунта.
Как работает Telegram Login Widget и в чём подвох
Когда пользователь нажимает кнопку входа через виджет, Telegram перенаправляет его на ваш redirect_url с набор параметров в GET или отправляет JS-объект в callback. Массив данных имеет следующий вид:
id— уникальный идентификатор пользователя в Telegram;first_name,last_name,username,photo_url— профильные данные;auth_date— Unix timestamp момента авторизации;hash— итоговая хеш-сумма для проверки валидности.
Главная ошибка разработчиков: путать алгоритм хеширования Telegram Login Widget и Telegram Mini Apps (initData). В Mini Apps секретным ключом выступает HMAC-SHA-256("WebAppData", bot_token). В Login Widget секретный ключ генерируется как обычный SHA-256 от токена бота в бинарном виде: hash('sha256', bot_token, true).
Алгоритм проверки подписи HMAC-SHA-256 на PHP
Для проверки подлинности полученных данных необходимо воспроизвести алгоритм Telegram на сервере:
- Извлечь параметр
hashиз массива полученных данных. - Удалить
hashиз массива, чтобы он не участвовал в формировании строки. - Отсортировать оставшиеся пары «ключ-значение» по алфавиту ключей.
- Сформировать подписываемую строку (data_check_string), соединив элементы в формате
key=valueчерез символ переноса строки. - Вычислить бинарный SHA-256 хеш от токена бота.
- Рассчитать HMAC-SHA-256 от сформированной строки с использованием бинарного ключа.
- Сравнить полученный хеш с переданным
hashс помощью функцииhash_equals()для защиты от атак по времени (timing attacks).
Ниже представлен изолированный сервисный класс для PHP 8.x, реализующий эту логику и дополнительно проверяющий срок давности авторизации через auth_date.
<?php
namespace app\components;
final class TelegramWidgetValidator
{
private string $botToken;
private int $maxAge;
public function __construct(string $botToken, int $maxAge = 86400)
{
$this->botToken = $botToken;
$this->maxAge = $maxAge;
}
public function validate(array $authData): bool
{
if (empty($authData['hash']) || empty($authData['auth_date'])) {
return false;
}
$checkHash = (string)$authData['hash'];
unset($authData['hash']);
// Защита от replay-атак: проверяем age таймштампа
$authDate = (int)$authData['auth_date'];
if ((time() - $authDate) > $this->maxAge) {
return false;
}
$dataCheckArray = [];
foreach ($authData as $key => $value) {
$dataCheckArray[] = $key . '=' . $value;
}
sort($dataCheckArray);
$dataCheckString = implode("
", $dataCheckArray);
$secretKey = hash('sha256', $this->botToken, true);
$calculatedHash = hash_hmac('sha256', $dataCheckString, $secretKey);
return hash_equals($calculatedHash, $checkHash);
}
}
Защита от Replay-атак: зачем нужен auth_date
Значение hash гарантирует, что данные пользователя не были изменены по пути. Однако без проверки auth_date злоумышленник, один раз перехвативший валидный URL с параметрами, сможет вечно авторизовываться под чужим именем.
Проверка (time() - $authDate) > $this->maxAge гарантирует, что сырые данные авторизации действительны только ограниченное время (например, 86400 секунд = 24 часа). Если запросу больше суток, бэкенд отклоняет авторизацию и запрашивает повторный вход.
Реализация авторизации и привязки аккаунта в Yii2
Рассмотрим сценарий работы контроллера Yii2 при получении редиректа от Telegram Login Widget. Поддерживаем 3 основных сценария:
- Пользователь уже существует в БД — выполняем авторизацию в сессии.
- Пользователь уже авторизован под обычным аккаунтом на сайте — привязываем к нему
telegram_id. - Пользователь новый — создаём новую учётную запись и входим.
<?php
namespace app\controllers;
use Yii;
use yii\web\Controller;
use yii\web\Response;
use app\models\User;
use app\components\TelegramWidgetValidator;
class AuthController extends Controller
{
public function actionTelegramCallback(): Response
{
$request = Yii::$app->request;
$authData = $request->get();
$botToken = Yii::$app->params['telegramBotToken'] ?? getenv('TELEGRAM_BOT_TOKEN');
if (!$botToken) {
throw new \RuntimeException('Токен Telegram бота не задан в конфигурации.');
}
$validator = new TelegramWidgetValidator($botToken, 86400);
if (!$validator->validate($authData)) {
Yii::$app->session->setFlash('error', 'Ошибка безопасности: недействительная подпись Telegram.');
return $this->redirect(['site/login']);
}
$telegramId = (int)$authData['id'];
$user = User::findOne(['telegram_id' => $telegramId]);
// 1. Пользователь с таким telegram_id уже есть — входим
if ($user !== null) {
Yii::$app->user->login($user, 3600 * 24 * 30);
return $this->goHome();
}
// 2. Пользователь уже авторизован на сайте — привязываем Telegram к профилю
if (!Yii::$app->user->isGuest) {
/** @var User $currentUser */
$currentUser = Yii::$app->user->identity;
$currentUser->telegram_id = $telegramId;
$currentUser->telegram_username = $authData['username'] ?? null;
if ($currentUser->save(false)) {
Yii::$app->session->setFlash('success', 'Telegram-аккаунт успешно привязан.');
}
return $this->redirect(['user/profile']);
}
// 3. Новый пользователь — регистрируем
$newUser = new User();
$newUser->telegram_id = $telegramId;
$newUser->username = $authData['username'] ?? ('tg_' . $telegramId);
$newUser->first_name = $authData['first_name'] ?? '';
$newUser->last_name = $authData['last_name'] ?? '';
$newUser->auth_key = Yii::$app->security->generateRandomString();
if ($newUser->save(false)) {
Yii::$app->user->login($newUser, 3600 * 24 * 30);
$this->sendTelegramNotification($telegramId, "Вы успешно вошли на сайт через Telegram Widget!");
return $this->goHome();
}
Yii::$app->session->setFlash('error', 'Не удалось создать пользователя.');
return $this->redirect(['site/login']);
}
private function sendTelegramNotification(int $chatId, string $message): bool
{
$botToken = Yii::$app->params['telegramBotToken'] ?? getenv('TELEGRAM_BOT_TOKEN');
$url = "https://api.telegram.org/bot{$botToken}/sendMessage";
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'chat_id' => $chatId,
'text' => $message,
'parse_mode' => 'HTML',
]),
CURLOPT_TIMEOUT => 5,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($response === false || $httpCode !== 200) {
return false;
}
$result = json_decode($response, true);
return json_last_error() === JSON_ERROR_NONE && !empty($result['ok']);
}
}
Настройка виджета на фронтенде
Вставьте следующий JS-скрипт на страницу авторизации вашего сайта. Замените bot_name на имя вашего бота без символа @, а data-auth-url на абсолютный URL вашего Yii2 action.
<script async src="https://telegram.org/js/telegram-widget.js?22"
data-telegram-login="YourProjectBot"
data-size="large"
data-auth-url="https://example.com/auth/telegram-callback"
data-request-access="write">
</script>
Частые ошибки при работе с Telegram Login Widget
- Использование file_get_contents для API: Все запросы к
api.telegram.orgнужно делать через cURL с явной проверкой HTTP-кода и ошибок парсинга JSON. - Сравнение строк через === вместо hash_equals(): Обычное сравнение оператором
===уязвимо к атакам по времени сравнения байтов. Всегда используйтеhash_equals(). - Мутация данных перед проверкой: Убедитесь, что параметры из
$_GETпередаются в валидатор в их оригинальном строковом виде без предварительной принудительной типизации. - Привязка без авторизации: При связывании аккаунтов всегда проверяйте статус текущей сессии (
!Yii::$app->user->isGuest), чтобы предотвратить захват чужого профиля.
Разработка и интеграция сложных решений на базе Telegram Bot API требует глубокого понимания безопасности и архитектуры — доверить такую задачу профильной команде можно в сервисе BotCreator.