Cómo inscribir masivamente YubiKeys con LinOTP

Introducción

La YubiKey viene de fábrica con un secreto que puede usarse para autenticarse contra el servicio en línea de Yubico. En muchos entornos esto no es aceptable: querrá controlar usted mismo el secreto y el proceso de autenticación.

La YubiKey puede comportarse además como un token HOTP conforme a RFC. En un proceso de despliegue puede escribirse la clave HMAC en cada YubiKey. Yubico proporciona herramientas (módulos Python y utilidades) para ese propósito.

LinOTP es un servidor de autenticación open source para Linux que soporta varios mecanismos OTP: mOTP, TOTP, HOTP, OCRA, SMS y contraseñas diarias, entre otros. Cuando inicializa la YubiKey como token HOTP, puede gestionarla desde LinOTP.

Desde LinOTP 2.4.1 (la serie 2.5.x estaba vigente al momento de escribir) LinOTP soporta la inscripción masiva de YubiKeys.

Importante: este artículo describe el flujo técnico para inscribir dispositivos; aplique sus políticas de seguridad, gestión de claves y cumplimiento antes de operar en producción.

Qué aprenderá (intención principal + variantes)

• Inscribir masivamente YubiKeys en LinOTP
• Alternativas y cuándo preferirlas
• Requisitos, permisos USB y udev
• Playbook paso a paso, roles y verificación

Prerrequisitos

• Servidor LinOTP instalado y configurado con un usuario administrador.
• Acceso de consola al servidor con permisos para crear reglas udev y ejecutar el cliente administrador.
• Paquetes Python y utilidades (pip/easy_install o paquetes .deb) según su distribución.

Instalar el servidor LinOTP

LinOTP es una aplicación web escrita en Python. Puede instalarlo desde cero usando pip/easy_install o paquetes .deb cuando estén disponibles en su repositorio. Las últimas builds públicas en repositorios se construyeron contra Ubuntu 12.04 LTS (nota histórica).

Consulte la documentación oficial del proyecto LinOTP para instrucciones específicas de instalación según su distribución.

Instalar el cliente administrador de LinOTP

LinOTP ofrece también un cliente administrativo en línea de comandos (linotpadminclientce). Puede instalarlo desde su repositorio configurado o desde PyPI.

Si configuró el repositorio, instale con:

apt-get install linotpadminclientce 

Si usó easy_install o pip, instale desde PyPI:

pip install linotpadminclientce

Una vez instalado el cliente, estará listo para realizar inscripciones masivas.

Inscripción masiva de YubiKeys

Acceso USB desde la sesión de consola

Normalmente un usuario de consola no tiene permiso para escribir la clave HMAC en una YubiKey. Hay dos opciones comunes:

• Ejecutar linotpadm como root (no recomendado).
• Crear una regla udev que otorgue acceso al usuario de consola cuando se inserte la YubiKey (recomendado).

Cree el archivo /etc/udev/rules.d/70-yubikey-enrollment.rules con su editor preferido:

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

Y añada el contenido siguiente:

# 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}"

(El fragmento anterior procede del paquete yubikey-personalization y delega permisos al usuario de consola para el dispositivo USB.)

Nota: si su entorno no usa ConsoleKit, adapte la regla udev a ConsoleKit/elogind/systemd-logind según corresponda.

Comando de inscripción

Con el cliente instalado y los permisos USB configurados, ejecute:

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

Salida esperada:

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

Cada vez que inserte una YubiKey y pulse Enter, linotpadm.py leerá el número de serie y escribirá el token HOTP en la base de datos de LinOTP. Repita hasta procesar todas las YubiKeys.

La entrada en la base de datos tendrá un identificador con el prefijo YUBI seguido del número de serie (por ejemplo, YUBI123456), lo que facilita la identificación del token.

La YubiKey tiene además el número de serie impreso en la parte trasera, lo que ayuda para la asignación física del token a usuarios.

Importante: gestione las claves HMAC como secretos: registre quién firmó/inscribió cada token y almacene los respaldos de forma segura.

Playbook paso a paso (mini-metodología)

1. Preparación
   • Verifique que LinOTP y la base de datos de usuarios están en funcionamiento.
   • Asegure un entorno controlado (sala con acceso restringido) para la inscripción masiva.
2. Instalación cliente
   • Instale linotpadminclientce en el servidor que ejecutará la inscripción.
