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 передавать нельзя.

Проверенные источники