Перейти к содержанию
29 минут чтения
Тема: Практика Laravel · Telegram Login · OpenID Connect · Авторизация

Как добавить вход через Telegram на сайт с Laravel

Для примера добавим на сайт кнопку «Войти через Telegram». Посетитель подтвердит вход в Telegram, вернётся на сайт и окажется в личном кабинете. При первом входе создадим аккаунт, при следующих найдём тот же аккаунт по проверенному идентификатору. Отдельно разберём привязку к уже существующему пользователю сайта, чтобы случайно не объединить чужие учётные записи.

Выберем актуальный способ авторизации

Используем серверный Authorization Code Flow с PKCE. Кнопка отправляет пользователя на страницу Telegram, callback получает короткоживущий код, а Laravel обменивает его на ID token. Подпись проверяет JWT-библиотека; сайт дополнительно проверяет назначение и параметры токена. Декодированный JSON без проверки подписи не даёт права войти.

Это Telegram Login для обычного сайта. Здесь не используется HMAC из старого iframe-виджета и не подходит проверка initData от Mini App. У Telegram Login есть также JavaScript-библиотека с popup, но серверный redirect позволяет показать весь путь без зависимости от связи окон браузера.

  • state связывает возврат с браузерной сессией, начавшей вход.

  • PKCE связывает код авторизации с секретным verifier, который остался на сервере.

  • nonce связывает ID token с конкретной попыткой входа.

  • Пара issuer + subject определяет внешнюю учётную запись. Username, имя и телефон для автоматического объединения аккаунтов не подходят.

Настроим Telegram и Laravel

Пример рассчитан на Laravel 13, PHP 8.3+, стандартную модель User и сессии Laravel. Понадобятся OpenSSL и mbstring. На существующем сайте встроите маршруты в текущую форму входа; не создавайте вторые /login и /logout. Для привязки к аккаунту с паролем ниже используется уже настроенный экран подтверждения пароля password.confirm, например из starter kit.

В Mini App BotFather выберите своего бота и раздел Login Widget. Добавьте Allowed URLs: origin сайта и точный callback. Для dev и production укажите отдельные адреса. Получите Client ID и Client Secret именно из настроек Login: это не токен Bot API. Оставьте алгоритм подписи RS256, поскольку код ниже принимает только его.

Allowed URLs · пример
https://example.com
https://example.com/auth/telegram/callback
https://dev.example.com
https://dev.example.com/auth/telegram/callback
Shell · зависимость и миграция
composer require firebase/php-jwt
php artisan make:migration create_telegram_identities_table
Laravel · .env
TELEGRAM_LOGIN_CLIENT_ID=CLIENT_ID_FROM_BOTFATHER
TELEGRAM_LOGIN_CLIENT_SECRET=CLIENT_SECRET_FROM_BOTFATHER
TELEGRAM_LOGIN_REDIRECT_URI=https://example.com/auth/telegram/callback
SESSION_DRIVER=database
CACHE_STORE=database
SESSION_SECURE_COOKIE=true
SESSION_HTTP_ONLY=true
SESSION_SAME_SITE=lax
PHP · добавить в массив config/services.php
'telegram_login' => [
    'client_id' => env('TELEGRAM_LOGIN_CLIENT_ID'),
    'client_secret' => env('TELEGRAM_LOGIN_CLIENT_SECRET'),
    'redirect_uri' => env('TELEGRAM_LOGIN_REDIRECT_URI'),
],

Таблицы sessions, cache и cache_locks должны существовать; они есть в стандартных миграциях нового Laravel-проекта. Блокировка сессии нужна, чтобы два callback одной попытки не выполнились одновременно. Не используйте cookie как драйвер сессии для этого примера. SameSite=Lax позволяет сессии вернуться при верхнеуровневом GET-переходе с Telegram.

Callback задаётся конфигурацией, а не заголовком Host и не return_url из браузера. Адрес должен совпасть с зарегистрированным, включая схему и путь. После настройки конфигурации в обычном процессе развёртывания обновите её кэш.

Подготовим связь с аккаунтом сайта

