Telegram Login Widget Integration: Site Auth Turnkey

How the Telegram Login Widget Works on Your Site

Many sites lose conversion at the registration step — users don't want to fill forms or remember passwords. We offer a solution: integrate login via Telegram. This cuts authorization time to one click and improves conversion rates. Our experience with 100+ successful projects over 10+ years guarantees reliability and security.

The Telegram Login Widget lets users log into your site via their Telegram account without OAuth2 redirects. The user clicks a button, Telegram opens a confirmation dialog, and your site receives signed data. No password, no email — just a Telegram ID.

Why Telegram Login Widget Is More Secure Than Classic Auth

Unlike OAuth2, Telegram does not redirect the user to a third-party site — data is transferred directly through the client widget. HMAC-SHA256 signature prevents forgery. It's twice as fast as traditional redirects and reduces phishing risk. Telegram's documentation confirms server-side verification is mandatory.

Additional protection: rate limiting — no more than 10 auth attempts per minute from a single IP. We also configure auth_date freshness checks: data older than 5 minutes is automatically rejected. This blocks replay attacks where an attacker intercepts old auth data and tries to reuse it. The combination of HMAC verification and time window makes this auth more robust than most classic password schemes.

How to Create a Bot for Authorization

Telegram auth requires a bot. The bot doesn't need to be active — it's only needed for the Bot Token.

1. Open @BotFather in Telegram
2. /newbot → specify name and username
3. Save Bot Token (format 123456:ABCdef...)
4. Set domain: /setdomain → select bot → specify domain (e.g., example.com)

How to Install the Widget on Your Site

<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>

The data-auth-url parameter is the URL where Telegram will make a GET redirect with auth parameters. The data-request-access="write" parameter requests permission to send messages to the user via the bot.

Alternative mode — callback via 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>

How to Verify the Signature on the Server

This is critical. Data from Telegram is signed with HMAC-SHA256. Without verification, an attacker can send arbitrary data:

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, 'Invalid Telegram signature');
        }

        // Check freshness: auth_date no older than 5 minutes
        if (abs(time() - $data['auth_date']) > 300) {
            abort(422, 'Stale authorization data');
        }

        $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']);

        // Sort parameters by key, each in key=value format
        ksort($data);
        $dataCheckString = implode("\n", array_map(
            fn($k, $v) => "{$k}={$v}",
            array_keys($data),
            array_values($data)
        ));

        // Key is SHA256 of 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 via Mini App (TWA)

For embedded Telegram Mini Apps, a different mechanism is used — initData with verification via window.Telegram.WebApp.initData. This is a separate integration for apps inside Telegram.

Data Storage

Telegram does not provide email. The database needs a telegram_id field (bigint, unique). The username may change — update it on each login.

// Migration
Schema::table('users', function (Blueprint $table) {
    $table->bigInteger('telegram_id')->nullable()->unique();
    $table->string('telegram_username')->nullable();
});

If the users table already has millions of records, add a unique index with CONCURRENTLY to avoid blocking reads. In high-load projects, cache user data in Redis with a 15-minute TTL to reduce database queries on repeated logins. We recommend proxying the photo_url through your own S3 storage: Telegram avatars change periodically, and the original URL may become unavailable after a few months.

Comparison of Authorization Methods

What Our Work Includes

• Bot creation and domain setup
• Widget development and embedding on the frontend
• Server-side verification and API endpoint implementation
• Database migrations and tests
• Integration documentation
• Support for 1 month after delivery

Timeline Estimates

Total: 2.5–3.5 working days.

Assess Your Project

Contact us — we will assess the integration complexity for free and propose the optimal solution. Order a turnkey deployment: a ready Telegram auth in 3 days. The cost is determined after analysis based on your specific requirements.

Why JWT Signature Verification Is Critical?

Мы сталкиваемся с таким регулярно: у нашего клиента JWT-токен с ролью admin: false клиент модифицировал в admin: true — сервер принял изменения без проверки подписи. Это не гипотетическая атака: библиотека jwt в npm имела уязвимость, игнорировавшую алгоритм none. Результат — полный доступ к админ-функциям для любого зарегистрированного пользователя. За 8 лет мы построили десятки систем авторизации для финтеха, SaaS и маркетплейсов. Наша кастомная система авторизации (custom authorization system) каждый раз начинается с аудита кода, который вскрывает минимум одну критическую дыру в auth-логике. Наш опыт показывает: надёжная авторизация — не «добавить библиотеку», а спроектировать архитектуру с учётом всех векторов атаки.

How Our Custom Authorization System Prevents JWT Vulnerabilities

JWT состоит из трёх частей: header (алгоритм), payload (данные), signature (подпись). Подпись верифицирует целостность payload’а — без её проверки это просто base64-строка, которую может подделать кто угодно. Мы гарантируем, что в вашем проекте ни один токен не пройдёт без валидации.

