Как добавить двухфакторную аутентификацию в приложение

Чтобы добавить двухфакторную аутентификацию (2FA) в приложение, позвольте пользователям подключить приложение-аутентификатор, отсканировав QR-код, и запрашивайте шестизначный код, который оно показывает, после пароля. Создавайте полноценную сессию на сервере только после того, как код проверен. Каждому пользователю выдавайте одноразовые резервные коды при включении 2FA, ограничивайте число попыток подбора и требуйте пароль плюс текущий код для отключения 2FA. Если вы используете размещённого провайдера аутентификации, включите его встроенную многофакторную защиту вместо собственной реализации.

Этот гайд проходит через выбор вариантов, точный порядок действий, промпты для ИИ-конструктора и ошибки, из-за которых 2FA есть на словах, но ничего не защищает. Если концепция новая, начните с что такое двухфакторная аутентификация.

Перед началом: нужен рабочий вход

2FA работает поверх существующего входа. Сначала нужно одно из двух:

• Собственный вход, с пользователями и хешированными паролями в базе данных вашего приложения.
• Размещённый провайдер аутентификации, который управляет пользователями за вас.

Если у вас пока нет ни того, ни другого, начните с как добавить вход в приложение. Остальной гайд предполагает, что шаг с паролем уже работает.

Выберите второй фактор

TOTP расшифровывается как time-based one-time password, то есть одноразовый пароль по времени, — стандарт (RFC 6238), который используют приложения-аутентификаторы. Ваш сервер и телефон пользователя разделяют секрет; каждый из них по этому секрету и текущему времени формирует один и тот же короткий код, обычно меняющийся каждые 30 секунд. Ни сети, ни SMS-провайдер не нужны.

Ключи доступа (passkeys) заменяют или дополняют пароль криптографическим ключом, который хранится на устройстве пользователя. Они надёжнее, но их сложнее построить самостоятельно, поэтому многие приложения начинают с TOTP и добавляют ключи позже или берут их у провайдера аутентификации.

Собирать самим или включить?

Проверьте актуальную документацию провайдера: какие факторы он поддерживает и на каких тарифах. В любом случае не пишите математику генерации кодов сами; используйте широко известную библиотеку.

Сначала решите политику

Ответьте на эти вопросы до промптов, потому что от них зависит дизайн:

1. Кому это обязательно? Необязательно всем, обязательно администраторам и сотрудникам или обязательно всем. Обязательность для тех, у кого есть админские права, — распространённый выбор. См. ролевой контроль доступа.
2. Как часто пользователь вводит код? При каждом входе или раз в 30 дней на устройстве («запомнить это устройство»).
3. Какие действия требуют повторной проверки? Смена email, реквизитов для выплат или отключение 2FA — хорошие кандидаты. Это называется step-up аутентификацией.
4. Каков процесс при потере телефона? Резервные коды плюс ручной запасной вариант, который вы готовы выполнять.

Пошагово: TOTP 2FA на собственном входе

1. Сохраните нужные поля

У каждого пользователя нужны: признак включённой 2FA, TOTP-секрет (зашифрованный в хранилище, а не открытым текстом), время включения и список резервных кодов, которые хранятся в виде хешей, как пароли. Добавьте место для подсчёта неудачных попыток.

2. Подключение

1. Пользователь открывает настройки и нажимает «Включить двухфакторную аутентификацию».
2. Сервер генерирует новый секрет и возвращает его в виде QR-кода, а также текстовой версией для тех, кто не может отсканировать.
3. Пользователь сканирует код в приложении-аутентификаторе и вводит текущий код.
4. Сервер проверяет код. Только если он верный, сохраняется секрет и 2FA помечается как включённая.
5. Приложение один раз показывает 8–10 резервных кодов и просит пользователя их сохранить.

Шаг 4 важен: если включить 2FA до подтверждения кода, то у тех, кто неверно отсканировал, при следующем входе не получится войти.

3. Вход со вторым шагом

1. Пользователь вводит email и пароль. Сервер их проверяет.
2. Если 2FA включена, сервер не создаёт полноценную сессию. Вместо этого он создаёт короткоживущее состояние «второй фактор ожидается».
3. Приложение показывает экран ввода кода. Сервер проверяет код, допуская небольшое окно на расхождение часов.
4. Только теперь сервер выдаёт настоящую сессию.