3. Permisos USB
   • Coloque la regla udev en /etc/udev/rules.d/70-yubikey-enrollment.rules.
   • Recargue udev: sudo udevadm control –reload && sudo udevadm trigger
4. Prueba con una YubiKey
   • Conecte una YubiKey y ejecute el comando de inscripción; confirme que se registra en LinOTP.
5. Inscripción masiva
   • Inserte YubiKey por YubiKey y pulse Enter; utilice un registro (hoja o CSV) que asocie serial -> usuario.
6. Asignación a usuarios
   • Asigne tokens en LinOTP a las cuentas de usuario según su política.
7. Verificación
   • Solicite al usuario realizar un primer inicio de sesión para validar el OTP.
8. Auditoría
   • Guarde registros de la sesión de inscripción y destruya cualquier export temporal de claves.

Checklist por rol

• Administrador de seguridad
  • Confirmar políticas de gestión de claves y auditoría.
  • Aprobar la lista de usuarios y el proceso de asignación.
• Operador / Técnico
  • Instalar cliente y reglas udev.
  • Ejecutar el proceso de inscripción y verificar registros.
• Responsable de soporte
  • Preparar la guía de entrega al usuario final y el procedimiento de primer inicio de sesión.

Problemas comunes y cómo resolverlos (cuando falla)

• No se detecta la YubiKey desde el usuario de consola
  • Verifique la regla udev y recargue udev. Asegúrese de que TEST apunte a una ruta válida en su sistema.
• linotpadm falla por permisos
  • Compruebe que el usuario de consola tiene permiso sobre el nodo de dispositivo creado por udev; pruebe temporalmente con sudo para depurar.
• Error de versión de Python o dependencias
  • Instale las dependencias indicadas en la documentación del cliente linotpadminclientce.
• Dispositivo ya provisionado
  • Si la YubiKey ya tiene otra clave HOTP, puede que deba reprogramarse; siga la guía oficial de Yubico para reconfigurar OTP.

Alternativas y cuándo usarlas

• Usar YubiKey Manager (ykman) o yubikey-personalization si necesita operaciones avanzadas de reprogramación o soporte de otras funciones fuera de HOTP.
• Provisionamiento centralizado con hardware HSM: si sus requisitos de seguridad exigen que la clave HMAC nunca salga de un HSM, considere integrar un HSM en su flujo de generación y firmado.
• Inscripción manual: válida para entornos pequeños o tokens únicos, pero no escalable para despliegues masivos.

Seguridad y privacidad

• Trate las claves HMAC como secretos críticos: aplique control de acceso, rotación y registro de auditoría.
• Al mapear tokens a usuarios usted procesa datos personales. Aplique las políticas de privacidad y, si corresponde, requisitos GDPR: minimice datos, justifique la finalidad y mantenga registros de consentimiento/gestión.
• Evite ejecutar utilidades administrativas como root cuando sea posible: otorgue permisos específicos mediante udev.

Criterios de aceptación

• Cada YubiKey aparece en LinOTP con un token con prefijo YUBI + número de serie.
• El usuario asignado puede generar OTP válidos y autenticarse en el sistema que delega en LinOTP.
• Las entradas de auditoría de inscripción están almacenadas y verificables.

Preguntas frecuentes (FAQ)

¿Puedo inscribir YubiKeys remotamente?

No de forma segura sin un canal que proteja la escritura de claves HMAC. El proceso descrito asume acceso físico a cada YubiKey para escribir la clave en el dispositivo.

¿Qué pasa si una YubiKey se pierde?

Revoque el token en LinOTP, desasigne del usuario y, si aplica, proceda a bloquear la cuenta o requerir MFA alternativo.

Resumen

Inscribir masivamente YubiKeys en LinOTP implica: instalar el cliente admin, garantizar acceso USB seguro mediante udev, ejecutar el comando de inscripción interactiva y luego asignar y verificar tokens con los usuarios. Mantenga registros de auditoría, proteja las claves HMAC y adapte la regla udev a su sistema de gestión de sesiones.

Resumen de acción rápida:

• Instale linotpadminclientce
• Cree /etc/udev/rules.d/70-yubikey-enrollment.rules
• Ejecute linotpadm.py con -C yubikey_mass_enroll
• Asigne tokens y verifique accesos

¡Feliz autenticación!