QR для Authenticator — это изображение URI вида `otpauth://totp/...`, а не сам алгоритм. Если сканирование создаёт запись, но коды не принимаются, сравните `secret`, `algorithm`, `digits` и `period` в URI с параметрами серверного валидатора, затем проверьте время сервера в UTC.
Реальный QR нельзя отправлять в тикет или аналитику: параметр `secret` позволяет генерировать будущие коды. Для диагностики создайте отдельный тестовый secret, а production-пользователю при подозрении на раскрытие предложите перепривязать 2FA и отзовите старый ключ.
Симптом показывает, где сломалась цепочка
| Симптом | Вероятная причина | Проверка |
|---|---|---|
| Камера не распознаёт QR | Низкий контраст, обрезка или слишком плотные данные | Открыть тестовый URI и увеличить quiet zone |
| Запись без имени сервиса | Неверный label/issuer | Сравнить URI-encoding и оба значения issuer |
| Коды всегда различаются | Другой secret или algorithm/digits | Сверить параметры provisioning и validator |
| Код иногда принимается | Clock drift или граница time step | Сравнить Unix time и окно допуска |
| Один код принимается дважды | Нет защиты от replay | Сохранять последний использованный time step |
| Один аккаунт перезаписал другой | Одинаковый label | Добавить уникальное имя пользователя и issuer |
RFC 6238 строит TOTP поверх HOTP и требует общего secret, текущего Unix time и одинакового time step. Часовой пояс пользователя в формулу не входит; важна абсолютная синхронизация часов.
URI проверяют до рендера изображения
otpauth://totp/Example%3Aalice%40example.com
?secret=JBSWY3DPEHPK3PXP
&issuer=Example
&algorithm=SHA1
&digits=6
&period=30Это публичный примерный secret из документации, не используйте его для реального аккаунта. Label содержит issuer и account name с URI-encoding; параметр issuer должен совпадать с prefix. Secret кодируется Base32 без случайного преобразования регистра или повторного Base64.
Сервер и приложение должны считать один time step
Проверьте NTP/chrony на серверах, время контейнера и часы устройства. Валидатор обычно допускает небольшой соседний интервал, но широкое окно увеличивает возможность повторного подбора. После успешной проверки не принимайте тот же OTP второй раз в том же step — это прямо отмечено в RFC 6238.
- Генерируйте уникальный случайный secret для каждого пользователя.
- Шифруйте secret в хранилище и отделяйте ключ шифрования.
- Ограничивайте попытки проверки и уведомляйте о подозрительной активности.
- Выдавайте recovery codes отдельно и показывайте их один раз.
- Не логируйте URI, QR payload и введённый OTP.
QR должен оставаться простым технически
Рендерьте QR без фонового рисунка, сильного скругления модулей и обрезанного quiet zone. Не встраивайте в URI лишние JSON-поля. Если provider-specific приложение игнорирует optional parameters, используйте поддерживаемый базовый профиль или явно ограничьте список совместимых клиентов.
Рядом с QR покажите текстовый Base32 key для ручного ввода только в защищённой настройке и после повторной аутентификации. Никогда не помещайте secret в URL страницы, где он попадёт в history и referrer.
Контрольный тест отделяет QR от TOTP
Сначала передайте тестовый URI напрямую двум Authenticator-приложениям и сравните коды в середине time step. Затем отрендерьте QR и повторите сканирование. Если URI работает, а QR нет, проблема в изображении; если оба не работают, ищите parameter или clock mismatch.
Для анализа достаточно тестового URI, version библиотеки, Unix timestamp и ожидаемого результата test vector. Production secret, recovery code и screenshot реального QR передавать нельзя.