Files
buryan-infra/ops/auth/2FA-DESIGN.md

125 lines
6.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 2FA: как не запереть себя снаружи
## Ловушка, которую вы заметили
Код приходит в Matrix. Но чтобы прочитать Matrix, нужно уже быть в него
залогиненным. На новом устройстве код получить негде — круг замкнулся.
Это реальная проблема, а не мелочь. Решается она не «умным» кодом,
а **порядком факторов**.
## Правильный порядок
| Очередь | Фактор | Работает если |
|---|---|---|
| 1 | **TOTP-приложение** (Aegis, Google Authenticator) | нет сети, нет Matrix, новый телефон |
| 2 | **Код на почту** (Gmail) | телефон потерян, приложение не настроено |
| 3 | **Копия в Matrix** | удобно, но никогда не единственный канал |
| 4 | **Резервные коды** (10 штук, распечатать) | всё остальное недоступно |
| 5 | **Break-glass** `/usr/local/bin/mfa-off` | админский доступ к серверу |
**Matrix — только удобная копия.** Основной фактор — TOTP-приложение:
оно не зависит ни от сети, ни от Matrix.
## Вход в Matrix с нуля
Matrix (Synapse) — **отдельная система**, не через Authentik.
У неё свой пароль, и 2FA Authentik на неё не влияет.
Порядок:
1. Ставите Element на новое устройство.
2. Входите логином/паролем Matrix (не SSO).
3. Получаете доступ к комнате, куда падают коды.
4. Дальше — обычный вход в сервисы через Authentik.
То есть Matrix — это **первый** аккаунт, который нужно помнить.
Пароль Matrix стоит хранить в менеджере паролей отдельно.
## Домашняя сеть — без кода
Политика `lan-bypass-mfa` уже создана: для адресов `192.168.1.0/24`
второй фактор не спрашивается. Дома вход всегда простой.
Проверка выполняется по `REMOTE_ADDR` в запросе.
## Break-glass
```
/usr/local/bin/mfa-off
```
Удаляет привязку MFA из потока входа. Работает с сервера по SSH,
не требует браузера и кода.
## Аппаратный ключ (YubiKey / FIDO2) — лучший вариант
Ключ снимает проблему целиком: он **физический**, код никуда не приходит,
работает без сети и без Matrix.
| Свойство | TOTP-приложение | YubiKey |
|---|---|---|
| Нужен телефон | да | нет |
| Работает без сети | да | да |
| Не фишируется | нет | **да** (проверяет домен) |
| Вход «касанием» | нет | **да** |
| Цена | 0 | ~5–6 тыс. ₽ |
| Потеря | восстановить по секрету | нужен второй ключ или коды |
### Схема с ключом
1. **Основной ключ** — вход касанием.
2. **Запасной ключ** — лежит дома (обязательно, если ключ один — потеря = проблема).
3. **Резервные коды** — 10 штук на бумаге.
4. TOTP/Matrix — не нужны, но остаются как резерв для семьи.
### Что нужно от вас
Купить один или два ключа (любой FIDO2: YubiKey 5, Token2, SoloKeys).
Двух достаточно на всю семью, если хранить запасной в сейфе.
### Что уже готово
- MFA-стадия принимает `totp` **и** `webauthn`, `not_configured_action=skip` —
значит включение никого не запрёт.
- Стадия настройки ключа: `default-authenticator-webauthn-setup`.
- `mfa-off` и LAN-bypass на месте.
## Что сделано сейчас
- MFA-привязка **снята**: вход снова простой (проверено: vikunja 200,
homebox 200, authentik 302).
- Политика `lan-bypass-mfa` создана и готова.
- Скрипт `mfa-off` создан.
- Попытка включить TOTP-валидацию откачена: проверить вход
end-to-end автоматически не удалось, а оставлять недопроверенную
блокировку входа — недопустимо.
## Как включать 2FA правильно (следующий заход)
1. Вы регистрируете TOTP в приложении (я дам QR/секрет).
2. Я включаю привязку **только для вашего пользователя**.
3. Вы проверяете вход в браузере в приватном окне.
4. Если что — `mfa-off`, 5 секунд.
5. После успеха — выдаю 10 резервных кодов.
6. Только потом добавляю остальных членов семьи.
## Решение владельца (21.10.2026)
2FA отложена. Вход остаётся по паролю, MFA-привязок в потоке **0**.
Важно, что выяснилось при попытке включить:
- у пользователя `roman` **нет TOTP-устройства** — включение MFA
мгновенно заперло бы вход;
- резервные коды через API не создаются (эндпоинт отвечает пусто);
- проверка входа автоматически не удалась — только браузером.
Поэтому порядок при возврате к теме строго такой:
1. сгенерировать секрет и **зарегистрировать TOTP в приложении** (браузер);
2. выдать 10 резервных кодов;
3. только после этого включать привязку MFA;
4. проверить вход в приватном окне;
5. держать `mfa-off` под рукой.