Registrazione di massa YubiKey con LinOTP

Introduzione

I YubiKey sono dispositivi hardware che possono usare una chiave segreta per autenticarsi. Molti dispositivi escono di fabbrica con una chiave legata al servizio online di Yubico; in contesti aziendali è preferibile controllare internamente le chiavi e il processo di autenticazione.

LinOTP è un server di autenticazione open source per Linux che supporta meccanismi OTP come HOTP, TOTP, OCRA, mOTP e altri. Dal supporto RFC per HOTP, è possibile inizializzare i YubiKey come token HOTP e gestirli centralmente con LinOTP. LinOTP supporta la registrazione di massa dei YubiKey (mass enrolling) a partire dalla versione 2.4.1.

Importante: questo documento descrive un flusso per generare e scrivere la chiave HMAC sui YubiKey in fase di rollout. Conserva sempre le chiavi in modo sicuro e limita l’accesso alle operazioni di enrollment.

Cosa aspettarsi e quando usare questa procedura

Uso ideale: rollout aziendale di molti YubiKey da distribuire agli utenti.
Non adatto: gestione di singoli YubiKey personali o quando si delega tutta la gestione a Yubico.

Prerequisiti

Server Linux con LinOTP installato e configurato.
Accesso amministrativo al server LinOTP e a una console con permessi per scrivere su dispositivi USB (o regole udev configurate).
Pacchetto linotpadminclientce installato sul sistema in cui verrà eseguito l’enrollment.
Cavi/lettori USB e YubiKey fisici disponibili.

Installare LinOTP (sintesi)

LinOTP è un’applicazione Python web. Puoi installarla da zero tramite pip/easy_install oppure usando pacchetti deb forniti nel repository ufficiale. I pacchetti della repository sono stati costruiti, al momento di riferimento, per Ubuntu 12.04 LTS; verifica la compatibilità con la tua distribuzione attuale.

Per istruzioni dettagliate sull’installazione di LinOTP e dei pacchetti, consulta la documentazione ufficiale del progetto.

Installare il client amministrativo LinOTP

LinOTP fornisce un client a riga di comando (linotpadm) che offre funzionalità non sempre presenti nella Web UI. Puoi installarlo tramite repository apt o PyPI.

Se hai configurato il repository apt, l’installazione è semplice:

apt-get install linotpadminclientce

Se usi pip:

pip install linotpadminclientce

Ora il client amministrativo è disponibile per l’enrollment.

Accesso USB: regola udev consigliata

Di norma un utente non ha i permessi per scrivere direttamente la chiave HMAC su un YubiKey. È possibile eseguire linotpadm come root (sconsigliato) oppure creare una regola udev che permetta all’utente della console di accedere al dispositivo USB.

Crea il file /etc/udev/rules.d/70-yubikey-enrollment.rules:

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

E inserisci la seguente regola (tratta da 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}"

Dopo aver salvato la regola, ricollega il YubiKey o ricarica le regole udev (udevadm control –reload). Questa regola consente all’utente della sessione di accedere al dispositivo senza usare l’account root.

Nota: alcune distribuzioni potrebbero usare logind invece di ConsoleKit; verifica l’ambiente della tua distribuzione e adatta la regola se necessario.

Procedura di registrazione (enroll)

Assicurati che il client linotpadm sia installato e che LinOTP sia raggiungibile dall’host in cui esegui il client.
Esegui il comando di enrollment di massa:

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

Il client richiederà la password dell’admin e poi ti guiderà inserendo i dispositivi uno alla volta. Esempio di output:

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

Inserisci un YubiKey, premi Invio. Ripeti per ogni dispositivo. Alla fine digita “x” per uscire.

Linotpadm legge il numero di serie del YubiKey e crea un token nel database LinOTP con un identificativo che include la seriale (ad es. YUBI123456). Il numero di serie è inoltre stampato sul retro del dispositivo, utile per l’assegnazione agli utenti.

Dopo l’enrollment

Verifica i token creati nella Web UI di LinOTP o tramite linotpadm.
Assegna i token agli utenti nel tuo userstore.
Esegui un test di autenticazione HOTP per confermare il funzionamento.

Best practice e sicurezza

Esegui l’enrollment in un ambiente controllato e protetto.
Limita l’accesso al server e al client di enrollment a personale autorizzato.
Conserva eventuali file di log sensibili in modo sicuro e configura la rotazione dei log.
Se possibile, genera le chiavi HMAC con procedure che non espongano le chiavi in chiaro su supporti condivisi.

