Выберем актуальный способ авторизации
Используем серверный 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, поскольку код ниже принимает только его.
https://example.com https://example.com/auth/telegram/callback https://dev.example.com https://dev.example.com/auth/telegram/callback
composer require firebase/php-jwt php artisan make:migration create_telegram_identities_table
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
'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
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.
}
};
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
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
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
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
// 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');
<!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>
<!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. На возврате проверяется, что пользователь всё ещё вошёл именно в него.
<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, сессии и блокировки. Для уже существующей связи сайта с ботом см. отдельный сценарий привязки.