Massenregistrierung von YubiKeys mit LinOTP

Warum YubiKey‑Massenregistrierung?

YubiKeys werden standardmäßig mit einem von Yubico bereitgestellten OTP‑Secret ausgeliefert, das gegen den Online‑Dienst von Yubico authentifiziert. Für viele Organisationen ist das nicht akzeptabel, da sie die Kontrolle über Geheimnisse und den Authentifizierungsprozess behalten möchten. Eine Alternative ist das Schreiben eines eigenen HMAC‑Schlüssels auf den YubiKey und die Verwendung des Geräts als RFC‑konformes HOTP‑Token.

LinOTP ist ein Open‑Source‑Authentifizierungsserver unter Linux, der viele OTP‑Mechanismen unterstützt (mOTP, TOTP, HOTP, OCRA, SMS usw.). Seit LinOTP 2.4.1 (mit aktuellen Paketen in der 2.5.0‑Reihe zum Zeitpunkt dieses Textes) unterstützt LinOTP die Massenregistrierung von YubiKeys. Das ermöglicht einen kontrollierten Rollout, bei dem Sie die Geheimnisse verwalten und Tokens zentral zuweisen.

Wichtig: Diese Anleitung beschreibt die lokale Erzeugung und Verteilung von HOTP‑Secrets. Verwenden Sie diese Vorgehensweise nur, wenn Sie die organisatorischen und datenschutzrechtlichen Anforderungen (z. B. Physische Sicherheit, Auditing, Benutzervereinbarungen) abgedeckt haben.

Voraussetzungen

• Ein laufender LinOTP‑Server mit Administratorzugang.
• Zugriff auf die Konsole des LinOTP‑Servers oder eines administrativen Arbeitsplatzes mit USB‑Ports.
• Physischer Zugriff auf die zu registrierenden YubiKeys.
• LinOTP‑Admin‑Client (linotpadm.py) installiert.
• Auf dem Arbeitsplatz muss Schreibzugriff auf die YubiKeys möglich sein (udev‑Regel oder Root).

Kurzdefinitionen:

• HOTP: HMAC‑basierte Einmalpasswörter (RFC 4226).
• LinOTP: Open‑Source OTP‑Server für zentrale Verwaltung von Tokens.
• YubiKey: Hardware‑Token, das HOTP/RFC‑konforme Tokens unterstützen kann.

LinOTP‑Server installieren

Es gibt mehrere Installationswege:

• Direkt aus den Python‑Paketen (pip / easy_install). LinOTP ist eine Python‑Webanwendung und kann über PyPI installiert werden.
• Über vorgefertigte Debian/Ubuntu‑Pakete von der Projektseite oder einem Repository. In einigen Repositories wurden Pakete für Ubuntu 12.04 LTS gebaut; prüfen Sie die Paketquelle und Kompatibilität mit Ihrer Distribution.

Praktisch: Wenn Sie einen stabilen Produktivbetrieb planen, nutzen Sie die Distributionspakete oder von Ihrem Team getestete Repositories, um Abhängigkeiten und Updates zu kontrollieren. Anleitungen zur Installation direkt vom Projekt oder Paketquellen finden Sie auf den jeweiligen Seiten des Projekts.

Hinweis: Nach der Installation legen Sie mindestens einen Administrator‑Benutzer an und konfigurieren den Benutzer‑Store (z. B. LDAP, lokale DB).

LinOTP Admin‑Client installieren

Der Admin‑Client (linotpadminclientce) ist ein Kommandozeilenwerkzeug mit Funktionen, die teilweise nicht über die Web‑UI verfügbar sind. Installation wahlweise über apt oder pip.

Beispiel mit APT (wenn das Repository konfiguriert ist):

apt-get install linotpadminclientce

Oder über PyPI:

pip install linotpadminclientce

Sobald der Client installiert ist, können Sie ihn für die Massenregistrierung verwenden.

YubiKeys registrieren