PHP · database/migrations/..._create_telegram_identities_table.php
<?php
declare(strict_types=1);
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        // Telegram Login does not provide an email address.
        Schema::table('users', function (Blueprint $table): void {
            $table->string('email')->nullable()->change();
        });
        Schema::create('telegram_identities', function (Blueprint $table): void {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->string('issuer', 64);
            $table->string('subject', 255);
            $table->char('subject_hash', 64)->unique();
            $table->unique('user_id');
            $table->timestamps();
        });
    }
    public function down(): void
    {
        Schema::dropIfExists('telegram_identities');
        // Keep email nullable: existing Telegram-only users may have no email.
    }
};
Shell · применить миграцию учебного приложения
php artisan migrate

Telegram не выдаёт email в этом потоке, поэтому для новой учётной записи он остаётся NULL. Не придумывайте адрес вида telegram-id@example.com: его можно ошибочно использовать для восстановления пароля. Если на сайте email обязателен, отправьте нового пользователя на отдельный шаг ввода и подтверждения адреса; доступ к разделам с verified должен зависеть от этого шага.

Уникальный subject хранится строкой. Для поиска и ограничения UNIQUE используем SHA-256 от issuer и subject с разделителем: так регистронезависимая сортировка строк в MySQL не объединит разные внешние идентификаторы. Subject не обязан совпадать с Telegram user id из profile, и превращать его в chat_id для sendMessage нельзя. В этом сценарии одного Telegram достаточно для одного аккаунта сайта; уникальность user_id также запрещает незаметно заменить привязанный Telegram другим.

PHP · app/Services/TelegramAccount.php
<?php
declare(strict_types=1);
namespace App\Services;

use App\Models\User;
use Illuminate\Database\UniqueConstraintViolationException;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Str;

final class TelegramAccount
{
    public function resolve(string $subject, string $name, ?int $linkTo): User
    {
        $subjectHash = hash('sha256', TelegramOidc::ISSUER."\0".$subject);
        try {
            return DB::transaction(function () use ($subject, $subjectHash, $name, $linkTo): User {
                $identity = DB::table('telegram_identities')->where('subject_hash', $subjectHash)->lockForUpdate()->first();
                if ($identity !== null) {
                    abort_if($linkTo !== null && (int) $identity->user_id !== $linkTo, 409, 'Telegram уже связан с другим аккаунтом');
                    return User::query()->whereKey($identity->user_id)->firstOrFail();
                }
                if ($linkTo !== null) {
                    $user = User::query()->lockForUpdate()->findOrFail($linkTo);
                    abort_if(DB::table('telegram_identities')->where('user_id', $linkTo)->exists(), 409, 'У аккаунта уже есть Telegram');
                } else {
                    $user = new User();
                    $user->forceFill(['name' => $name, 'email' => null,
                        'password' => Hash::make(Str::random(64))])->save();
                }
                DB::table('telegram_identities')->insert([
                    'user_id' => $user->getKey(), 'issuer' => TelegramOidc::ISSUER,
                    'subject' => $subject, 'subject_hash' => $subjectHash, 'created_at' => now(), 'updated_at' => now(),
                ]);
                return $user;
            });
        } catch (UniqueConstraintViolationException) {
            // A concurrent callback may have created the identity first.
            // The losing transaction (including a new User) has rolled back.
            $identity = DB::table('telegram_identities')->where('subject_hash', $subjectHash)->first();
            abort_if($identity === null || ($linkTo !== null && (int) $identity->user_id !== $linkTo), 409, 'Конфликт привязки');
            return User::query()->whereKey($identity->user_id)->firstOrFail();
        }
    }
}

Транзакция сохраняет пользователя и внешнюю идентичность вместе. Если два независимых входа одновременно создают одну связь, ограничение UNIQUE отклонит второй, его новая запись User откатится, а код найдёт уже существующую связь. Имя обновлять при каждом входе необязательно: в примере локальное имя существующего аккаунта не перезаписывается.

Обменяем код и проверим ID token

PHP · app/Services/TelegramOidc.php
<?php
declare(strict_types=1);
namespace App\Services;

use Firebase\JWT\JWK;
use Firebase\JWT\JWT;
use Illuminate\Support\Facades\Http;
use RuntimeException;

final class TelegramOidc
{
    public const ISSUER = 'https://oauth.telegram.org';

