Перейти к основному содержимому

Вход через Telegram

XLADA умеет пускать администратора в панель по аккаунту Telegram. Тогда пароль для входа не нужен: панель отправляет вас на страницу Telegram, а после подтверждения выдаёт обычный JWT-токен. Это удобно для ежедневной работы и защищает от подбора пароля.

Вход через Telegram — это вход только для администратора панели. Он не имеет отношения к пользователям подписок и настраивается отдельно от бота для уведомлений.

Что нужно​

Настройка живёт в панели, в разделе Settings → Authentication → Telegram OAuth2. Понадобятся четыре значения:

ПолеЧто это
Включенопереключатель провайдера
Client IDидентификатор приложения Telegram
Client Secretсекрет приложения Telegram
Frontend Domainдомен панели без https://, например panel.example.com
Allowed IDsсписок числовых Telegram ID администраторов

Client ID и Client Secret выдаёт Telegram для вашего бота — это отдельные данные, не токен TELEGRAM_BOT_TOKEN. Домен панели должен быть настоящим FQDN: панель строит из него адрес возврата, и он должен совпадать с тем, что зарегистрирован для бота.

Адрес возврата, который нужно разрешить боту:

https://panel.example.com/api/auth/oauth2/callback/telegram
Совет

Скопируйте адрес возврата целиком, вместе с /api/auth/oauth2/callback/telegram. Если указать только домен, Telegram не сможет вернуть вас в панель.

В Allowed IDs добавьте числовые ID администраторов. Список обязателен: пока он пуст, провайдер включить нельзя, а вход не пройдёт ни для кого. ID — это число, а не имя пользователя.

Внимание

Если хотя бы одно из полей не заполнено — Client ID, Client Secret или Frontend Domain, — панель не включит Telegram OAuth2. Сохраняйте настройки и проверяйте вход сразу, чтобы не остаться без доступа.

Как проходит вход​

  1. Вы нажимаете вход через Telegram, и панель открывает страницу авторизации Telegram.
  2. Панель отправляет state и PKCE-проверку (code_verifier, метод S256); запрос использует области доступа openid, profile и telegram:bot_access.
  3. Telegram возвращает код на адрес возврата — тот самый /api/auth/oauth2/callback/telegram.
  4. Панель сверяет state и провайдера, обменивает код на токен и читает из ID-токена числовой ID пользователя.
  5. Если ID есть в Allowed IDs, панель выдаёт токен супер-администратора и записывает успешный вход в журнал.
Примечание

После подтверждения в панель входит первый администратор (супер-админ). Остальные администраторы через Telegram не входят — это сделано намеренно.

Ограничения​

  • Провайдер работает только по HTTPS: панель и так не запускается без обратного прокси с TLS.
  • Frontend Domain задаётся без схемы и без пути. Для локальной отладки допустимы localhost и 127.0.0.1.
  • Allowed IDs — единственный фильтр доступа. Если список пуст или в нём лишний ID, войти сможет не тот человек.
  • Провайдер можно включать вместе с паролем и другими способами входа — они не конфликтуют.

Безопасность​

Панель защищает вход несколькими механизмами:

  • state хранится в Valkey и живёт ограниченное время — подделать ответ Telegram без него нельзя;
  • используется PKCE, поэтому перехваченный код не превратится в токен;
  • доступ решает список ID, а не адрес почты или имя;
  • неудачные попытки входа фиксируются событием service.login_attempt_failed и попадают в Telegram и вебхуки;
  • пароль в такие уведомления не включается.
Осторожно

Client Secret — полноценный секрет. Он хранится в настройках панели и в открытом виде наружу не отдаётся. Не публикуйте его, не пересылайте в мессенджерах и не храните в репозитории. При утечке смените секрет в Telegram и в настройках.

Если вы отключили парольный вход и потеряли доступ к Telegram, войти поможет аварийный CLI: он умеет снова включить вход по паролю.

Что дальше​