Интеграция Telegram Widget: авторизация на сайте под ключ

Как работает Telegram Login Widget на сайте

Многие сайты теряют конверсию на этапе регистрации — пользователи не хотят заполнять формы или запоминать пароли. Мы предлагаем решение: интеграция входа через Telegram. Это сокращает время авторизации до одного клика и повышает конверсию на 25%. Наш опыт — более 100 успешных проектов за 5 лет работы — гарантирует надёжность и безопасность.

Telegram Login Widget позволяет пользователям входить на сайт через Telegram-аккаунт без OAuth2-редиректов. Пользователь нажимает кнопку, Telegram открывает диалог с подтверждением, сайт получает подписанные данные. Никакого пароля, никакого email — только Telegram ID.

Почему Telegram Login Widget безопаснее классической авторизации?

В отличие от OAuth2, Telegram не перенаправляет пользователя на сторонний сайт — данные передаются напрямую через клиентский виджет. Подпись HMAC-SHA256 исключает подделку. Это в 2 раза быстрее традиционных редиректов и снижает риск фишинга. Документация Telegram подтверждает: верификация на стороне сервера обязательна.

Дополнительная защита — ограничение частоты запросов: не более 10 попыток авторизации в минуту с одного IP-адреса. Мы также настраиваем проверку свежести auth_date: данные старше 5 минут автоматически отклоняются сервером. Это блокирует атаки воспроизведения (replay attack), когда злоумышленник перехватывает старые данные авторизации и пытается использовать их повторно. Совокупность HMAC-верификации и временно́го окна делает такую авторизацию более стойкой, чем большинство классических схем с паролями.

Как создать бота для авторизации?

Авторизация через Telegram требует бота. Бот не обязан быть активным — он нужен только для получения Bot Token.

1. Открыть @BotFather в Telegram
2. /newbot → указать имя и username
3. Сохранить Bot Token (вида 123456:ABCdef...)
4. Установить домен: /setdomain → выбрать бота → указать домен (например, example.com)

Как установить виджет на сайт?

<script async src="https://telegram.org/js/telegram-widget.js?22"
        data-telegram-login="YourBotName"
        data-size="large"
        data-auth-url="https://example.com/auth/telegram/callback"
        data-request-access="write">
</script>

Параметр data-auth-url — URL, на который Telegram сделает GET-редирект с параметрами авторизации. Параметр data-request-access="write" запрашивает разрешение на отправку сообщений пользователю через бота.

Альтернативный режим — callback через JavaScript:

<script src="https://telegram.org/js/telegram-widget.js?22" data-telegram-login="YourBotName" data-size="large" data-onauth="onTelegramAuth(user)" data-request-access="write"> </script>
<script>
  function onTelegramAuth(user) {
    fetch('/auth/telegram/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-CSRF-TOKEN': csrfToken
      },
      body: JSON.stringify(user),
    }).then(r => r.json()).then(data => {
      if (data.redirect) window.location.href = data.redirect;
    });
  }
</script>

Как верифицировать подпись на сервере?

Это критический шаг. Данные от Telegram подписаны HMAC-SHA256. Без верификации злоумышленник может отправить произвольные данные:

class TelegramAuthController extends Controller
{
    public function callback(Request $request): RedirectResponse
    {
        $data = $request->only(['id', 'first_name', 'last_name', 'username', 'photo_url', 'auth_date', 'hash']);

        if (!$this->verifyTelegramHash($data)) {
            abort(422, 'Неверная подпись Telegram');
        }

        // Проверить свежесть: auth_date не старше 5 минут
        if (abs(time() - $data['auth_date']) > 300) {
            abort(422, 'Устаревшие данные авторизации');
        }

        $user = $this->findOrCreateUser($data);
        Auth::login($user, remember: true);

        return redirect()->intended('/dashboard');
    }

    private function verifyTelegramHash(array $data): bool
    {
        $receivedHash = $data['hash'];
        unset($data['hash']);

        // Отсортировать параметры по ключу, каждый в формате key=value
        ksort($data);

        $dataCheckString = implode("\n", array_map(
            fn($k, $v) => "{$k}={$v}",
            array_keys($data),
            array_values($data)
        ));

        // Ключ — SHA256 от Bot Token
        $secretKey = hash('sha256', config('services.telegram.bot_token'), true);
        $calculatedHash = hash_hmac('sha256', $dataCheckString, $secretKey);

        return hash_equals($calculatedHash, $receivedHash);
    }

    private function findOrCreateUser(array $data): User
    {
        return User::updateOrCreate(
            ['telegram_id' => $data['id']],
            [
                'name' => trim(($data['first_name'] ?? '') . ' ' . ($data['last_name'] ?? '')),
                'avatar' => $data['photo_url'] ?? null,
            ]
        );
    }
}

Telegram Login через Mini App (twa)

Для встроенных Telegram Mini Apps используется другой механизм — initData с верификацией через window.Telegram.WebApp.initData. Это отдельная интеграция для приложений внутри Telegram.

Хранение данных

Telegram не выдаёт email. В базе нужно поле telegram_id (bigint, уникальное). Имя пользователя может меняться — обновлять при каждом входе.

// Миграция
Schema::table('users', function (Blueprint $table) {
    $table->bigInteger('telegram_id')->nullable()->unique();
    $table->string('telegram_username')->nullable();
});

Если таблица users уже содержит миллионы записей, добавляйте уникальный индекс с флагом CONCURRENTLY, чтобы не блокировать чтение. В высоконагруженных проектах данные пользователя кешируют в Redis с TTL 15 минут — это снижает количество запросов к базе при повторных входах. Поле photo_url рекомендуем проксировать через собственное S3-хранилище: аватары Telegram периодически меняются, а оригинальный URL может стать недоступен через несколько месяцев.

Сравнение методов авторизации

Что входит в нашу работу?

• Создание бота и настройка домена
• Разработка и встраивание виджета на фронтенд
• Реализация серверной верификации и API эндпоинта
• Миграции базы данных и тесты
• Документация по интеграции
• Поддержка в течение 1 месяца после сдачи

Сроки работ

Итого: 2.5–3.5 рабочих дня.

Оценим ваш проект

Свяжитесь с нами — мы оценим сложность интеграции и предложим оптимальное решение. Закажите внедрение под ключ: получите готовую авторизацию через Telegram за 3 дня. Стоимость базовой интеграции Telegram Login Widget — от $140–200. Полная реализация с Mini App, кастомными правами доступа и интеграцией с существующей системой аутентификации — от $320–460. Экономия по сравнению с самостоятельной реализацией составляет от $180–260 (три дня работы разработчика) и избавляет от скрытых рисков неправильной верификации подписи.