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

Впровадження Telegram аутентифікації для веб-сайтів

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

На відміну від класичного OAuth2, Telegram не перенаправляє користувача на свій сайт. Авторизація відбувається через:

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

Підписані дані передаються клієнту, який відправляє їх на сервер для верифікації.

Створення бота

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" запитує дозвіл на відправку повідомлень користувачу через бота.

Верифікація підпису на сервері

Критичний крок. Дані від 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']);

        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);
    }
}

Терміни

Разом: 2.5–3.5 дня.