Настройка двухфакторной авторизации через собственный сервер OTP#

При выборе этого способа сервер RuDesktop не генерирует одноразовый пароль сам, а обращается по HTTP к стороннему сервису: просит его отправить код пользователю, а затем — проверить введённый код

Способ подходит, когда одноразовые пароли уже выдаёт внешняя система (корпоративное решение 2FA, собственный шлюз рассылки, внутренний сервис аутентификации) и требуется использовать её вместо встроенных каналов RuDesktop

Важно

Способ доступен только на локальном сервере RuDesktop. В облачной версии он не отображается ни в настройках, ни в списке методов пользователя

Как это работает#

Сервер RuDesktop выполняет POST-запрос на указанный URL с телом в формате JSON и ожидает ответ 2xx с телом {"ok": true}

Запрос отправляется дважды за одну авторизацию:

  1. Отправка кода — когда пользователь запрашивает одноразовый пароль. Сторонний сервис должен сгенерировать код и доставить его пользователю выбранным им способом

  2. Проверка кода — когда пользователь ввёл код. Сторонний сервис должен сверить его и ответить, верен ли код

Важно

Одноразовый пароль целиком на стороне внешнего сервиса: RuDesktop его не генерирует, не хранит и не проверяет. Срок жизни кода, его длину и способ доставки определяет сам сервис

Формат запроса#

Тело запроса — JSON со следующими полями:

Поле

Описание

action

send — отправить код пользователю, verify — проверить введённый код

username

Логин пользователя в RuDesktop

full_name

Полное имя пользователя из профиля

email

E-Mail из профиля

phone

Номер телефона из профиля

telegram_chat_id

ID чата Telegram из профиля

max_chat_id

ID чата MAX из профиля

otp

Введённый пользователем код. Передаётся только при action: verify

manager_username

Логин администратора, инициировавшего отправку. Передаётся только при регистрации ключа из веб-интерфейса

Подсказка

Контактные поля передаются, чтобы внешний сервис сам выбрал канал доставки кода. Пустые значения передаются как пустые строки

Формат ответа#

Запрос считается успешным, если одновременно выполнены оба условия:

  • HTTP-код ответа — успешный (2xx)

  • тело ответа — корректный JSON, в котором поле ok равно true

Во всех остальных случаях (ошибка сети, код ответа 4xx/5xx, нечитаемый JSON, ok не равно true) операция завершается ошибкой: при отправке пользователь увидит сообщение о невозможности запроса, при проверке — отказ во входе

Важно

Таймаут запроса — 5 секунд. Если внешний сервис не ответил за это время, запрос считается неуспешным

Ограничение частоты отправки#

Запросить отправку кода можно не более 3 раз за 5 минут для одного пользователя. При превышении лимита выводится сообщение с указанием, через сколько минут можно повторить попытку

Настройка на сервере#

Общий URL для всех пользователей#

  1. Перейти в Администрирование → Настройки → Настройки собственного сервера OTP:

    • В поле URL собственного сервера OTP указать адрес сервиса, например https://otp.example.com/rudesktop

  2. Перейти в Администрирование → Настройки → Аутентификация:

    • Активировать чек-бокс Использовать URL собственного сервера OTP из настроек при отправке OTP для всех пользователей

  3. Сохранить настройки, нажав Сохранить

Подсказка

При включённой опции URL из профиля пользователя не используется — все запросы уходят на общий адрес из настроек. При регистрации ключа поле ввода URL заменяется подписью «Будет использован общий URL собственного сервера OTP»

Важно

Принимаются только адреса со схемой http или https. Некорректный адрес не будет сохранён

Включение двухфакторной авторизации#

Способ 1. Только для конкретных пользователей#

Глобально 2FA на сервере включать не нужно. Достаточно зарегистрировать ключ в профиле нужного пользователя:

  1. Открыть профиль пользователя в Организация → Пользователи

  2. Перейти на вкладку Безопасность аккаунта

  3. Добавить ключ типа Собственный сервер OTP

  4. Указать URL собственного сервера OTP — адрес сервиса, обслуживающего этого пользователя

    Подсказка

    Поле не отображается, если включена опция использования общего URL из настроек сервера

  5. Нажать кнопку запроса одноразового пароля — сервер обратится к внешнему сервису с action: send

  6. Ввести полученный код и подтвердить — сервер проверит его запросом с action: verify и сохранит ключ

После этого при входе только у этого пользователя будет запрошен второй фактор через внешний сервис. Остальные пользователи войдут без 2FA

Способ 2. Для всех пользователей сервера#

  1. Перейти в Администрирование → Настройки → Аутентификация

  2. В поле Двухфакторная авторизация выбрать Собственный сервер OTP

  3. Сохранить настройки, нажав Сохранить

После этого 2FA через внешний сервис станет обязательной для всех пользователей сервера. Пользователи, у которых ключ ещё не зарегистрирован, при первом входе будут проведены через мастер регистрации

Подсказка

Чтобы не указывать адрес в профиле каждого пользователя, заранее включите опцию Использовать URL собственного сервера OTP из настроек при отправке OTP для всех пользователей

Аварийное отключение#

Если возникают проблемы и пройти двухфакторную авторизацию невозможно, выполните на сервере команду:

rude constance set TWO_FACTOR "off"

Диагностика#

Ошибки обращения к внешнему сервису записываются в лог сервера. Наиболее частые причины отказа:

  • «URL собственного сервера OTP не задан» — адрес не указан ни в профиле пользователя, ни в настройках сервера при включённой опции общего URL

  • «Введите корректный URL собственного сервера OTP» — адрес указан не по схеме http/https либо синтаксически неверен

  • «Не удалось выполнить запрос к собственному серверу OTP» — сервис недоступен, не ответил за 5 секунд или вернул ошибочный HTTP-код

  • «Собственный сервер OTP вернул некорректный ответ» — тело ответа не является корректным JSON

  • «Собственный сервер OTP отклонил запрос» — сервис ответил, но поле ok в ответе не равно true. При проверке кода это означает, что код неверен

  • «Собственный сервер OTP не настроен» — у пользователя нет включённого ключа этого типа