Каждый защищённый маршрут и API-эндпоинт должен отклонять состояние ожидания. Экран 2FA, который только скрывает страницы в браузере, можно обойти, вызвав API напрямую.

4. Ограничения и уведомления

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

5. Восстановление и отключение

• Резервный код работает один раз, затем удаляется.
• Для отключения 2FA нужны пароль и текущий код или резервный код.
• Перевыпуск резервных кодов делает старый набор недействительным.
• Отправляйте пользователю письмо каждый раз, когда 2FA включается или выключается.

Промпты для ИИ-конструктора

Начните с основного потока:

Добавь необязательную двухфакторную аутентификацию с приложениями-аутентификаторами (TOTP) в наш существующий вход по email и паролю. Используй известную библиотеку TOTP, не пиши алгоритм сам. В настройках покажи QR-код и текстовый секрет, а 2FA включай только после ввода верного кода. Храни секрет в зашифрованном виде и больше не показывай его после настройки. Покажи 10 одноразовых резервных кодов один раз и храни их в виде хешей.

Затем принуждение, где сгенерированный код чаще всего подводит:

Принуди 2FA на сервере. После верного пароля пользователи с включённой 2FA получают короткоживущее состояние ожидания, а не полноценную сессию. Каждая защищённая страница и API-маршрут должны отклонять состояние ожидания. Ограничь число попыток ввода кода до 5, затем блокируй второй шаг на 15 минут и отправляй пользователю письмо.

Затем политика:

Требуй 2FA для аккаунтов администраторов: администратор без 2FA направляется в настройку и не может попасть в панель, пока не завершит её. Для отключения 2FA или смены email аккаунта требуй пароль и текущий код. Отправляй пользователю письмо, когда 2FA включается или выключается.

Наконец, попросите агента объяснить, что он построил:

Перечисли каждый маршрут, который проверяет, что второй фактор пройден, где хранятся TOTP-секрет и резервные коды и как они защищены.

Частые ошибки

• Сессия выдаётся после пароля. Самая серьёзная ошибка. Если полноценная сессия существует до проверки кода, 2FA — это декорация. Проверьте, вызвав защищённый API только после шага с паролем.
• Нет ограничения попыток. Неограниченные догадки делают код подбираемым.
• Секреты и резервные коды открытым текстом. Утечка базы тогда отдаёт второй фактор всех пользователей.
• Включение до проверки. Пользователи, которые неверно отсканировали код, оказываются заблокированы при следующем входе.
• Нет пути восстановления. Каждый потерянный телефон превращается в обращение в поддержку или потерянного клиента.
• Слишком лёгкое отключение. Если украденная сессия может отключить 2FA без кода, защиты больше нет.
• Коды в логах. Убедитесь, что коды и секреты никогда не попадают в серверные логи или сообщения об ошибках.
• Проверка только на странице входа. Сброс пароля, вход по «волшебной ссылке» и вход через соцсети тоже должны учитывать 2FA, иначе они станут обходом.

Чек-лист тестирования

• Подключение завершается только после верного кода
• Вход с верным паролем, но без кода не даёт доступа ни к одной защищённой странице или API
• Неверный код отклоняется; повторные неверные коды запускают блокировку и письмо
• Код, который был несколько минут назад, отклоняется
• Каждый резервный код работает ровно один раз
• Отключение 2FA требует пароль и текущий код
• Сброс пароля не обходит 2FA
• Администраторы без 2FA не могут попасть в админ-страницы (если это обязательно)
• Секреты и резервные коды зашифрованы или захешированы в базе
• Коды и секреты не появляются в логах

Перед запуском также пройдите полный чек-лист безопасности для приложений, созданных с ИИ.

Добавление 2FA в Mythex

Mythex не включает встроенной системы входа для конечных пользователей вашего приложения, поэтому 2FA является частью того подхода к аутентификации, который вы выбрали: собственного входа по email и паролю с базой данных проекта или размещённого провайдера с многофакторной защитой. Вы описываете нужное в чате, используя промпты, похожие на приведённые выше, а ключи провайдера сохраняются в секретах проекта (через /secrets, настройки проекта или карточку секретов, которую показывает агент), а не в тексте сообщения. В рецепте документации добавить вход в приложение есть стартовый промпт, а безопасность для приложений, которые вы создаёте описывает привычки работы с ключами и правами. Когда агент закончит, проверьте в Preview каждый пункт чек-листа до публикации.

Вопросы