Одноразовые коды TOTP для приложения

Механизм секретов TOTP позволяет приложению проверять одноразовые коды второго фактора своих пользователей, не храня ключи у себя. Это отдельная возможность: она не связана с MFA при входе в сам Stronghold. MFA при входе описана в разделе «MFA для администраторов».

Цель

Создать ключ TOTP для пользователя приложения, получить код и проверить его, а также убедиться, что один и тот же код нельзя использовать дважды.

Предварительные требования

Для выполнения примера нужны:

• Токен Stronghold с правами на включение механизмов секретов и запись в totp/*.

Шаг 1. Включите механизм и создайте ключ

Включите механизм секретов TOTP и создайте ключ для пользователя alice:

d8 stronghold secrets enable totp

d8 stronghold write -format=json totp/keys/alice generate=true issuer="Example" account_name="alice@example.com" period=30 algorithm=SHA1 digits=6 | jq -r '.data.url'

Команда возвращает URL вида otpauth://totp/.... Приложение показывает его пользователю в виде QR-кода (в ответе также есть поле barcode с изображением в base64), и пользователь добавляет ключ в приложение-аутентификатор.

Основные параметры ключа:

Шаг 2. Выдайте приложению минимальные права

Приложению нужно только проверять коды:

d8 stronghold policy write totp-verifier - <<'POLICY'
path "totp/code/*" {
  capabilities = ["update"]
}
POLICY

Право read на totp/code/* позволяет получать сами коды, поэтому приложению его не давайте.

Шаг 3. Получите и проверьте код

Получите код так, как это делает приложение-аутентификатор, и проверьте его так, как это делает приложение:

1. Получите текущий код. Так вы имитируете аутентификатор пользователя:

   CODE=$(d8 stronghold read -field=code totp/code/alice)

2. Проверьте код, как это делает приложение:

   d8 stronghold write totp/code/alice code="$CODE"

   В ответе valid равен true.

3. Проверьте неверный код:

   d8 stronghold write totp/code/alice code=000000

   В ответе valid равен false.

Шаг 4. Убедитесь, что код одноразовый

Повторная проверка уже использованного кода отклоняется:

# Повторно проверьте тот же код.
d8 stronghold write totp/code/alice code="$CODE"

Stronghold отвечает ошибкой code already used; wait until the next time period. Следующий код можно проверить после смены периода.

Проверка

Выведите список ключей и прочитайте параметры ключа alice:

d8 stronghold list totp/keys
d8 stronghold read totp/keys/alice

Список содержит alice, а чтение ключа возвращает параметры (issuer, period, algorithm, digits) без секрета.

Очистка

Удалите ключ, политику и механизм секретов:

d8 stronghold delete totp/keys/alice
d8 stronghold policy delete totp-verifier
d8 stronghold secrets disable totp

Дополнительные ресурсы

• Механизм секретов TOTP
• MFA для администраторов