Podcast-Transkript ansehen
Captive Portal for Ubiquiti UniFi - A Purple Technical Briefing
[EINFÜHRUNG & KONTEXT - ca. 1 Minute]
Willkommen zur Purple Technical Briefing-Serie. Ich bin Ihr Gastgeber, und heute befassen wir uns mit den Besonderheiten der Bereitstellung eines externen Captive Portal auf einer Ubiquiti UniFi-Infrastruktur - einer der am weitesten verbreiteten Netzwerkplattformen im Gastgewerbe, im Einzelhandel und in Unternehmensumgebungen weltweit.
Wenn Sie IT-Manager, Netzwerkarchitekt oder Systemintegrator sind und mit UniFi Cloud Gateways, Dream Machines oder der UniFi Network Application arbeiten, ist diese Episode genau das Richtige für Sie. Wir gehen genau durch, wie der externe Portal-Mechanismus unter der Haube funktioniert, wie man ihn richtig konfiguriert, wo die üblichen Fallstricke liegen und warum die Überlagerung von Purple auf einer UniFi-Bereitstellung die richtige architektonische Entscheidung für Standorte ist, die mehr als eine einfache Splash-Page benötigen.
Legen wir los.
[TECHNISCHER DEEP-DIVE - ca. 5 Minuten]
Verstehen wir zunächst, was tatsächlich passiert, wenn sich ein Gast mit einer UniFi-SSID verbindet, bei der ein Captive Portal aktiviert ist.
Wenn sich ein Gastgerät mit Ihrer Gast-SSID verbindet, weist der UniFi Access Point ihm wie gewohnt eine IP-Adresse über DHCP zu. Das Gerät wird jedoch sofort in einen Zustand versetzt, den UniFi als "pending" bezeichnet. In diesem Zustand fängt der im AP integrierte DNSmasq-Prozess jede DNS-Anfrage ab, die das Gerät stellt, unabhängig davon, welchen DNS-Server das Gerät zu verwenden glaubt. Der AP leitet den gesamten DNS-Verkehr an sich selbst um.
Gleichzeitig führt der AP einen schlanken HTTP-Redirector auf Port 80 aus. In dem Moment, in dem der Browser des Gasts eine HTTP-Anfrage stellt - und das ist das Schlüsselwort, HTTP, nicht HTTPS -, sendet der Redirector eine 302-Umleitung zurück und leitet den Browser auf die Splash-Page des Captive Portal weiter. Dies ist der Mechanismus, der die Benachrichtigung "Bei WiFi anmelden" auf iOS- und Android-Geräten auslöst.
Hier wird der Unterschied zwischen dem integrierten Portal und dem externen Portal entscheidend. Beim integrierten UniFi Hotspot Portal wird die Splash-Page direkt von der UniFi Network Application bereitgestellt. Das ist funktional und schnell eingerichtet, aber stark eingeschränkt. Sie erhalten eine einfache Passwort-Authentifizierung, Voucher und Stripe-Zahlungen. Es gibt keine E-Mail-Erfassung, kein Social Login, kein GDPR-Einwilligungsmanagement, keine CRM-Integration und keine aussagekräftigen Analysen über die Anzahl der Sitzungen hinaus.
Wenn Sie einen externen Portal-Server konfigurieren - die Einstellung, auf die wir uns heute konzentrieren -, weisen Sie den UniFi-Controller an, Gäste zu einer völlig separaten Webanwendung umzuleiten. In unserem Fall ist das Purple. Die URL, die Sie in das Feld für den externen Portal-Server eingeben, wird zum Ziel für all diese 302-Umleitungen.
Hier ist das wichtige technische Detail zu dieser Weiterleitungs-URL. Wenn UniFi einen Gast zu Ihrem externen Portal weiterleitet, hängt es mehrere Abfrageparameter an die URL an. Dazu gehören: die MAC-Adresse des AP, die MAC-Adresse des Client-Geräts, ein Unix-Zeitstempel, die ursprüngliche URL, die der Client aufrufen wollte, und der SSID-Name. Ihr externes Portal - in diesem Fall Purple - erfasst diese Parameter, verwendet sie zur Identifizierung des verbindenden Geräts, zeigt die entsprechende Splash Page an, übernimmt die Authentifizierung und führt dann einen API-Aufruf zurück an die UniFi-Netzwerkanwendung aus, um diese MAC-Adresse zu autorisieren.
Dieser API-Aufruf ist der entscheidende Handshake. Seit der UniFi-Netzwerkanwendung Version 9.1 und höher gibt es eine offizielle REST-API mit ordnungsgemäßer schlüsselbasierter Authentifizierung. Der Autorisierungsendpunkt ist eine POST-Anfrage an die Version 1 der Sites-API, die auf die spezifische Client-ID abzielt, mit einem JSON-Body, der Zeitlimits in Minuten, Datennutzungslimits in Megabyte und Ratenlimits in Kilobit pro Sekunde angeben kann. Sobald der Controller diese Autorisierung erhält, leitet er die Anweisung an den AP weiter, und der Status des Gasts wechselt von ausstehend zu autorisiert. Der Internetzugang wird gewährt.
Lassen Sie uns nun über den Walled Garden sprechen, den UniFi als Pre-Authorization Access bezeichnet. Dies ist die Whitelist von Domains und IP-Adressen, die Gäste erreichen können, bevor sie sich authentifiziert haben. Sie ist unerlässlich und eine der häufigsten Fehlerquellen bei der Konfiguration.
Ihr Walled Garden muss mindestens den vollqualifizierten Domänennamen Ihres Purple-Portals und die IP-Adressen oder CIDR-Bereiche enthalten, auf die die Infrastruktur von Purple verweist. Wenn Sie Social Login - Facebook, Google, Microsoft - verwenden, müssen Sie auch die OAuth-Endpunkt-Domains dieser Anbieter hinzufügen. Die Login-Endpunkte von Google erstrecken sich über mehrere IP-Bereiche und verschiedene Domains, darunter accounts.google.com und oauth2.googleapis.com. Die Login-Infrastruktur von Facebook erfordert ebenfalls mehrere Einträge. Die Dokumentation von Purple enthält eine gepflegte Liste der genau benötigten Einträge, und diese Liste wird auf dem neuesten Stand gehalten, wenn diese Anbieter ihre Infrastruktur aktualisieren.
Es gibt eine kritische Besonderheit bei UniFi, die bei vielen Implementierungen zu Problemen führt. Der HTTP-Redirector auf dem AP fängt nur reinen HTTP-Verkehr auf Port 80 ab. Moderne Geräte - iOS, Android, Windows, macOS - führen alle eine HTTPS-basierte Erkennung von Captive Portals durch. Apple-Geräte rufen captive.apple.com über HTTPS auf. Android-Geräte rufen connectivitycheck.gstatic.com auf. Wenn diese HTTPS-Anfragen keine spezifische Antwort erhalten, entscheidet das Gerät möglicherweise, dass kein Captive Portal vorhanden ist, und zeigt die Anmeldeaufforderung einfach nicht an.
Die Lösung besteht darin, sicherzustellen, dass Ihr Walled Garden die Domains zur Erkennung von Captive Portals für die gängigen Betriebssysteme enthält und dass Ihr Purple-Portal über HTTPS mit einem gültigen, vertrauenswürdigen SSL-Zertifikat erreichbar ist. Selbstsignierte Zertifikate führen zu Sicherheitswarnungen im Browser, die das Laden des Portals blockieren. Dies ist für Produktivumgebungen nicht verhandelbar.
Die andere UniFi-spezifische Überlegung betrifft die Erreichbarkeit des Controllers. Die UniFi Network Application — unabhängig davon, ob sie auf einem Cloud Gateway, einem Cloud Key oder einem selbstgehosteten Server läuft — muss von der Infrastruktur von Purple aus erreichbar sein, damit die API-Autorisierungsaufrufe erfolgreich sind. Wenn sich Ihr Controller in einem privaten Netzwerk hinter NAT befindet, müssen Sie sicherstellen, dass die relevanten API-Ports zugänglich sind. Bei selbstgehosteten Controllern ist dies in der Regel Port 8443 für die Legacy-API oder der Standard-HTTPS-Port 443 für die neuere API, die in Version 9.1 eingeführt wurde. Die Support-Dokumentation von Purple gibt die genauen IP-Bereiche an, die eingehenden Zugriff auf Ihren Controller benötigen.
Für die RADIUS-basierte Authentifizierung - die relevant ist, wenn Sie Purple zusammen mit WPA2-Enterprise- oder WPA3-Enterprise-SSIDs anstelle des offenen Gast-SSID-Modells bereitstellen - unterstützt der integrierte RADIUS-Server von UniFi standardmäßige 802.1X EAP-Methoden. Sie konfigurieren das RADIUS-Profil unter Einstellungen, Netzwerke, RADIUS-Server und verweisen dann in Ihrer SSID-Konfiguration auf dieses Profil. UniFi unterstützt ab Version 8.4 auch RADIUS über TLS, bekannt als RADSEC, wodurch der RADIUS-Verkehr zwischen dem AP und dem Authentifizierungsserver verschlüsselt wird. Für Multi-Site-Bereitstellungen, bei denen der RADIUS-Verkehr über das öffentliche Internet läuft, wird RADSEC dringend empfohlen.
[IMPLEMENTIERUNGSEMPFEHLUNGEN & FALLSTRICKE - ca. 2 Minuten]
Hier ist die praktische Implementierungs-Checkliste, die ich mit jedem Kunden durchgehen würde, der Purple auf UniFi bereitstellt.
Erstens: Netzwerksegmentierung. Ihre Gast-SSID muss sich in einem dedizierten VLAN befinden, isoliert von Ihren Unternehmens- und IoT-Netzwerken. UniFi macht dies einfach - erstellen Sie ein dediziertes Netzwerk unter Einstellungen, Netzwerke, weisen Sie ihm eine VLAN-ID zu und verknüpfen Sie Ihre Gast-SSID mit diesem Netzwerk. Aktivieren Sie die Client-Isolierung im Gastnetzwerk, um Datenverkehr von Gast zu Gast zu verhindern.
Zweitens: Der Controller muss über einen gültigen FQDN und ein vertrauenswürdiges SSL-Zertifikat verfügen. Verlassen Sie sich nicht auf die IP-Adresse. Verwenden Sie einen ordnungsgemäßen Domainnamen, besorgen Sie sich ein Let's Encrypt- oder kommerzielles Zertifikat dafür und konfigurieren Sie UniFi so, dass es dieses Zertifikat verwendet. Dies behebt die Mehrheit der HTTPS-Umleitungsprobleme.
Drittens: Erstellen Sie Ihren Walled Garden sorgfältig und testen Sie ihn. Die Mindesteinträge sind: Ihre Purple Portal-Domain und deren IP-Bereiche, die Captive Portal-Erkennungsdomains für iOS, Android und Windows sowie alle von Ihnen verwendeten OAuth-Anbieterdomains. Testen Sie mit einem Gerät, das noch nie mit dem Netzwerk verbunden war - zwischengespeicherte DNS- und Netzwerkzustände können Lücken im Walled Garden beim Testen maskieren.
Viertens: Verwenden Sie für die API-Integration ein dediziertes lokales Admin-Konto in der UniFi Network Application mit den minimal erforderlichen Berechtigungen. Verwenden Sie nicht Ihre primären Admin-Anmeldedaten. Wenn Sie Network Application 9.1 oder höher verwenden, nutzen Sie den neuen API-Schlüsselmechanismus unter Control Plane, Integrations - dies ist sicherer und erfordert keine anmeldedatenbasierte Authentifizierung.
Fünftens: Berücksichtigen Sie die Sitzungsdauer sorgfältig. Die standardmäßige Sitzungsdauer für Gäste bei UniFi kann auf nur acht Stunden eingestellt sein. Für Implementierungen im Gastgewerbe, bei denen Gäste möglicherweise mehrere Nächte bleiben, konfigurieren Sie die entsprechenden Sitzungsdauern in den Einstellungen des Purple-Portals und stellen Sie sicher, dass diese Dauern im API-Autorisierungsaufruf korrekt übermittelt werden.
Der häufigste Fehler, den ich sehe, ist die Bereitstellung auf einem selbst gehosteten Controller, der nicht öffentlich zugänglich ist. Wenn Purple Ihren Controller nicht erreichen kann, um Gäste zu autorisieren, wird das Portal zwar geladen, aber die Authentifizierung schlägt im Hintergrund fehl. Überprüfen Sie vor dem Live-Gang immer die API-Konnektivität von der Purple-Infrastruktur aus.
[SCHNELLES F&A - ca. 1 Minute]
Funktioniert das auf der UniFi Dream Machine Pro? Ja. Alle UniFi OS-Konsolen - UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max - unterstützen die Konfiguration des External Portal Server. Die Network Application läuft direkt auf dem Gerät.
Kann ich Purple auf mehreren UniFi-Standorten über ein einziges Purple-Konto nutzen? Ja. Die Multi-Site-Architektur von Purple ist genau dafür ausgelegt. Jeder Standort wird als separater Standort in Purple konfiguriert und dem entsprechenden UniFi-Standort zugeordnet.
Muss ich Firewall-Ports auf dem UniFi-Gateway öffnen? Sie müssen sicherstellen, dass der Datenverkehr des Gäste-VLAN den Purple-Portal-Domain auf Port 443 erreichen kann. Der API-Port des Controllers muss ebenfalls von den Purple-Servern aus erreichbar sein. Die Dokumentation von Purple enthält die spezifischen IP-Bereiche.
Wie sieht es mit WPA3 aus? UniFi unterstützt WPA3 Personal und WPA3 Enterprise. Der Captive Portal-Mechanismus funktioniert mit WPA3 Personal in Gästenetzwerken. WPA3 Enterprise verwendet 802.1X und RADIUS, was einen anderen Authentifizierungsablauf darstellt.
[ZUSAMMENFASSUNG & NÄCHSTE SCHRITTE - ca. 1 Minute]
Zusammenfassend lässt sich sagen: Die Bereitstellung von Purple als externes Captive Portal auf UniFi ist eine gut unterstützte, architektonisch solide Integration. Die wichtigsten Schritte sind: Konfigurieren Sie Ihre Gäste-SSID mit der Option External Portal Server, die auf Ihre Purple-Portal-URL verweist, erstellen Sie einen umfassenden Walled Garden, der die Purple-Infrastruktur und alle von Ihnen genutzten OAuth-Anbieter abdeckt, stellen Sie sicher, dass Ihr UniFi-Controller über ein gültiges SSL-Zertifikat verfügt und von den Purple-API-Servern aus erreichbar ist, und konfigurieren Sie die für Ihren Standorttyp angemessenen Sitzungsdauern.
Der Business Case liegt auf der Hand. Das integrierte UniFi-Portal bietet Ihnen eine Splash Page. Purple bietet Ihnen eine DSGVO-konforme, analysebasierte Plattform für das Gästeerlebnis, die sich in Ihr CRM integrieren lässt, First-Party-Daten mit GDPR-Zustimmung erfasst und die Analysen zu Besucherzahlen und Verweildauer liefert, die Standortbetreiber und Marketingteams tatsächlich benötigen.
Wenn Sie ein MSP oder Systemintegrator sind, der UniFi in großem Stil bereitstellt, machen das Multi-Site-Management und die White-Label-Funktionen von Purple es zum richtigen Overlay für Ihre Kunden.
Ausführliche Konfigurationsdokumentationen, Walled-Garden-IP-Listen und API-Integrationshandbücher finden Sie unter purple.ai. Vielen Dank fürs Zuhören.
