Telegram аутентификация

Обзор Telegram аутентификации

Telegram аутентификация использует официальный Telegram Login Widget — механизм, предоставляемый Telegram для интеграции входа через Telegram в сторонние сервисы.

Создание Telegram бота

Для использования Telegram аутентификации необходимо создать бота через @BotFather в Telegram.

Пошаговая инструкция

1. Откройте Telegram и найдите бота @BotFather
2. Отправьте команду /newbot
3. Следуйте инструкциям:
   • Введите отображаемое имя бота (например: "Моя Компания Login")
   • Введите username бота (должен заканчиваться на bot, например: mycompany_login_bot)
4. BotFather создаст бота и выдаст токен — сохраните его, он понадобится для настройки в IDENTYX
5. Отправьте команду /setdomain и выберите созданного бота
6. Укажите домен вашей системы IDENTYX (например: mycompany.ru)

Настройка в IDENTYX

После создания бота настройте Telegram аутентификацию в IDENTYX.

Пошаговая настройка

1. Войдите в IDENTYX как администратор
2. Перейдите в раздел Настройки → Настройки
3. Раскройте раздел Авторизация → Telegram
4. Установите флажок Включить аутентификацию через Telegram
5. Заполните поле Имя бота (username) — введите username вашего бота без символа @ (например: mycompany_login_bot)
6. Заполните поле Токен бота — введите токен, полученный от BotFather
7. Нажмите кнопку Сохранить внизу страницы

Автоматическая регистрация

IDENTYX может автоматически создавать учетные записи для пользователей, входящих через Telegram впервые.

Настройка автоматической регистрации

1. В разделе Telegram настроек установите флажок Разрешить автоматически регистрировать учетные записи
2. В поле Группы для автодобавления выберите группы, в которые будут автоматически добавляться новые пользователи
3. Сохраните настройки

Процесс автоматической регистрации

При первом входе через Telegram система:

• Создает новую локальную учетную запись
• Устанавливает отображаемое имя из данных Telegram:
  • Если доступны имя и фамилия — использует их
  • Если доступен только username — использует @username
  • Если ничего нет — устанавливает "Telegram User"
• Генерирует случайный логин и пароль (пользователь не сможет войти по паролю без явной настройки)
• Привязывает Telegram ID к созданной учетной записи
• Добавляет пользователя в указанные группы
• Логирует все действия в журнал событий

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

Пользователи могут привязать свой Telegram аккаунт к уже существующей учетной записи в IDENTYX.

Привязка через профиль пользователя

1. Войдите в систему под своей учетной записью
2. Перейдите в Профиль пользователя (кнопка с вашим именем в правом верхнем углу)
3. Найдите раздел Методы авторизации
4. Найдите карточку Telegram
5. Нажмите кнопку Привязать
6. Откроется окно Telegram Login Widget — подтвердите вход
7. После успешной привязки статус изменится на "Подключено"

Отвязка Telegram аккаунта

Чтобы отвязать Telegram от учетной записи:

1. Перейдите в Профиль пользователя
2. Найдите карточку Telegram в разделе Методы авторизации
3. Нажмите кнопку Отвязать
4. Подтвердите действие

Использование Telegram для входа

Процесс входа

1. Откройте страницу входа в IDENTYX
2. Найдите кнопку Telegram в разделе альтернативных методов входа
3. Нажмите на кнопку
4. Откроется окно Telegram Login Widget
5. Подтвердите вход в Telegram (если требуется)
6. Система автоматически выполнит вход в IDENTYX

Требования для входа

Для успешного входа через Telegram:

• Telegram должен быть привязан к учетной записи IDENTYX
• В настройках пользователя должен быть разрешен вход через Telegram (флаг allow_enter_by_telegram)
• Учетная запись не должна быть заблокирована

Безопасность Telegram аутентификации

Проверка подписи

IDENTYX проверяет подлинность данных, полученных от Telegram, используя криптографическую подпись:

• Все данные от Telegram содержат параметр hash
• Система вычисляет контрольную подпись на основе токена бота и полученных данных
• Используется алгоритм HMAC-SHA256
• Ключ подписи = SHA256(токен бота)
• Если подписи не совпадают — вход отклоняется

Ограничение срока действия

Данные аутентификации от Telegram имеют ограниченный срок действия:

• Telegram передает параметр auth_date — время создания токена
• IDENTYX проверяет, что с момента создания токена прошло не более 24 часов
• Если токен устарел — вход отклоняется

Защита от дубликатов

Система предотвращает привязку одного Telegram аккаунта к нескольким учетным записям IDENTYX:

• Каждый Telegram ID может быть привязан только к одной учетной записи
• При попытке привязать уже используемый Telegram ID система выдаст ошибку

Логирование событий

Все события, связанные с Telegram аутентификацией, записываются в журнал:

• Успешная аутентификация
• Неудачная аутентификация (с указанием причины)
• Привязка Telegram к учетной записи
• Отвязка Telegram от учетной записи
• Автоматическая регистрация нового пользователя
• Отказ во входе (например, если флаг allow_enter_by_telegram отключен)

Часто задаваемые вопросы

Что такое username бота и где его взять?

Username бота — это уникальное имя, которое вы указываете при создании бота через @BotFather. Оно обязательно заканчивается на bot (например: mycompany_login_bot). Вы можете посмотреть username в профиле бота в Telegram.

Безопасно ли хранить токен бота в IDENTYX?

Да. Токен бота хранится в зашифрованном виде в базе данных и используется только для проверки подписи данных от Telegram. Никакие API-запросы к Telegram не выполняются.

Можно ли привязать один Telegram к нескольким учетным записям?

Нет. Каждый Telegram аккаунт может быть привязан только к одной учетной записи IDENTYX. Это сделано для безопасности и предотвращения конфликтов.

Что делать, если пользователь потерял доступ к Telegram?

Если Telegram был единственным методом входа:

• Администратор может установить пароль для учетной записи
• Или администратор может отвязать старый Telegram и привязать новый
• Или настроить другие методы аутентификации (LDAP, внешние провайдеры)

Кнопка Telegram не отображается на странице входа

Проверьте следующее:

• Включена ли аутентификация через Telegram в настройках
• Правильно ли указан username бота (без символа @)
• Сохранены ли настройки
• Настроен ли домен бота через команду /setdomain в BotFather

Как узнать, что пользователь был создан автоматически?

В журнале событий будет запись с текстом "Пользователь автоматически создан при первой аутентификации в системе через Telegram".

Откуда берется отображаемое имя при автоматической регистрации?

Telegram передает данные пользователя:

• first_name — имя
• last_name — фамилия (если указана)
• username — username в Telegram (если указан)

Система формирует отображаемое имя в следующем порядке приоритета:

1. Имя + Фамилия (если оба указаны)
2. @username (если указан)
3. "Telegram User" (если ничего не указано)

Задачи администратора

Разрешение входа через Telegram для конкретного пользователя

Администратор может явно разрешить или запретить вход через Telegram для пользователя:

1. Перейдите в раздел Пользователи → Локальные пользователи
2. Найдите нужного пользователя и откройте его карточку
3. В разделе настроек доступны параметры методов аутентификации
4. Управляйте флагом разрешения входа через Telegram

Принудительная отвязка Telegram

Администратор может отвязать Telegram от учетной записи пользователя через управление пользователями или напрямую в базе данных (для опытных администраторов).