Перейти к содержанию
12 минут чтения
Тема: Практика Mini Apps · PHP · Laravel · Авторизация

Авторизация в Telegram Mini App на PHP и Laravel: проверка initData

Для примера у сервисного центра уже есть Mini App с формой заявки. Теперь клиент должен видеть свои обращения после входа, а сервер — отличать его от другого пользователя. Разберём проверку Telegram, создание сессии и выборку заявки по владельцу. Этот материал продолжает пример формы, но проверку подписи можно использовать отдельно.

Какие данные подтверждают личность

Telegram.WebApp.initData — исходная строка параметров, которую браузер передаёт вашему серверу. initDataUnsafe — уже разобранный объект для интерфейса. Отображать из него приветствие можно, выдавать по нему доступ к заказам нельзя: HTTP-запрос к серверу пользователь способен составить самостоятельно.

Проверка проходит в три этапа: подпись подтверждает происхождение данных, auth_date ограничивает время их использования, собственная сессия связывает последующие запросы с проверенным Telegram ID. Проверка роли или владельца конкретной заявки выполняется отдельно. Даже правильная подпись не означает, что человек — менеджер.

Используем запуск из кнопки меню личного чата, как в первой форме Mini App. Прямое открытие страницы вне Telegram не является входом. Не добавляйте обход с user_id из query string ради удобства отладки.

Проверяем initData на PHP

Ниже функция для PHP 8.3+ на 64-битной системе. Сохраните её в telegram-init-data.php вне public. Передайте токен именно того бота, из которого открывается приложение, и текущее время сервера. BOT_TOKEN храните в настоящем окружении PHP-процесса либо загружайте конфигурацию явно; обычный PHP не читает .env автоматически.

Из набора исключается hash, остальные значения сохраняются в исходном декодированном виде. Не разбирайте и не собирайте заново JSON user перед подписью: пробелы и экранирование влияют на HMAC. Поле signature, если оно присутствует, остаётся в строке для этого алгоритма с токеном. Отдельный алгоритм Ed25519 для сторонней проверки здесь не используется.

PHP · telegram-init-data.php
<?php
declare(strict_types=1);

function validateInitData(string $raw, string $token, int $now): int
{
    if ($raw === '' || strlen($raw) > 12000) {
        throw new DomainException('Invalid Telegram data');
    }
    $fields = [];
    foreach (explode('&', $raw) as $pair) {
        $parts = explode('=', $pair, 2);
        if (count($parts) !== 2) {
            throw new DomainException('Invalid Telegram data');
        }
        $key = urldecode($parts[0]);
        if (!preg_match('/^[a-zA-Z0-9_]+$/D', $key)
            || array_key_exists($key, $fields)) {
            throw new DomainException('Invalid Telegram fields');
        }
        $fields[$key] = urldecode($parts[1]);
    }
    $hash = $fields['hash'] ?? '';
    unset($fields['hash']);
    if (!preg_match('/^[a-f0-9]{64}$/D', $hash)) {
        throw new DomainException('Invalid Telegram hash');
    }
    ksort($fields, SORT_STRING);
    $lines = [];
    foreach ($fields as $key => $value) {
        $lines[] = $key.'='.$value;
    }
    $secret = hash_hmac('sha256', $token, 'WebAppData', true);
    $expected = hash_hmac('sha256', implode("\n", $lines), $secret);
    if (!hash_equals($expected, $hash)) {
        throw new DomainException('Invalid Telegram signature');
    }
    $date = $fields['auth_date'] ?? '';
    if (!ctype_digit($date) || (int) $date < $now - 600 || (int) $date > $now + 30) {
        throw new DomainException('Reopen the Mini App');
    }
    try {
        $user = json_decode($fields['user'] ?? '', true, 32, JSON_THROW_ON_ERROR);
    } catch (JsonException) {
        throw new DomainException('Invalid Telegram user');
    }
    if (!is_array($user) || !is_int($user['id'] ?? null) || $user['id'] <= 0) {
        throw new DomainException('Invalid Telegram user');
    }
    return $user['id'];
}

Десять минут допустимого возраста и тридцать секунд допуска в будущее — выбранные нами значения, а не обязательный срок Telegram. После истечения окна попросите переоткрыть приложение. Часы сервера должны быть синхронизированы. Пустые, повторяющиеся или неправильно подписанные параметры не должны приводить к созданию сессии.