    private function setting(string $name): string
    {
        $value = config('services.telegram_login.'.$name);
        if (!is_string($value) || $value === '') {
            throw new RuntimeException('Missing Telegram Login setting');
        }
        return $value;
    }

    public static function base64url(string $bytes): string
    {
        return rtrim(strtr(base64_encode($bytes), '+/', '-_'), '=');
    }

    public function authorizationUrl(string $state, string $nonce, string $verifier): string
    {
        return self::ISSUER.'/auth?'.http_build_query([
            'client_id' => $this->setting('client_id'),
            'redirect_uri' => $this->setting('redirect_uri'),
            'response_type' => 'code', 'scope' => 'openid profile',
            'state' => $state, 'nonce' => $nonce,
            'code_challenge' => self::base64url(hash('sha256', $verifier, true)),
            'code_challenge_method' => 'S256',
        ], '', '&', PHP_QUERY_RFC3986);
    }

    /** @return array{sub:string,name:string} */
    public function exchange(string $code, string $verifier, string $nonce): array
    {
        $client = $this->setting('client_id');
        $response = Http::asForm()->acceptJson()->connectTimeout(3)->timeout(10)
            ->withBasicAuth($client, $this->setting('client_secret'))
            ->post(self::ISSUER.'/token', [
                'grant_type' => 'authorization_code', 'code' => $code,
                'client_id' => $client, 'code_verifier' => $verifier,
                'redirect_uri' => $this->setting('redirect_uri'),
            ]);
        // Do not throw an HTTP exception containing a token response body.
        if (!$response->successful() || !is_string($response->json('id_token'))) {
            throw new RuntimeException('Telegram token exchange failed');
        }
        $keys = Http::acceptJson()->connectTimeout(3)->timeout(5)
            ->get(self::ISSUER.'/.well-known/jwks.json');
        if (!$keys->successful() || !is_array($keys->json('keys'))) {
            throw new RuntimeException('Telegram keys unavailable');
        }
        $allowed = [];
        foreach ($keys->json('keys') as $key) {
            if (is_array($key) && ($key['kty'] ?? '') === 'RSA'
                && ($key['alg'] ?? 'RS256') === 'RS256' && ($key['use'] ?? 'sig') === 'sig') {
                $allowed[] = $key;
            }
        }
        // Algorithm is fixed to the RS256 setting chosen in BotFather.
        $claims = JWT::decode($response->json('id_token'), JWK::parseKeySet(['keys' => $allowed], 'RS256'));
        $now = time();
        if (($claims->iss ?? null) !== self::ISSUER || ($claims->aud ?? null) !== $client
            || !is_int($claims->exp ?? null) || $claims->exp <= $now
            || !is_int($claims->iat ?? null) || $claims->iat > $now + 30 || $claims->iat < $now - 600
            || !is_string($claims->nonce ?? null) || !hash_equals($nonce, $claims->nonce)
            || !is_string($claims->sub ?? null) || $claims->sub === '' || strlen($claims->sub) > 255) {
            throw new RuntimeException('Invalid Telegram identity claims');
        }
        return ['sub' => $claims->sub,
            'name' => is_string($claims->name ?? null) ? mb_substr($claims->name, 0, 100) : 'Пользователь Telegram'];
    }
}

HTTP-запрос к /token идёт с Basic Authorization и form-urlencoded; Client Secret остаётся на сервере. JWKS загружается только с фиксированного адреса Telegram. Алгоритм ограничен RS256: значение alg из неподтверждённого токена не выбирает алгоритм проверки за нас. Библиотека проверяет подпись и временные ограничения, затем код проверяет iss, aud, nonce и sub.

В этом примере принимается одна строка aud, равная Client ID, как в документированном ответе Telegram. Максимальный возраст iat — десять минут, независимо от более долгого exp. Поддерживайте время сервера через синхронизацию часов. Ключи загружаются при каждом входе, поэтому их ротация не требует перезапуска; при большом трафике добавьте небольшой кэш JWKS с обновлением по неизвестному kid.

