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

Як працює Telegram Login Widget на сайті

Багато сайтів втрачають конверсію на етапі реєстрації — користувачі не хочуть заповнювати форми чи запам'ятовувати паролі. Ми пропонуємо рішення: інтеграція входу через Telegram. Це скорочує час авторизації до одного кліка та підвищує конверсію. Наш досвід — понад 40 успішних проєктів та 5+ років на ринку — гарантує надійність і безпеку.

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

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

На відміну від OAuth2, Telegram не перенаправляє користувача на сторонній сайт — дані передаються напряму через клієнтський віджет. Підпис HMAC-SHA256 виключає підробку. Це в 2 рази швидше за традиційні редиректи та в 3 рази безпечніше за парольну автентифікацію. Документація Telegram (telegram.org) підтверджує: верифікація на стороні сервера обов'язкова.

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

Для авторизації через Telegram використовується Telegram Login Widget, який забезпечує безпечну верифікацію. Вхід через Telegram на сайт реалізується за допомогою віджета. Це простий та швидкий спосіб.

Як створити бота для авторизації?

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

1. Відкрити @BotFather у Telegram
2. /newbot → вказати ім'я та username
3. Зберегти Bot Token (виду 123456:ABCdef...)
4. Встановити домен: /setdomain → вибрати бота → вказати домен вашого сайту

Як встановити віджет на сайт?

<script
  async
  src="https://telegram.org/js/telegram-widget.js?22"
  data-telegram-login="YourBotName"
  data-size="large"
  data-auth-url="https://ваш-домен/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('/home');
    }

    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 робочих дні, вартість від 200$.

Telegram Widget економить до 50% часу на авторизації порівняно з формою реєстрації. Завдяки нашому досвіду (5+ років на ринку) ви отримуєте надійну інтеграцію без помилок. Ми маємо 5+ років досвіду та реалізували понад 40 проєктів з інтеграції Telegram.

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

Зв'яжіться з нами — ми безкоштовно оцінимо складність інтеграції та запропонуємо оптимальне рішення. Замовте впровадження під ключ: отримайте готову авторизацію через Telegram за 3 дні.

Аутентифікація та авторизація: OAuth, JWT, сесії, RBAC, 2FA

На одному проєкті токен JWT із роллю admin: false» міг бути змінений клієнтом на admin: true» — і сервер прийняв його без верифікації підпису. Ми знайшли це на тестовому стенді, коли робили огляд існуючої кодової бази новому замовнику. Причина — застаріла бібліотека jsonwebtoken, яка в певних версіях пропускала алгоритм «none». Наслідки — повний доступ до адміністративного API для будь-якого зареєстрованого користувача. Замовник не знав про це, але ми оцінили ризик, переписали модуль авторизації під ключ і запровадили обов’язкову перевірку алгоритму. Тепер подібних інцидентів немає. За 7+ років ми реалізували понад 50 проєктів із системами аутентифікації та авторизації користувачів — від стартапів до корпоративних рішень, що працюють із фінансовими даними.

Чому JWT не варто зберігати в localStorage?

JWT складається з трьох частин: header (алгоритм), payload (дані), signature (підпис). Підпис верифікує, що payload не змінено. Без перевірки підпису — це просто base64-encoded JSON, який будь-хто може підробити. Помилки, які бачимо в коді регулярно:

• Зберігання в localStorage. LocalStorage доступний будь-якому JS на сторінці — XSS-атака читає токен і відправляє на сервер зловмисника. Access token в пам’яті (змінна модуля), refresh token в httpOnly cookie — правильна схема.
• Довгоживучі access-токени. Access token на 7 днів без можливості відкликання — витік дає 7 днів доступу. Стандарт: 15 хвилин для access token, 30 днів для refresh token з ротацією. При кожному використанні refresh token видається новий, старий інвалідується — якщо старий хтось використовує повторно, це детектується як Token Reuse Attack, уся сім’я токенів відкликається.
• Зберігання секретних даних у payload. JWT payload не зашифровано, лише підписано — його видно в base64. Паролі, платіжні дані, особиста інформація — не в JWT. Алгоритм RS256 (асиметричний) кращий за HS256 (симетричний) у мікросервісній архітектурі: сервіси можуть верифікувати токен публічним ключем, не маючи доступу до секрету для його створення.

Як обрати між сесіями та токенами?

Сесії зберігають стан на сервері (Redis, database) — сервер може миттєво відкликати сесію. При масштабуванні на кілька інстансів потрібен спільний store (Redis Cluster). Cookie з session ID — httpOnly, Secure, SameSite=Strict.

Stateless JWT не вимагають server-side storage, масштабуються горизонтально. Але відкликання токена до завершення терміну — тільки через blacklist (Redis), що частково знімає перевагу stateless.

Для більшості веб-додатків сесії простіші та безпечніші. JWT має сенс для API, що споживаються з мобільного додатку, та для мікросервісної архітектури. Оцініть ваш сценарій — ми допоможемо обрати правильний підхід.

OAuth 2.0 та OpenID Connect

