Telegram Login Widget на PHP та Yii2: HMAC-SHA-256, перевірка auth_date та прив'язка акаунтів

Виджет авторизации 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 на сервері:

  1. Витягнути параметр hash з масиву отриманих даних.
  2. Видалити hash з масиву, щоб він не брав участі у формуванні рядка.
  3. Відсортувати решту пар «ключ-значення» за алфавітом ключів.
  4. Сформувати рядок для підпису (data_check_string), з'єднавши елементи у форматі key=value через символ перенесення рядка .
  5. Обчислити бінарний SHA-256 хеш від токена бота.
  6. Розрахувати HMAC-SHA-256 від сформованого рядка з використанням бінарного ключа.
  7. Порівняти отриманий хеш із переданим 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.

Нові статті — у Telegram

Розбираємо, що автоматизувати в бізнесі та як це працює на практиці. Без спаму.