USB‑Zugriff (udev‑Regel)

Normalerweise hat ein normaler Benutzer keinen direkten Zugriff, um das HMAC‑Secret auf einen YubiKey zu schreiben. Sie sollten vermeiden, Verwaltungsbefehle als Root auszuführen. Besser ist das Anlegen einer udev‑Regel, die dem angemeldeten Console‑Benutzer den Zugriff erlaubt.

Erstellen Sie die Datei /etc/udev/rules.d/70-yubikey-enrollment.rules:

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

Fügen Sie folgende Regel ein:

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

Wichtig: Die obige Regel stammt aus dem yubikey‑personalization‑Projekt. Testen Sie die Regel in Ihrer Umgebung und passen Sie ATTRS{idProduct} an, falls Sie andere YubiKey‑Modelle haben.

Nach dem Anlegen der Regel starten Sie udev neu oder stecken die YubiKeys erneut ein:

systemctl restart systemd-udevd.service

(oder in älteren Systemen udevadm control –reload)

Hinweis: Falls Ihre Umgebung kein ConsoleKit verwendet, müssen Sie die Regel an Ihre Session‑/Benutzerverwaltung (z. B. logind) anpassen.

YubiKey eintragen (Erster Test)

Führen Sie auf dem Admin‑Arbeitsplatz folgenden Befehl aus:

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

Erwartete Ausgabe (Beispiel):

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

Beschreibung: linotpadm.py liest die Seriennummer des YubiKey aus und legt ein HOTP‑Token mit der Kennung YUBI123456 (basierend auf der Seriennummer) in der LinOTP‑Token‑Datenbank an. So können Sie später das physische Gerät einfach identifizieren und zu Benutzern zuordnen.

Tipp: Die Seriennummer steht auf der Rückseite des YubiKey – notieren Sie Seriennummern und zugeordnete Benutzer in Ihrem Inventar.

SOP: Playbook für Massenregistrierung (Schritt‑für‑Schritt)

1. Vorbereitung
   • Prüfen Sie Server, Netzwerk und LinOTP‑Version.
   • Stellen Sie sicher, dass der Admin‑Client funktioniert und der Administrator Zugriff hat.
   • Legen Sie einen sicheren Registrierungsarbeitsplatz mit erforderlichen Tools an.
2. Physische Vorbereitung
   • Etikettieren Sie YubiKeys mit temporären ID‑Stickern (falls gewünscht).
   • Stellen Sie eine sichere Umgebung bereit (z. B. verschlossene Registrierungsstation).
3. udev‑Regel aktivieren
   • Deployen und testen Sie die udev‑Regel auf dem Arbeitsplatz.
4. Registrierung durchführen
   • Starten Sie den Befehl: linotpadm.py -U https://localhost -a admin -C yubikey_mass_enroll
   • Folgen Sie den Aufforderungen und stecken Sie nacheinander die YubiKeys ein.
5. Zuordnung
   • Weisen Sie die neu angelegten Token den Benutzern zu (manuell oder per Skript).
6. Dokumentation und Audit
   • Protokollieren Sie Seriennummer, zugewiesenen Benutzer, Datum, verantwortliche Person.
7. Abschluss
   • Entfernen Sie temporäre Etiketten und übertragen Sie Geräte an die Benutzer mit einer kurzen Bedienungsanleitung.

Kriterien für erfolgreiche Registrierung:

• Token erscheinen in LinOTP mit erkennbarer Seriennummer.
• Challenge/Response‑Test oder Anmeldeversuch mit HOTP funktioniert.
• Dokumentation ist vollständig und unterzeichnet.

Rollenbasierte Checklisten

Administrator:

• LinOTP‑Server auf dem neuesten stabilen Stand.
• Admin‑Client installiert und getestet.
• Registrierungsrichtlinie genehmigt.

Operator (Registrierungsdurchführer):