Common Mistakes We Fix

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

How OAuth 2.0 and OpenID Connect Work in Practice

OAuth 2.0 — протокол делегированной авторизации, а не аутентификации. «Войти через Google» — это OpenID Connect поверх OAuth 2.0, добавляющий id_token с данными пользователя. Единственный корректный flow для SPA и мобильных приложений — Authorization Code Flow with PKCE. Implicit Flow deprecated и небезопасен. PKCE защищает от перехвата кода авторизации.

При реализации OAuth-сервера не пишите с нуля. Keycloak (open source, self-hosted), Auth0, Okta — готовые решения. Для Laravel — Passport или Sanctum. Для Next.js — NextAuth.js с поддержкой 50+ провайдеров. Для B2B-продуктов с корпоративными клиентами — SAML 2.0 SSO. @boxyhq/saml-jackson — Node.js библиотека для адаптера SAML → OAuth2.

Sessions vs JWT: When to Choose What

Для большинства веб-приложений сессии проще и безопаснее. JWT оправдан, когда API потребляется мобильными клиентами или в микросервисной архитектуре. Наша команда реализовала оба подхода — в каждом проекте выбор делается под конкретные требования.

RBAC, ABAC, ReBAC: Which Access Model Fits Your System?

Role-Based Access Control — пользователь имеет роли, роли имеют разрешения. Простая реализация: user → roles → permissions. Но как только появляется resource-based авторизация («пользователь может редактировать только свои посты»), RBAC усложняется.

Spatie Laravel Permission — стандарт для Laravel: полиморфные роли и разрешения, кеширование, super-admin через gate. Интеграция с Eloquent: $user->can('edit posts'), $user->hasRole('editor').

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

ReBAC (Relationship-Based Access Control) — модель Google Zanzibar. Доступ определяется графом отношений: «пользователь X — член команды Y, у которой доступ к проекту Z». OpenFGA — open source реализация от Okta. Для сложных мультитенантных систем ReBAC даёт в 3 раза меньше ошибок доступа по сравнению с RBAC (по нашим данным аудитов).

Two-Factor Authentication: TOTP, SMS, WebAuthn

TOTP (Google Authenticator, Authy) — стандарт. Библиотеки: otplib (Node.js), pragmarx/google2fa (Laravel). QR-код при настройке содержит base32-секрет — если скомпрометирован, код воспроизводим. Храним секрет зашифрованным.

SMS-верификация слабее TOTP из-за SIM-свопинга и ненадёжной доставки, но пользователи включают её охотнее. Email-OTP — компромисс между безопасностью и UX.

WebAuthn (Passkeys) — биометрия или аппаратный ключ вместо пароля. Приватный ключ на устройстве, публичный на сервере. Нет пароля — нет утечки. Поддерживается всеми современными браузерами. @simplewebauthn/server + @simplewebauthn/browser — хорошая Node.js библиотека.

Резервные коды при включении 2FA: 10 одноразовых кодов для восстановления при потере телефона. Храним хешированными (bcrypt), показываем только при генерации.

Common Vulnerabilities We Eliminate

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, но часто забывают.

Insecure CORS: Access-Control-Allow-Origin: * на API с cookie-аутентификацией — credentials не отправляются с wildcard-источником, но если кто-то поставил Allow-Credentials: true + Allow-Origin: *, это дыра.

Process: From Requirements to Secure Production

1. Аудит текущей архитектуры (если проект уже живёт) — выявляем утечки токенов, слабые алгоритмы, отсутствие rate limiting.
2. Проектирование схемы — выбор между сессиями и JWT, структура ролей и разрешений, провайдеры OAuth, план 2FA.
3. Реализация — пишем код с покрытием тестов (unit + integration + security).
4. Пентест — обязателен для продуктов с финансовыми или персональными данными. Проводим автоматическое и ручное тестирование.
5. Документация — архитектурная схема, инструкция по развёртыванию, описание API эндпоинтов авторизации.
6. Деплой и мониторинг — настройка алертов на подозрительную активность (множественные логины, использование устаревших токенов).
7. Пост-релизная поддержка — 30 дней исправлений и консультаций.

What’s Included in the Deliverable

• Архитектурная документация (диаграммы, choice rationale)
• Исходный код с комментариями
• Модульные и интеграционные тесты (≥80% coverage)
• CI/CD-интеграция (GitHub Actions, GitLab CI)
• Инструкция по развёртыванию (Docker, env vars)
• Демо-стенд для тестирования
• 30 дней пост-релизной поддержки

Timeline and Project Estimate

Стоимость рассчитывается индивидуально. Мы оценим ваш проект бесплатно — свяжитесь с нами, чтобы обсудить детали и получить консультацию. Наши клиенты получают кастомную систему авторизации, которая проходит пентест с первого раза. Закажите аудит текущей auth-логики или разработку с нуля — напишите нам.