Importante: non trasferire le chiavi HMAC su canali non sicuri. Se usi backup della configurazione, assicurati che siano cifrati.

Risoluzione dei problemi comuni

“Device not found” o permessi negati: verifica la regola udev e che il tuo utente appartenga alla sessione ConsoleKit/logind.
Il client non raggiunge LinOTP: controlla che l’URL (-U) sia corretto e che il certificato HTTPS sia valido. Per test temporanei puoi usare un endpoint HTTP locale, ma non in produzione.
Token duplicati: controlla che il numero di serie non sia già presente nel database prima dell’enrollment di massa.

Quando questa procedura fallisce (controesempi)

Se stai gestendo token TOTP o OCRA esclusivamente, la scrittura della chiave HOTP su YubiKey non è pertinente.
Se i dispositivi YubiKey sono già vincolati a Yubico con una chiave impossibile da sovrascrivere (rare ma possibili in hardware con configurazioni proprietarie), non potrai trasformarli in token HOTP gestiti internamente.

Approcci alternativi

Enrollment manuale: usare l’interfaccia Web UI e la registrazione singola per ogni token (utile per pochi dispositivi).
Uso di YubiKey personalization tools: la suite ufficiale Yubico permette di generare e scrivere chiavi; puoi usarla prima dell’enrollment LinOTP.
Servizi gestiti: delegare la gestione a fornitori terzi se non vuoi mantenere l’infrastruttura LinOTP.

SOP / Playbook: registrazione di massa (passo-passo)

Preparazione:
- Verifica prerequisiti.
- Prepara postazione isolata fisicamente.
- Assicurati che tutti i dispositivi YubiKey siano disponibili.
Esecuzione:
- Applica la regola udev e riconnetti i dispositivi.
- Esegui il comando linotpadm e inserisci i dispositivi sequentialmente.
- Controlla il database LinOTP per ogni token creato.
Verifica e consegna:
- Assegna token agli utenti.
- Esegui test di autenticazione con campione di utenti.
- Documenta numeri di serie assegnati ai rispettivi utenti.

Checklist per ruolo

Amministratore LinOTP:
- Verifica server LinOTP e permessi.
- Esegui test di connessione HTTPS.
Operatore enrollment:
- Gestisce i YubiKey fisici.
- Esegue linotpadm e controlla l’output.
Sicurezza/Compliance:
- Verifica registri e policy di conservazione.
- Conferma che la procedura soddisfi i requisiti di audit.

Mini-metodologia

Preparare l’ambiente (HW/SW) e i permessi.
Automatizzare l’accesso USB (udev).
Eseguire enrollment iterativo con linotpadm.
Validare e assegnare i token.
Documentare e monitorare.

Criteri di accettazione

Tutti i YubiKey elencati sono presenti come token HOTP nel database LinOTP.
Ogni token è associato al corretto numero di serie e (se previsto) a un utente.
Test di autenticazione HOTP eseguiti con successo per un campione casuale.

Glossario (una linea ciascuno)

YubiKey: token hardware per autenticazione multifattore prodotto da Yubico.
HOTP: One-Time Password basato su contatore (RFC 4226).
LinOTP: server open source per la gestione di token OTP.
udev: sistema di gestione dei dispositivi per il kernel Linux.

Privacy e note GDPR

Durante l’enrollment evita di memorizzare informazioni personali non necessarie. Associa i numeri di serie ai profili utenti solo se previsto dalla policy aziendale e registra eventuali motivazioni di trattamento. Tratta i log come dati sensibili quando contengono riferimenti a utenti o dispositivi.

Riepilogo

La registrazione di massa dei YubiKey con LinOTP è un processo efficace per rollout aziendali. Richiede preparazione: server LinOTP funzionante, client admin, e regole udev per permettere l’accesso USB. Una volta eseguito linotpadm in modalità “yubikey_mass_enroll”, puoi inserire i dispositivi uno alla volta per scrivere le chiavi HMAC e creare i token HOTP nel database. Segui le best practice di sicurezza e documenta l’assegnazione dei token.

Auguri per un deployment sicuro e tracciabile delle tue chiavi hardware.

Come eseguire la registrazione di massa dei YubiKey con LinOTP