Como inscrever em massa YubiKey com LinOTP

LinOTP suporta inscrição em massa de YubiKeys como tokens HOTP desde a versão 2.4.1. Configure o servidor LinOTP e o cliente administrativo, ajuste uma regra udev para acesso USB e execute linotpadm.py com o comando de mass enroll para gravar a chave HMAC em cada YubiKey. Este guia traz passos, checklist por função e resolução de problemas comum.

Visão geral

A YubiKey é entregue com um segredo usado para autenticar contra o serviço online da Yubico. Em muitas organizações isso não é aceitável: você quer controlar o segredo e o processo de autenticação internamente.

A YubiKey também pode operar como um token HOTP compatível com RFC. Em um rollout, a chave HMAC (segredo) pode ser escrita na YubiKey. A Yubico fornece um módulo Python para isso.

LinOTP é um servidor de autenticação open source baseado em Linux. Ele suporta vários mecanismos OTP (mOTP, TOTP, HOTP, OCRA), SMS, senhas diárias e outros. Ao inicializar a YubiKey como token HOTP, é simples integrar e gerir esses tokens com LinOTP.

Importante: desde a versão 2.4.1 do LinOTP (lançada em novembro de 2011) há suporte para inscrição em massa de YubiKeys.

Pré-requisitos

• Servidor LinOTP instalado e configurado (usuário administrador definido e userstore configurado).
• Cliente administrativo linotpadm instalado no sistema que fará as gravações.
• Acesso físico às YubiKeys e leitor USB onde aplicável.
• Permissão para executar comandos que interajam com dispositivos USB (veja udev abaixo).

Definições rápidas

• HOTP: algoritmo de senha única baseado em HMAC e contador.
• Mass enroll: processo para gravar várias YubiKeys em sequência sem repetir comandos manuais para cada uma.

Instalar o servidor LinOTP

LinOTP é uma aplicação web em Python. Você pode instalar a partir do zero usando easy_install ou pip. Também existem pacotes .deb disponíveis no repositório do projeto — os pacotes mais recentes do repositório foram construídos para Ubuntu 12.04 LTS. Se optou por usar repositórios, instale via apt; se preferir Python packages, use pip.

Observação: siga a documentação oficial do projeto LinOTP para detalhes de dependências, banco de dados e configuração do servidor.

Instalar o cliente administrativo LinOTP

O cliente administrativo linotpadminclientce é uma ferramenta de linha de comando que oferece funcionalidades que nem sempre aparecem na interface web.

Se configurou o repositório do sistema, instale com:

apt-get install linotpadminclientce

Se preferir instalar via PyPI:

pip install linotpadminclientce

Após a instalação, o utilitário linotpadm.py estará disponível para uso.

Acesso USB: udev e permissões

Normalmente o usuário comum não tem permissão para escrever a chave HMAC na YubiKey. Existem duas alternativas:

• Executar linotpadm como root (não recomendado).
• Criar uma regra udev para permitir que o usuário do console acesse o dispositivo YubiKey.

Crie o arquivo /etc/udev/rules.d/70-yubikey-enrollment.rules com o conteúdo abaixo. Isso permite que o ConsoleKit (usuário do console) acesse o dispositivo USB da YubiKey durante o processo de challenge/response.

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

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

Nota: essa regra foi adaptada do pacote yubikey-personalization. Após criar a regra, reinicie o udev ou remova/reinsira a YubiKey para que a nova regra seja aplicada.

Inscrição em massa (passo a passo)

1. No terminal com o usuário que tem acesso ao console, execute o comando de mass enroll:

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

2. O utilitário solicitará a senha do administrador:

Please enter password for ‘admin’:

3. Em seguida, o prompt pedirá que você insira cada YubiKey, uma por vez, e pressione Enter:

Please insert the next yubikey and press enter (x=Exit):

4. Para cada YubiKey inserida, o linotpadm.py lê o número de série do dispositivo, grava o token no banco de dados do LinOTP e mostrará um resultado como:

{ u’status’: True, u’value’: True}

5. Repita para todas as YubiKeys. Quando terminar, digite x e Enter:

Please insert the next yubikey and press enter (x=Exit): x

O token ficará registrado com um identificador relacionado ao número de série da YubiKey (ex.: YUBI123456), facilitando a associação com usuários.

Verificação e atribuição de tokens

• O número de série também está impresso no verso da YubiKey. Use-o para identificar fisicamente cada dispositivo.
• Depois de inscritos, atribua tokens no console administrativo do LinOTP ou via API/cliente para usuários finais.

