Telegram Authentication for Website

Telegram Authentication Implementation for Websites

Telegram Login Widget lets users login to your site via their Telegram account without OAuth2 redirects. User clicks button, Telegram opens confirmation dialog, site receives signed data. No password, no email—just Telegram ID.

Unlike classic OAuth2, Telegram doesn't redirect to its site. Auth happens via:

1. Widget mode—JavaScript widget embedded on page
2. Redirect mode—link to t.me/BotName?start=auth

Signed data passes to client, which sends to server for verification.

Creating a Bot

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

Installing Widget

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

Parameter data-auth-url is where Telegram redirects with auth parameters. Parameter data-request-access="write" requests permission to send messages.

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

Verifying Signature on Server

Critical step. Telegram data is signed with HMAC-SHA256. Without verification, 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 not 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']);

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

Database Schema

Telegram doesn't provide email. Need telegram_id field (bigint, unique). Username can change—update on each login:

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

Timeline

Total: 2.5–3.5 days.