OAuth 2.0 — протокол делегованої авторизації, не аутентифікації. «Увійти через Google» — це OpenID Connect поверх OAuth 2.0, який додає id_token з даними користувача. Authorization Code Flow з PKCE — єдиний правильний flow для браузерних SPA та мобільних додатків. Implicit Flow застарів і небезпечний. PKCE (Proof Key for Code Exchange) захищає від перехоплення authorization code.

Реалізація OAuth сервера: не пишемо з нуля. Keycloak (open source, self-hosted), Auth0, Okta — готові рішення. Laravel Passport або Laravel Sanctum для серверних додатків. NextAuth.js для Next.js — підтримує 50+ провайдерів з коробки. Для B2B продуктів з корпоративними клієнтами — SAML 2.0 SSO. Корпоративні IT-відділи часто вимагають його замість OAuth. @boxyhq/saml-jackson — node.js бібліотека для SAML → OAuth2 адаптера.

RBAC, ABAC, ReBAC — що і коли застосовувати

Role-Based Access Control — у користувача є ролі, у ролей — права. Проста реалізація: user → roles → permissions. Але коли з'являється ресурсна авторизація («користувач може редагувати лише свої пости»), RBAC ускладнюється. У такому разі використовуйте Spatie Laravel Permission (стандарт для Laravel): поліморфні ролі та права, кешування, super-admin через gate. Інтеграція з Eloquent — $user->can('edit posts'), $user->hasRole('editor').

ABAC (Attribute-Based Access Control) — політики на основі атрибутів: користувача, ресурсу, середовища. Потрібен, коли правила доступу складні: «менеджер може переглядати замовлення свого регіону, якщо замовлення створено більше 24 годин тому». Casbin — популярна cross-language бібліотека для ABAC.

ReBAC (Relationship-Based Access Control) — Google Zanzibar model. Доступ визначається графом відносин: «користувач X є учасником команди Y, яка має доступ до проєкту Z». OpenFGA — open source реалізація від Okta.

Як ми це робимо: кейс із впровадження 2FA

Проєкт — платіжний шлюз для маркетплейсу. Потрібно було захистити доступ до операцій виводу коштів. Ми спроєктували систему:

• Основний пароль замінили на комбінацію пароль + TOTP (Google Authenticator). Використали otplib (Node.js) для генерації та верифікації кодів.
• Під час першого підключення 2FA показували QR-код (base32-encoded secret) і генерували 10 одноразових backup-кодів, хешованих bcrypt. Відображали коди лише один раз.
• Secret для TOTP зберігали у зашифрованому вигляді в базі даних (AES-256-GCM, ключ у AWS KMS).
• На стороні фронтенду інтегрували @simplewebauthn/browser для passkeys — біометрична аутентифікація як альтернатива паролю. Публічний ключ зберігали на сервері, private key на пристрої користувача.
• Результат: час на логін зріс на 5 секунд, але кількість зламаних акаунтів упала до нуля за пів року роботи. Гарантія безпеки — на рівні OWASP ASVS Level 2.

Також варто зазначити, що TOTP значно надійніше за SMS-верифікацію через SIM-swapping, тому для фінансових даних ми рекомендуємо TOTP або апаратні ключі.

Типові вразливості, які ми знаходимо

• Broken Object Level Authorization (BOLA/IDOR): /api/orders/12345 повертає замовлення без перевірки, чи належить воно поточному користувачу. Найпоширеніша вразливість API за OWASP. Кожен запит до ресурсу — перевірка через $user->can('view', $order).
• Mass Assignment: User::create($request->all()) — користувач передає is_admin: true в тілі запиту. Laravel вирішує через $fillable / $guarded, але часто забувають.
• Небезпечний CORS: Access-Control-Allow-Origin: * на API з авторизацією по cookie — credentials не передаються з wildcard origin, але якщо хтось зробив Allow-Credentials: true + Allow-Origin: * — це діра.

Penetration testing обов’язковий для продуктів з фінансовими даними або персональними даними користувачів. Ми проводимо аудит коду й інфраструктури на етапі приймання.

Що входить у роботу

Ми передаємо замовнику:

• Документацію архітектури авторизації (flow діаграми, опис токенів, політик доступу).
• Репозиторій із вихідним кодом, покритий unit- та integration-тестами.
• Конфігурацію для CI/CD (GitHub Actions/ GitLab CI) із перевірками безпеки.
• Доступи до середовищ (staging, production) із правами адміністратора.
• Інструкцію з експлуатації та супроводу.
• Підтримку після впровадження — 2 тижні безкоштовних консультацій.

Терміни та вартість

Базова аутентифікація (email/password + OAuth + JWT/сесії): 1–3 тижні. RBAC з детальними політиками доступу: 2–4 тижні. 2FA (TOTP + SMS): 1–2 тижні. WebAuthn/Passkeys: 2–3 тижні. Повна система аутентифікації для SaaS з multi-tenancy: 4–8 тижнів.

Вартість розраховується індивідуально залежно від обсягу та складності. Замовте консультацію — оцінимо ваш проєкт безкоштовно. Отримайте гарантію безпеки вашої авторизації користувачів.