Checklist por função

Administrador (setup inicial)

• Confirmar instalação e versão do LinOTP (>= 2.4.1).
• Garantir que o banco de dados esteja configurado e acessível.
• Criar conta administrador para o linotpadm.

Operador (inscrição em massa)

• Ter acesso físico às YubiKeys e porta USB.
• Verificar regra udev aplicada e que o usuário do console consegue acessar o dispositivo.
• Executar linotpadm.py e monitorar logs do servidor LinOTP.

Helpdesk

• Registrar número de série da YubiKey para rastreabilidade.
• Conectar usuários aos tokens após atribuição.

Usuário final

• Receber YubiKey com número de série e instruções de uso.
• Testar autenticação com token HOTP antes de implantação em produção.

Cenários em que isso falha e soluções

• Erro de permissão USB: confirme regra udev e reinicie o serviço udev; teste com lsusb e ferramentas de leitura da YubiKey.
• linotpadm não encontra o servidor: verifique a URL (-U), certificados TLS (se usar https) e conectividade de rede.
• Versão do LinOTP antiga: versões anteriores à 2.4.1 podem não ter mass enroll — atualize o servidor.
• Chave HMAC já gravada: se a YubiKey já tiver segredo diverso, será necessário reconfigurá-la usando ferramentas de personalização da Yubico antes de inscrever no LinOTP.

Alternativas e abordagens híbridas

• Inscrição manual por usuário: adequada para ambientes pequenos ou quando requer validação individual.
• Gerar e armazenar segredos no HSM interno e usar scripts para gravar YubiKeys em lote.
• Usar serviço de terceirização (Yubico cloud) quando controle local do segredo não for um requisito de segurança.

Escolha a alternativa conforme o equilíbrio entre controle (segredo interno) e custo operacional.

Playbook rápido (SOP) para uma sessão de mass enroll

1. Preparar estação: usuário do console com linotpadm instalado.
2. Conectar estação ao servidor LinOTP (verificar -U e porta).
3. Aplicar regra udev e reconectar a YubiKey.
4. Executar linotpadm.py -C yubikey_mass_enroll.
5. Inserir YubiKeys uma a uma, confirmar mensagens de sucesso.
6. Documentar números de série e atribuir tokens aos usuários.
7. Testar autenticação com 2–3 tokens antes de finalizar.
8. Registrar reversão: se algo falhar, recuperar backup do banco de dados e remover tokens problemáticos.

Runbook de incidentes rápido

Sintoma: inscrições falham com erro de I/O USB

• Verifique dmesg e /var/log/syslog para mensagens do kernel.
• Teste lsusb para confirmar detecção do dispositivo.
• Reinicie udev: sudo udevadm control –reload && sudo udevadm trigger.
• Tente reinserir a YubiKey.

Sintoma: LinOTP rejeita token ou não aparece no banco

• Verifique logs do LinOTP (normalmente em /var/log/linotp/).
• Confirme que o linotpadm usa credenciais corretas e que o endpoint (-U) está correto.

Mapa de decisão (Mermaid)

flowchart TD
  A[Preciso controlar segredos internamente?] -->|Sim| B[Usar LinOTP e mass enroll]
  A -->|Não| C[Considerar Yubico Cloud]
  B --> D{Ambiente pequeno ou grande}
  D -->|Pequeno| E[Inscrição manual por usuário]
  D -->|Grande| F[Mass enroll com linotpadm]
  F --> G[Aplicar udev, executar script, registrar números]

Notas de compatibilidade e migração

• LinOTP: certifique-se de usar versão >= 2.4.1 para mass enroll de YubiKeys.
• Distribuição Linux: os pacotes .deb do repositório foram construídos para Ubuntu 12.04 LTS — verifique compatibilidade e dependências para distribuições mais modernas.

Glossário rápido

• YubiKey: token físico de autenticação multifator.
• HOTP: One-time password HMAC-based.
• linotpadm.py: cliente de administração em linha de comando do LinOTP.

Resumo e próximos passos

Inscrever YubiKeys em massa com LinOTP centraliza o controle dos segredos e facilita a gestão de tokens HOTP. Antes de executar em produção, teste o processo em um ambiente controlado, valide a regra udev, e documente os números de série para rastreabilidade. Considere também um procedimento de rollback para o banco de dados do LinOTP.

Important: sempre proteja backups do banco de dados e os artefatos que contenham segredos.

Happy Authenticating!