Реализация авторизации через Telegram на сайте

Реализация авторизации через Telegram на сайте

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

Принцип работы

В отличие от классического OAuth2, Telegram не перенаправляет пользователя на свой сайт. Авторизация происходит через:

1. Widget-режим — JavaScript виджет, встроенный на страницу
2. Redirect-режим — ссылка на t.me/BotName?start=auth

Подписанные данные передаются клиенту, который отправляет их на сервер для верификации.

Создание бота

Авторизация через 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();
});

Сроки работ

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