Создаём сессию в обычном PHP

Для варианта на обычном PHP используйте одну HTTPS-origin для страницы и её обработчиков. До session_start включите session.use_strict_mode, а cookie задайте Secure, HttpOnly и SameSite=Lax. Не кладите токен бота или initData в cookie. Сервер хранит только проверенный ID, время окончания сессии и случайный CSRF-токен.

Следующий фрагмент выполняется в обработчике входа после проверки метода POST, размера тела и CSRF-токена предварительной сессии. Предварительную сессию создаёт сервер при выдаче страницы; её CSRF-токен страница отправляет в заголовке. Это предотвращает навязывание браузеру чужого входа. Не исключайте endpoint входа из защиты только потому, что он принимает initData.

PHP · Создание сессии после проверки запроса
<?php
declare(strict_types=1);
require __DIR__.'/telegram-init-data.php';
// The page and login handler use the same cookie settings.
ini_set('session.use_strict_mode', '1');
session_set_cookie_params([
    'secure' => true, 'httponly' => true, 'samesite' => 'Lax', 'path' => '/',
]);
session_start();
$csrf = $_SERVER['HTTP_X_CSRF_TOKEN'] ?? '';
if (!is_string($_SESSION['csrf'] ?? null) || $csrf === ''
    || !hash_equals($_SESSION['csrf'], $csrf)) {
    http_response_code(403);
    exit;
}
// $data is the validated JSON object from a size-limited POST body.
$token = getenv('BOT_TOKEN');
if (!is_string($token) || $token === '') {
    throw new RuntimeException('BOT_TOKEN is missing');
}
try {
    $userId = validateInitData($data['initData'], $token, time());
} catch (DomainException) {
    http_response_code(401);
    exit;
}
session_regenerate_id(true);
$_SESSION = [
    'telegram_user_id' => $userId,
    'expires_at' => time() + 1800,
    'csrf' => bin2hex(random_bytes(32)),
];

До этого фрагмента проверьте, что initData — непустая строка. После него верните JSON с новым CSRF-токеном и Cache-Control: no-store. На каждом защищённом запросе проверяйте expires_at; истёкшая сессия возвращает 401. При выходе очистите данные сессии и её cookie. Время жизни cookie само по себе не заменяет серверную проверку срока.

Подключаем ту же проверку в Laravel

Для Laravel 13 используйте PHP 8.3+; пример также опирается на обычные web-сессии, доступные в Laravel 11/12. Перенесите тело функции выше в App\Support\TelegramInitData: файл app/Support/TelegramInitData.php, namespace App\Support, final class TelegramInitData, метод public static function validate(string $raw, string $token, int $now): int. Алгоритм внутри не меняется.

Добавьте в возвращаемый массив config/services.php запись 'telegram' => ['bot_token' => env('BOT_TOKEN')]. Читайте токен через config, чтобы настройка работала и с кэшем конфигурации. Настройте рабочий session driver и Secure/HttpOnly cookie; примеры предполагают HTTPS и один origin. Для встроенного Telegram Web на другом origin отдельно проверьте ограничения third-party cookies: не ослабляйте их автоматически для всех клиентов.

Ниже фрагмент routes/web.php. Он предполагает таблицу leads с полями id, telegram_user_id, subject, status. Используем собственную сессионную идентичность Mini App; это не вход в стандартный Laravel guard и не привязка к существующему аккаунту по имени или email.

PHP · routes/web.php
<?php
use App\Support\TelegramInitData;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Route;

Route::post('/mini/session', function (Request $request) {
    $data = $request->validate(['initData' => ['required', 'string', 'max:12000']]);
    $token = config('services.telegram.bot_token');
    abort_unless(is_string($token) && $token !== '', 503);
    try {
        $id = TelegramInitData::validate($data['initData'], $token, time());
    } catch (\DomainException) {
        abort(401, 'Переоткройте Mini App');
    }
    $request->session()->invalidate();
    $request->session()->regenerateToken();
    $request->session()->put([
        'mini_user_id' => $id, 'mini_expires_at' => time() + 1800,
    ]);
    return response()->json(['csrf' => csrf_token()])->header('Cache-Control', 'no-store');
})->middleware('throttle:10,1');