Отдельного запроса UserInfo здесь нет: Telegram возвращает профиль в ID token. Access token не сохраняется, потому что для входа он дальше не нужен. Не логируйте код, Client Secret, ID token и тело ответа /token. Если обмен завершился таймаутом, начните новую попытку входа, а не повторяйте код авторизации бесконечно.

Свяжем кнопку, callback и сессию

PHP · app/Http/Controllers/TelegramLoginController.php
<?php
declare(strict_types=1);
namespace App\Http\Controllers;

use App\Services\TelegramAccount;
use App\Services\TelegramOidc;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Log;

final class TelegramLoginController extends Controller
{
    public function start(Request $request, TelegramOidc $oidc): RedirectResponse
    {
        $linkTo = $request->routeIs('telegram.link') ? (int) Auth::id() : null;
        $flow = ['state' => bin2hex(random_bytes(32)), 'nonce' => bin2hex(random_bytes(32)),
            'verifier' => TelegramOidc::base64url(random_bytes(32)), 'created' => time(), 'link_to' => $linkTo];
        $request->session()->put('telegram_login', $flow);
        return redirect()->away($oidc->authorizationUrl($flow['state'], $flow['nonce'], $flow['verifier']));
    }

    public function callback(Request $request, TelegramOidc $oidc, TelegramAccount $accounts): RedirectResponse
    {
        $flow = $request->session()->pull('telegram_login');
        $state = $request->query('state');
        if (!is_array($flow) || !is_string($state) || !is_string($flow['state'] ?? null)
            || !is_string($flow['nonce'] ?? null) || !is_string($flow['verifier'] ?? null)
            || !is_int($flow['created'] ?? null) || !array_key_exists('link_to', $flow)
            || ($flow['link_to'] !== null && !is_int($flow['link_to']))
            || !hash_equals($flow['state'], $state) || $flow['created'] < time() - 600) {
            abort(419, 'Начните вход заново');
        }
        if ($request->has('error')) {
            return redirect('/login')->with('status', 'Вход через Telegram отменён');
        }
        $code = $request->query('code');
        if (!is_string($code) || $code === '' || strlen($code) >= 4096) {
            abort(422);
        }
        $linkTo = $flow['link_to'];
        abort_if($linkTo !== null && (int) Auth::id() !== $linkTo, 403);
        abort_if($linkTo === null && Auth::check(), 409, 'Сессия изменилась. Начните заново');
        try {
            $identity = $oidc->exchange($code, $flow['verifier'], $flow['nonce']);
        } catch (\Throwable) {
            Log::warning('Telegram login could not be verified');
            return redirect('/login')->withErrors(['telegram' => 'Вход не подтверждён. Попробуйте ещё раз.']);
        }
        $user = $accounts->resolve($identity['sub'], $identity['name'], $linkTo);
        // Apply your existing suspended/deleted-account policy here before login.
        Auth::login($user);
        $request->session()->regenerate();
        $request->session()->regenerateToken();
        return redirect('/account');
    }
}
PHP · routes/web.php
<?php
// Add to routes/web.php; do not put these routes in stateless api.php.
use App\Http\Controllers\TelegramLoginController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Route;

Route::view('/login', 'auth.login')->middleware('guest')->name('login');
Route::post('/auth/telegram', [TelegramLoginController::class, 'start'])
    ->middleware(['guest', 'throttle:10,1'])->block(30, 10)->name('telegram.start');
Route::post('/account/telegram', [TelegramLoginController::class, 'start'])
    ->middleware(['auth', 'password.confirm', 'throttle:10,1'])->block(30, 10)->name('telegram.link');
Route::get('/auth/telegram/callback', [TelegramLoginController::class, 'callback'])
    ->middleware('throttle:20,1')->block(30, 10)->name('telegram.callback');
Route::view('/account', 'account')->middleware('auth');
Route::post('/logout', function (Request $request) {
    Auth::logout();
    $request->session()->invalidate();
    $request->session()->regenerateToken();
    return redirect('/login');
})->middleware('auth')->name('logout');
Blade · resources/views/auth/login.blade.php
<!doctype html><html lang="ru"><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Вход</title><h1>Войти в кабинет</h1>
@if (session('status')) <p>{{ session('status') }}</p> @endif
@error('telegram') <p role="alert">{{ $message }}</p> @enderror
<form method="post" action="{{ route('telegram.start') }}">
    @csrf
    <button type="submit">Войти через Telegram</button>
