Podcast-Transkript ansehen
Captive Portal für Ubiquiti UniFi - Ein Purple Technical Briefing
[EINFÜHRUNG & KONTEXT - ca. 1 Minute]
Willkommen zur Purple Technical Briefing-Reihe. Ich bin Ihr Gastgeber, und heute befassen wir uns mit den Besonderheiten der Bereitstellung eines externen Captive Portals auf einer Ubiquiti UniFi-Infrastruktur - einer der am weitesten verbreiteten Netzwerkplattformen im Gastgewerbe, im Einzelhandel und in Unternehmensumgebungen weltweit.
Wenn Sie ein IT-Manager, Netzwerkarchitekt oder Systemintegrator sind, der mit UniFi Cloud Gateways, Dream Machines oder der UniFi Network Application arbeitet, ist diese Episode genau das Richtige für Sie. Wir werden genau erklären, wie der externe Portal-Mechanismus unter der Haube funktioniert, wie man ihn richtig konfiguriert, wo die häufigsten Stolpersteine 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]
Zunächst sollten wir verstehen, 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 Gäste-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 "ausstehend" 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 weiter.
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-Weiterleitung zurück, die den Browser zur Captive Portal Splash Page schickt. Dies ist der Mechanismus, der die Benachrichtigung "Bei WiFi anmelden" auf iOS- und Android-Geräten auslöst.
An dieser Stelle wird die Unterscheidung 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 - und das ist die Einstellung, auf die wir uns heute konzentrieren -, weisen Sie den UniFi-Controller an, Gäste an eine völlig separate Webanwendung weiterzuleiten. 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-Weiterleitungen.
Hier ist das wichtige technische Detail zu dieser Redirect-URL. Wenn UniFi einen Gast zu Ihrem externen Portal weiterleitet, hängst es mehrere Query-Parameter an die URL an. Dazu gehören: die AP-MAC-Adresse, die MAC-Adresse des Client-Geräts, ein Unix-Zeitstempel, die ursprüngliche URL, die der Client erreichen wollte, und der SSID-Name. Ihr externes Portal - in diesem Fall Purple - erfasst diese Parameter, nutzt 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 zur UniFi-Netzwerkanwendung aus, um diese MAC-Adresse zu autorisieren.
Dieser API-Aufruf ist der entscheidende Handshake. Seit der UniFi-Netzwerkanwendung Version 9.1 und neuer gibt es eine offizielle REST-API mit ordnungsgemäßer schlüsselbasierter Authentifizierung. Der Autorisierungs-Endpunkt ist eine POST-Anfrage an Version eins der Sites-API, die auf die spezifische Client-ID abzielt, mit einem JSON-Body, der Zeitlimits in Minuten, Datennutzungslimits in Megabyte und Ratenbegrenzungen in Kilobit pro Sekunde angeben kann. Sobald der Controller diese Autorisierung erhält, leitet er die Anweisung an den AP weiter, und der Gast 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 unverzichtbar und eine der häufigsten Fehlerquellen bei Fehlkonfigurationen.
Ihr Walled Garden muss mindestens den vollqualifizierten Domainnamen Ihres Purple-Portals und die IP-Adressen oder CIDR-Bereiche enthalten, auf die die Infrastruktur von Purple auflöst. 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 bietet eine gepflegte Liste der genauen erforderlichen 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 unverschlüsselten HTTP-Verkehr auf Port 80 ab. Moderne Geräte - iOS, Android, Windows, macOS - führen alle eine HTTPS-basierte Captive Portal-Erkennung 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 Captive Portal-Erkennung für die wichtigsten 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 mit Version 9.1 eingeführt wurde. Die Support-Dokumentation von Purple spezifiziert die genauen IP-Bereiche, 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 in UniFi integrierte RADIUS-Server 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-Datenverkehr zwischen dem AP und dem Authentifizierungsserver verschlüsselt wird. Für Bereitstellungen an mehreren Standorten, bei denen der RADIUS-Datenverkehr über das öffentliche Internet läuft, wird RADSEC dringend empfohlen.
[IMPLEMENTIERUNGSEMPFEHLUNGEN & HINDERNISSE - ca. 2 Minuten]
Lassen Sie mich Ihnen die praktische Implementierungs-Checkliste an die Hand geben, die ich mit jedem Kunden durchgehen würde, der Purple auf UniFi bereitstellt.
Erstens: Netzwerksegmentierung. Ihre Gast-SSID muss sich auf 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, installieren Sie ein Let's Encrypt- oder kommerzielles Zertifikat darauf und konfigurieren Sie UniFi so, dass es dieses Zertifikat verwendet. Dies behebt die Mehrheit der HTTPS-Weiterleitungsprobleme.
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 Domains zur Erkennung des Captive Portal für iOS, Android und Windows sowie alle von Ihnen genutzten OAuth-Provider-Domains. Testen Sie mit einem Gerät, das noch nie zuvor mit dem Netzwerk verbunden war - zwischengespeichertes DNS und der Netzwerkstatus können Lücken im Walled Garden während des Testens 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 die Network Application 9.1 oder neuer verwenden, nutzen Sie den neuen API-Schlüssel-Mechanismus unter Control Plane, Integrationen - dieser ist sicherer und erfordert keine auf Anmeldedaten basierende Authentifizierung.
Fünftens sollten Sie die Sitzungsdauer sorgfältig prüfen. Der Standard-Ablauf der Gastsitzung bei UniFi kann auf nur acht Stunden eingestellt sein. Für Hotel- und Gastronomie-Bereitstellungen, bei denen Gäste mehrere Nächte bleiben, konfigurieren Sie die entsprechenden Sitzungsdauern in den Einstellungen des Purple Hub und stellen Sie sicher, dass diese Dauern im API-Autorisierungsaufruf korrekt übermittelt werden.
Die häufigste Fehlerquelle, die 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 stillschweigend fehl. Überprüfen Sie vor der Liveschaltung immer die API-Konnektivität von der Purple-Infrastruktur aus.
[SCHNELLE FRAGEN & ANTWORTEN - 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 für externe Portalserver. 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 Veranstaltungsort 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 Gast-VLANs die Purple-Portaldomain über Port 443 erreichen kann. Der Controller-API-Port 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 Gastnetzwerken. 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 Gast-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 verwendeten 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 geschäftliche Nutzen liegt auf der Hand. Das integrierte UniFi-Portal bietet Ihnen lediglich eine Begrüßungsseite. Purple bietet Ihnen eine konforme, analysengesteuerte Plattform für das Gästeerlebnis, die sich in Ihr CRM integrieren lässt, First-Party-Daten mit GDPR-Einwilligung erfasst und die Analysen zu Besucherzahlen und Verweildauer liefert, die Betreiber von Veranstaltungsorten und Marketingteams tatsächlich benötigen.
Wenn Sie als MSP oder Systemintegrator UniFi in großem Stil bereitstellen, machen die Multi-Site-Verwaltung und die White-Label-Funktionen von Purple es zum idealen Overlay für Ihre Kunden.
Ausführliche Dokumentationen zur Konfiguration, Walled-Garden-IP-Listen und API-Integrationshandbücher finden Sie unter purple.ai. Vielen Dank fürs Zuhören.