Route::get('/mini/leads/{id}', function (Request $request, string $id) {
    $owner = $request->session()->get('mini_user_id');
    abort_unless(is_int($owner)
        && (int) $request->session()->get('mini_expires_at', 0) > time(), 401);
    $lead = DB::table('leads')->where('id', $id)
        ->where('telegram_user_id', $owner)->first(['id', 'subject', 'status']);
    abort_if($lead === null, 404);
    return response()->json($lead)->header('Cache-Control', 'no-store');
})->whereNumber('id')->middleware('throttle:60,1');

Route::post('/mini/logout', function (Request $request) {
    $request->session()->invalidate();
    $request->session()->regenerateToken();
    return response()->json(['csrf' => csrf_token()])->header('Cache-Control', 'no-store');
});

Для такого варианта выделите Mini App собственный host или приложение, если рядом есть кабинет с другим входом: invalidate очищает всю текущую сессию. При совместном размещении сначала спроектируйте связь двух идентичностей, чтобы вход в форму не завершал сессию менеджера.

Передаём данные из страницы и сохраняем CSRF

HTML выдаётся через Blade-маршрут с web middleware. Добавьте в head meta с csrf_token(), а скрипт Telegram подключите перед JavaScript приложения. POST входа остаётся под штатной CSRF-защитой Laravel. После смены сессии обновите токен в странице.

HTML · Фрагмент Blade-страницы
<meta name="csrf-token" content="{{ csrf_token() }}">
<script src="https://telegram.org/js/telegram-web-app.js?64"></script>
<script>
async function loginMiniApp() {
  const meta = document.querySelector('meta[name="csrf-token"]');
  const app = window.Telegram?.WebApp;
  if (!app?.initData) throw new Error('Откройте приложение из Telegram');
  const response = await fetch('/mini/session', {
    method: 'POST', credentials: 'same-origin',
    headers: {'Content-Type': 'application/json', 'Accept': 'application/json',
      'X-CSRF-TOKEN': meta.content},
    body: JSON.stringify({initData: app.initData})
  });
  if (!response.ok) throw new Error('Вход не подтверждён: ' + response.status);
  const result = await response.json();
  meta.content = result.csrf;
}
// Call on page initialization and handle rejection in the visible UI.
</script>

Все последующие изменения заявок и выход также отправляйте с текущим X-CSRF-TOKEN. При 419 обновите страницу, получив новую предварительную сессию; при 401 повторно откройте Mini App. Не выключайте middleware ради прохождения запроса. Серверу и reverse proxy задайте небольшой лимит размера тела: правило max для одного поля действует уже после разбора запроса.

Ограничиваем доступ к чужим заявкам

Идентификатор владельца берётся из проверенной сессии, а не из user_id в форме. В примере выборка одновременно ограничена ID заявки и владельцем; чужая запись выглядит как отсутствующая. Такое же условие требуется для изменения, удаления и скачивания вложений. Скрытая кнопка на странице доступа не ограничивает.

Если заявки принадлежат аккаунтам сайта, сначала создайте подтверждённую связь Telegram ID с аккаунтом. Совпадение username, имени или введённого email для привязки недостаточно. Роли менеджеров храните в своей базе и проверяйте отдельно через policy или сервис авторизации.

Подпись не делает initData одноразовым. До истечения auth_date украденная строка может быть повторно использована. Не записывайте её в URL, аналитику и журналы ошибок; защищайте страницу от XSS. Для платежей и других значимых действий дополнительно используйте серверный идентификатор операции. Повторный вход и повторное создание заявки — разные задачи.

Что проверить перед открытием доступа

  • Корректные данные создают новую сессию; неподписанный user_id этого не делает.

  • Подмена user, hash, дубликат ключа, старый и слишком будущий auth_date дают отказ.

  • Пользователь A не может получить, изменить или скачать вложение заявки B, даже зная её номер.

  • После выхода и истечения срока защищённые маршруты возвращают 401.

  • POST без CSRF отклоняется; после входа страница использует обновлённый токен.

  • Проверьте сохранение cookie в мобильном, настольном и веб-клиенте Telegram, которыми пользуется ваша аудитория.

BotGate и официальные источники

Вызовы Bot API можно отправлять через BotGate, но локальная проверка initData использует Telegram-токен. API-ключ BotGate и webhook_secret для неё не подходят. Сессии и права на заявки остаются частью вашего приложения.