</form>
</html>
Blade · resources/views/account.blade.php
<!doctype html><html lang="ru"><meta charset="utf-8">
<title>Кабинет</title><h1>Здравствуйте, {{ auth()->user()->name }}</h1>
<p>Вы вошли в аккаунт сайта.</p>
<form method="post" action="{{ route('logout') }}">@csrf <button>Выйти</button></form>
</html>

Начало входа — POST с обычной CSRF-защитой Laravel. Callback — GET от Telegram; ему не нужен CSRF-токен формы, его проверка — state плюс одноразовая серверная попытка. После успеха regenerate меняет идентификатор сессии, а regenerateToken обновляет CSRF. Выход удаляет сессию и выполняется только POST.

После входа перенаправляем на фиксированный /account. Если нужно возвращать посетителя к заказу, заранее сохраните разрешённый внутренний путь в сессии и проверьте доступ к заказу после авторизации. Не перенаправляйте на произвольный URL из callback.

В демонстрации один браузер хранит одну активную попытку: новая кнопка входа заменяет предыдущую. Поэтому старый callback получит 419. Для нескольких вкладок можно хранить ограниченный набор попыток по state, но каждой всё равно нужны срок действия и однократное потребление.

Привяжем Telegram к существующему аккаунту

Если человек уже зарегистрирован через email, сначала предложите войти обычным способом и подтвердить пароль. Затем разместите в настройках аккаунта следующую форму. Она запускает тот же OIDC-поток, но сохраняет в сессии конкретный локальный user_id. На возврате проверяется, что пользователь всё ещё вошёл именно в него.

Blade · форма в настройках аккаунта
<form method="post" action="{{ route('telegram.link') }}">
    @csrf
    <button>Привязать Telegram к этому аккаунту</button>
</form>

Если внешний subject уже связан с другим локальным аккаунтом, верните конфликт и предложите разбор через поддержку. Совпадение имени, username или номера телефона не разрешает перенос привязки. Для смены Telegram создайте отдельный сценарий с повторной проверкой личности, а не удаляйте старую связь в callback автоматически.

Перед Auth::login примените действующую политику блокировки аккаунтов сайта. Если у вас есть suspended_at, запрет входа или обязательная двухфакторная проверка, Telegram не должен их обходить. У стандартной учебной модели этих полей нет, поэтому место применения собственной политики отмечено в контроллере.

Проверим успешный и ошибочные сценарии

  • Первый вход создаёт одну строку users и одну telegram_identities. Повторный вход возвращает того же User.

  • Неверные state, nonce, issuer, audience, подпись и истёкший exp не создают аккаунт и не авторизуют пользователя.

  • Повторный callback уже завершённой попытки отклоняется; ошибка пользователя error возвращает сообщение об отмене.

  • Попытка привязать Telegram, занятый другим аккаунтом, даёт 409 и не меняет связи.

  • Одинаковый username у локального и Telegram-пользователя не объединяет их автоматически.

  • После успешного входа ID сессии меняется, после logout кабинет недоступен.

  • Недоступность /token или JWKS даёт понятную ошибку и не приводит к входу по неподтверждённым данным.

Автотесты удобно строить через Http::fake: подпишите тестовый JWT отдельным RSA-ключом и отдайте соответствующий JWKS. Это проверяет реальную криптографическую валидацию, не обращаясь к Telegram и не создавая аккаунты посетителей. Настройку Allowed URLs, cookies и возврат между доменами дополнительно проверьте в браузере на своём тестовом аккаунте.

Где нужен BotGate и что читать дальше

OIDC-запросы отправляются к oauth.telegram.org и не подменяются Bot API-шлюзом. BotGate может понадобиться позже для сообщений бота пользователю. Право написать ему запрашивается отдельно: сам успешный вход не означает согласие на любую рассылку. Настройки сообщений разобраны в статье об уведомлениях.

Источники: актуальный Telegram Login, PHP-JWT, авторизация Laravel, сессии и блокировки. Для уже существующей связи сайта с ботом см. отдельный сценарий привязки.