WiFi Vouchers 1.7: API-Key hinter dem eigenen Proxy

Seit wir WiFi Vouchers für UniFi veröffentlicht haben, kam eine Rückfrage immer wieder: „Ich soll einer App meinen UniFi-API-Key geben?“

Die Frage ist berechtigt. Ein Key der UniFi Network Integration API erbt sämtliche Rechte des Admin-Accounts, der ihn erstellt hat, und Ubiquiti bietet keine Möglichkeit, ihn auf einzelne Endpunkte einzuschränken. „Gib der Voucher-App einfach einen API-Key“ heißt in der Praxis also: Gib ihr deine ganze Console. Das abzulehnen ist eine völlig vernünftige Haltung.

Version 1.7.0 hat darauf jetzt eine Antwort.

Der Proxy ist der fehlende Scope

Zusammen mit dem Update haben wir unifi-voucher-proxy veröffentlicht: einen kleinen Dienst, den du auf eigener Hardware betreibst. Er hält den echten API-Key. Die Clients – etwa das iPhone an der Rezeption – bekommen ein eigenes Token, das genau vier Dinge darf:

• Sites auflisten

• Voucher auflisten

• Voucher anlegen

• Voucher zurückziehen

Jeder andere Pfad antwortet mit 403 – und erzeugt dabei überhaupt keinen Traffic zu deinem Controller. Es gibt bewusst keinen generischen Weiterleiter: Jeder Call, den der Proxy nach oben machen kann, ist eine benannte Methode in einer einzigen Datei.

Dazu kommt alles, was ein API-Key selbst nicht kann: eine Site-Allowlist pro Token (ein Token, das auf eine Site beschränkt ist, sieht die anderen nicht einmal), Quotas für Menge und Gültigkeit, Rate-Limits pro Token und pro IP, und ein Audit-Log, in dem auf jeder Zeile der Name des Tokens steht, das sie verursacht hat.

Die Tokens selbst liegen nur als Argon2id-Hash in der Konfiguration. Eine kopierte Config ist damit kein funktionierender Zugang.

Und nebenbei: Certificate Pinning

UniFi-Consoles liefern ein selbstsigniertes Zertifikat aus. Die normale Prüfung schlägt deshalb immer fehl, und die meisten Tools lösen das, indem sie die Prüfung komplett abschalten. Damit liegt der API-Key offen für jeden, der die Adresse der Console per ARP-Spoofing übernehmen kann – in einem Gästenetz ist das eine relevante Menge an Leuten.

Der Proxy pinnt stattdessen den Fingerprint deiner Console und spricht danach nur noch mit genau diesem Zertifikat.

Geschrieben ist das Ganze in Rust: keine Runtime-Abhängigkeiten, rund 5 MB Container. Es spricht REST (pfadgleich zur UniFi Integration API) und GraphQL, steht unter MIT-Lizenz und ist offen einsehbar – du musst uns kein Wort davon glauben.

In drei Befehlen eingerichtet

Der Proxy läuft als einzelne Binary oder als Container. Die Einrichtung besteht im Kern aus drei Schritten:

Danach in der App auf Controller hinzufügen gehen, auf Über Proxy umschalten und Adresse plus Token eintragen. Die Pfade sind identisch zur Integration API, sonst ändert sich nichts.

Ein Detail, das im Alltag angenehm ist: Die App fragt beim Verbinden ab, was das Token überhaupt darf, und richtet sich danach. Ein Read-only-Token bekommt keinen Erstellen-Button, ein Token ohne Revoke-Recht keine Rückzieh-Aktionen, und der Slider für die Menge endet bei dem Maximum, das du im Proxy konfiguriert hast.

Was sonst noch in 1.7 steckt

• Face ID / Touch ID – optionale Sperre für die App, falls das Gerät an der Rezeption auch mal offen herumliegt.

• Home-Screen-Widget für iOS – im Stil der App, für den Voucher zwischendurch.

• Editierbare Gültigkeits-Presets – deine eigenen Laufzeiten statt unserer Vorschläge.

• WiFi-Join-Karte zum Teilen, plus die üblichen Bugfixes.

WiFi Vouchers für UniFi gibt es weiterhin kostenlos für iPhone, macOS und Android. Der Proxy ist optional – wer den direkten Weg zur Console mag, ändert nichts und merkt vom Update nichts außer den neuen Funktionen.