Массовая запись YubiKey в LinOTP

О чём эта инструкция

YubiKey по умолчанию содержит секрет, привязанный к сервису Yubico. Во многих организациях это неприемлемо — вы хотите хранить ключи локально и контролировать процесс аутентификации. YubiKey поддерживает режим RFC-совместимого HOTP-токена: в устройство можно записать HMAC-секрет, а затем использовать его с сервером аутентификации, например LinOTP.

LinOTP — это сервер аутентификации с открытым кодом на Linux, поддерживающий mOTP, TOTP, HOTP, OCRA, SMS и другие методы. Начиная с LinOTP 2.4.1 (и в версии 2.5.0 на момент написания), реализована возможность массовой записи YubiKey.

Важно: процедура записывает секреты в устройства; храните их и базу LinOTP в соответствии с политиками безопасности вашей организации.

Ключевые понятия

YubiKey — аппаратный токен от Yubico, поддерживает HOTP/TOTP и другие режимы.
HOTP — одноразовые пароли на основе HMAC, RFC 4226.
LinOTP — сервер для управления OTP-токенами и верификации.
linotpadm.py — CLI-клиент администратора LinOTP.

Требования и подготовка

Рабочий сервер с установленным LinOTP и доступом администратора.
Установленный клиент linotpadm (linotpadminclientce).
Физический доступ к YubiKey и USB-порты на машине, где выполняется запись.
Права на изменение udev-прав или возможность запуска от пользователя, имеющего доступ к USB-устройству.

Установка LinOTP сервера

LinOTP — Python-веб-приложение. Можно установить вручную через easy_install/pip или пакеты .deb из репозитория/домашней страницы проекта. В репозитории доступны собранные пакеты (на момент публикации — для Ubuntu 12.04 LTS). Инструкции по установке сервера см. на официальном сайте LinOTP.

Теперь предполагаем, что сервер LinOTP установлен, администратор настроен, а userstore сконфигурирован.

Установка клиента администратора LinOTP

LinOTP предоставляет консольный admin client (linotpadminclientce). Он дополняет Web UI и содержит команды, недоступные в веб-интерфейсе.

Установить клиент можно из репозитория (если вы добавили репозиторий) или из PyPI:

apt-get install linotpadminclientce

или

pip install linotpadminclientce

После установки клиент готов к использованию.

Доступ к YubiKey по USB (udev)

Обычно обычный пользователь не имеет прав на запись HMAC-ключа в YubiKey. Не рекомендуется запускать linotpadm как root. Вместо этого добавьте правило udev, чтобы консольный пользователь мог получить доступ к USB-устройству.

Создайте файл /etc/udev/rules.d/70-yubikey-enrollment.rules:

vi /etc/udev/rules.d/70-yubikey-enrollment.rules

Вставьте в него следующее содержимое (пример из yubikey-personalization):

# Udev rules for letting the console user access the Yubikey USB
# device node, needed for challenge/response to work correctly.
ACTION=="add|change", SUBSYSTEM=="usb", \
  ATTRS{idVendor}=="1050", ATTRS{idProduct}=="0010|0110|0111", \
  TEST=="/var/run/ConsoleKit/database", \
  RUN+="udev-acl --action=$env{ACTION} --device=$env{DEVNAME}"

После создания правила перезагрузите udev или систему, чтобы изменения вступили в силу.

Пошаговая методика массовой записи YubiKey

Убедитесь, что пользователь, выполняющий запись, находится в консольной сессии и имеет доступ к USB (udev).
Запустите linotpadm от имени администратора LinOTP (не root-сессии операционной системы, а аутентификация в LinOTP производится через параметры команды).
По очереди вставляйте YubiKey и нажимайте Enter для записи.
Завершите запись, введя «x».

Команда для запуска массовой записи:

% linotpadm.py -U https://localhost -a admin -C yubikey_mass_enroll

Пример вывода:

Please enter password for ‘admin’:
Please insert the next yubikey and press enter (x=Exit):
{ u’status’: True, u’value’: True}
Please insert the next yubikey and press enter (x=Exit): x

linotpadm.py читает серийный номер YubiKey и создаёт токен в базе LinOTP с идентификатором вида YUBI123456 (в соответствии с серийным номером). Это упрощает дальнейшее назначение токенов пользователям.

Контроль качества и критерии приёмки

Токен отображается в списке токенов LinOTP и имеет серийный номер YubiXYZ.
Для токена установлен тип HOTP и корректные параметры (counter, digits).
При ручной проверке challenge/response аутентификация проходит успешно.
Администратор зафиксировал список серийных номеров и назначил токены пользователям.

Роль‑ориентированные чеклисты

Администратор сервера:

Установил и настроил LinOTP.
Создал учётную запись администратора LinOTP для команды записи.
Настроил безопасный доступ к серверу (TLS, firewall).

Оператор по записи YubiKey:

Имеет доступ к консоле с udev-политиками.
Проверил, что клиент linotpadm установлен и работает.
Имеет список учётных записей, кому выдаются токены.
Фиксирует серийный номер каждого устройства.

Что может идти не так (частые ошибки и решения)

Нет доступа к USB: проверьте udev-правила и перезапустите udev.
linotpadm не запускается: проверьте версию python, зависимости и путь к клиенту.
Токен создан, но аутентификация не проходит: проверьте настройки HOTP (digits, counter) и синхронизацию счётчика.
Серийный номер не читается: убедитесь, что устройство корректно подключено и не заблокировано другим процессом.

Альтернативные подходы

Ручная персонализация каждого YubiKey с помощью yubikey-personalization GUI/CLI.
Использование готовых корпоративных решений управления ключами от поставщиков HSM для центрального хранения секретов.
Выпуск временных одноразовых паролей с последующей сменой на постоянные секреты уже в LinOTP.

Когда этот подход не подходит

Если вы хотите привязать устройство исключительно к сервисам Yubico (без локального контроля).
Когда требуется централизованное аппаратное хранение ключей на HSM с тонким разграничением прав — возможно, лучше интегрировать LinOTP с HSM.

Безопасность и рекомендации

Не запускайте linotpadm как системный root-аккаунт без необходимости.
Ограничьте доступ к машине, где происходит запись, и логируйте операции.
Резервно храните базу LinOTP и политику восстановления доступа.
Планируйте процесс замены/отзыва токенов (SOP на случай потери устройства).

Краткое руководство для оператора (cheat sheet)

Подготовка: убедиться в udev-правиле и наличии linotpadm.
Запуск: linotpadm.py -U https://localhost -a admin -C yubikey_mass_enroll
Вставлять YubiKey по одному, нажимать Enter.
Ввод «x» — закончить сессию.

Словарь (одна строка)

HOTP — стандарт одноразовых паролей на основе HMAC (RFC 4226).

Итог

Массовая запись YubiKey в LinOTP позволяет централизованно выпускать и управлять аппаратными HOTP-токенами, сохраняя контроль над секретами и интегрируя токены в существующие политики аутентификации. Следуйте правилам безопасности, проверяйте доступ по USB и фиксируйте серийные номера для дальнейшего распределения токенов.

Примечание: перед началом массовой записи отработайте процесс на 2–3 тестовых устройствах, чтобы избежать ошибок при полном развёртывании.

Удачной аутентификации!