• Physische Kontrolle über die YubiKeys.
• udev‑Regel geprüft und aktiv.
• Registrierung gemäß SOP durchgeführt.
• Übergabeprotokoll ausgefüllt.

Auditor/Security:

• Prüft Audit‑Logs in LinOTP.
• Verifiziert sichere Lagerung/Entsorgung nicht verwendeter Schlüssel.
• Bestätigt Einhaltung der Unternehmensrichtlinien.

Sicherheitshärtung & Best Practices

• Erzeugen und verwalten Sie HOTP‑Secrets nur in einer kontrollierten Umgebung.
• Beschränken Sie Client‑Zugriff auf registrierende Personen (kein dauerhafter Root‑Zugriff).
• Aktivieren Sie Audit‑Logs in LinOTP und behalten Sie Änderungen an Token sichtbar.
• Implementieren Sie eine Richtlinie zur Schlüsselrotation und Gerätezurücksetzung (z. B. bei Verlust).
• Verwahren Sie nicht zugewiesene YubiKeys sicher (versiegelter Umschlag oder Tresor).
• Deaktivieren Sie, sofern möglich, die Verwendung des Yubico Online‑Dienstes für lokale Tokens, wenn Sie selbst verwalten möchten.

Kompatibilität, Einschränkungen und typische Fehlerfälle

Wann das Verfahren scheitern kann:

• Veraltete LinOTP‑Versionen ohne Mass‑Enroll‑Support.
• Fehlende oder falsch konfigurierte udev‑Regeln verhindern Zugriff auf das Gerät.
• YubiKey‑Modelle, die kein RFC‑konformes HOTP unterstützen.
• Probleme mit ConsoleKit/logind auf neueren Distributionen—die udev‑Regel muss angepasst werden.

Alternative Ansätze:

• Nutzung eines zentralen Geräts/Station, an dem alle Keys nacheinander physisch programmiert werden.
• Vorinstallierte Tokens durch Lieferanten mit kundeneigenen Secrets (nur wenn Trust‑Beziehung vorhanden).
• Verwendung eines HSM zur zentralen Geheimnisverwaltung und zur Ausgabe von Tokens als Service.

Migrationshinweis:

• Prüfen Sie vor dem Rollout die Kompatibilität der YubiKey‑Modelle mit Ihrer LinOTP‑Version.
• Testen Sie das Verfahren mit 3–5 Geräten, bevor Sie einen größeren Batch eintragen.

Mini‑Methodenbox: Prüftests nach der Registrierung

• Sichtprüfung: Seriennummer stimmt mit dem Inventar überein.
• Login‑Test: Benutzer authentifiziert sich mit einem HOTP‑Token.
• Audit‑Check: Eintrag in LinOTP‑Logs vorhanden und mit Zeitstempel.

1‑Zeilen‑Glossar

• HOTP: HMAC‑basierte Einmalpasswörter, RFC 4226.
• HMAC: Hashbasierte Message Authentication Codes, zur Generierung des OTP.
• LinOTP: Open‑Source OTP‑Server für die zentrale Tokenverwaltung.
• YubiKey: Hardware‑Token, mehrfach einsetzbar (OTP, U2F, Smartcard).

Kurze Zusammenfassung

Massenregistrierung von YubiKeys in LinOTP ermöglicht die zentrale Kontrolle über Secrets und Tokens. Stellen Sie eine sichere Registrierungsumgebung bereit, konfigurieren Sie udev‑Regeln für den USB‑Zugriff und verwenden Sie den linotpadm.py‑Client für die eigentliche Massenaufnahme. Ergänzen Sie den Prozess durch SOP, Checklisten, Auditierung und Sicherheitsmaßnahmen.

Wichtig: Testen Sie immer im Vorfeld in einer kontrollierten Umgebung, dokumentieren Sie jeden Schritt und beachten Sie organisatorische Sicherheitsanforderungen.

Viel Erfolg beim Rollout und sichere Authentifizierung!