Безопасность учётной записи: MFA, ключи доступа и устройства#

Это руководство дополняет раздел аутентификации. Elang объединяет вход по паролю, необязательные одноразовые пароли на основе времени, ключи доступа, отзываемые сессии устройств и цепочку аудита с обнаружением изменений. Эти возможности — строительные блоки приложения; они не сертифицируют приложение для банковской деятельности или соответствия нормативным требованиям.

Установка и подготовка#

Используйте PHP 8.3 или новее, Composer 2, постоянный ключ шифрования приложения, HTTPS и синхронизированное время сервера. Полный фреймворк включает OTPHP, web-auth/webauthn-lib и локальное средство формирования QR-кодов SVG. Секрет не передаётся стороннему сервису QR-кодов.

php elang key:generate
php elang platform:setup
php elang doctor

Для существующей рабочей базы данных создайте резервную копию, проверьте изменения схемы и выполните php elang platform:setup --force. Сохраните существующий APP_KEY: его изменение делает сохранённые секреты MFA и зашифрованную почту нечитаемыми. Добавьте Elang\Auth\AuthProvider в начальную загрузку, если приложение ещё не регистрирует его.

Включение приложения-аутентификатора#

1. Войдите, смените временный пароль, если он есть, и подтвердите электронную почту.
2. Откройте /security, введите текущий пароль и начните настройку.
3. Отсканируйте локальное изображение QR-кода приложением-аутентификатором или введите показанный ключ настройки вручную.
4. Отправьте текущий шестизначный код. Настройка действует десять минут.
5. Сохраните десять кодов восстановления в личном менеджере паролей. Они показываются один раз.

База данных хранит зашифрованный секрет аутентификатора и хеши кодов восстановления. Коды состоят из шести цифр и используют 30-секундные интервалы с допуском в один интервал для расхождения часов. Атомарное обновление последнего использованного интервала отклоняет повторное использование принятого кода аутентификатора. Каждый код восстановления можно использовать один раз. Код, использованный для подтверждения настройки, нельзя сразу повторно использовать для входа.

После включения или отключения MFA отзываются остальные сессии, API-токены и действующие ссылки сброса пароля или подтверждения адреса. Текущий браузер получает новую сессию. После этого вход по паролю создаёт ожидающую проверку со сроком пять минут; доступ к учётной записи не предоставляется до успешной проверки второго фактора. /two-factor обрабатывает браузерные формы, а /api/session/mfa — JSON-клиенты. Оба используют CSRF и ограничения числа попыток.

Для отключения MFA и замены кодов восстановления требуются текущий пароль и свежий код аутентификатора или восстановления. Замена кодов восстановления аннулирует все старые коды. Восстановление пароля по электронной почте меняет пароль и отзывает сессии; оно не удаляет MFA.

Регистрация и использование ключей доступа#

В /security введите пароль, выберите имя устройства и зарегистрируйте ключ доступа. Браузер использует свой встроенный диалог учётных данных. Требуются проверка пользователя и обнаруживаемые учётные данные. Elang поддерживает алгоритмы открытого ключа ES256 и RS256 и аттестацию none. Здесь аттестация не подтверждает сертификацию устройства.

Идентификатор проверяющей стороны берётся из имени хоста APP_URL. В рабочей среде необходим HTTPS. Для разработки поддерживаются loopback-адреса и localhost. Настройте точные источники, если несколько интерфейсов используют одно имя хоста проверяющей стороны:

'auth' => [
    'passkey_origins' => ['https://app.example.com'],
],

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

Используйте «Войти с ключом доступа» на /login. Проверенный ключ доступа — отдельный способ входа; он не запрашивает TOTP, используемый при входе по паролю. Удаление ключа доступа требует пароль учётной записи. Сохраните другой способ восстановления, прежде чем удалять последние пригодные для входа учётные данные.

Просмотр устройств и записей аудита#

/security показывает сессии устройств с описанием браузера и временем последней активности. Описания — подсказки, предоставленные браузерами, а не доверенная идентификация устройства. Отзыв одной сессии вступает в силу при следующей проверке авторизации. Смена пароля отзывает все сессии, API-токены и токены ссылок. Обычные cookie сессий используют HttpOnly, SameSite=Lax и Secure при HTTPS. Развёртывания с Redis совместно используют данные отзыва через SQL, а содержимое сессий — через Redis.

$audit = $app->container->get(Elang\Audit\Audit::class);
$result = $audit->verify('user:'.$user->id);
// ['valid' => true, 'sequence' => ..., 'hash' => ...]

Записи аудита образуют отдельную для каждой области цепочку HMAC под ключом, производным от APP_KEY. Они обнаруживают изменения строк, пропущенные записи последовательности и изменённую вершину цепочки, пока ключ приложения остаётся доверенным. Это не внешний неизменяемый журнал. Экспортируйте подписанные контрольные точки за отдельную границу доверия, если модель угроз требует устойчивости к действиям администратора базы данных. Никогда не записывайте пароли, секреты, токены, адреса электронной почты, тела запросов или платёжные данные в метаданные аудита.

Устранение неполадок#

• Код отклонён: синхронизируйте время сервера и устройства; дождитесь нового кода, если предыдущий интервал уже использован. Никогда не увеличивайте окно приёма, чтобы скрыть проблемы часов.
• Диалог ключа доступа недоступен: проверьте HTTPS/localhost, поддержку браузера, точный источник, имя хоста RP и доступность аутентификации платформы.
• Настройка исчезла: истекли десять минут настройки или две минуты браузерного проверочного запроса; начните настройку заново.
• Все устройства вышли из учётной записи: изменения пароля или факторов намеренно обновляют версии учётных данных.
• Утрачены все факторы: используйте сохранённый код восстановления. Восстановление администратором должно быть отдельным проверенным процессом подтверждения личности; Elang не предоставляет публичный эндпоинт обхода MFA.

Далее: инфраструктура Redis и эксплуатация.