UniFi captive portal Einrichtungsleitfaden

Captive Portal for Ubiquiti UniFi - Ein Purple Technical Briefing [EINFÜHRUNG & KONTEXT - ca. 1 Minute] Willkommen zur Purple Technical Briefing Reihe. Ich bin Ihr Moderator, und heute befassen wir uns mit den Besonderheiten der Bereitstellung eines externen Captive Portals auf einer Ubiquiti UniFi Infrastruktur - einer der am häufigsten installierten Netzwerkplattformen im Gastgewerbe, im Einzelhandel und in Unternehmensumgebungen weltweit. Wenn Sie als IT-Manager, Netzwerkarchitekt oder Systemintegrator 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. [TECHNISCHE TIEFENANALYSE - ca. 5 Minuten] Zunächst sollten wir verstehen, was tatsächlich passiert, wenn sich ein Gast mit einer UniFi SSID verbindet, auf 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 „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 um. Gleichzeitig führt der AP einen schlanken HTTP-Redirector auf Port 80 aus. In dem Moment, in dem der Browser des Gasts eine beliebige HTTP-Anfrage stellt - und das ist das Schlüsselwort, HTTP, nicht HTTPS -, sendet der Redirector einen 302-Redirect zurück und leitet den Browser auf die Captive Portal Splash Page weiter. Dies ist der Mechanismus, der die Benachrichtigung „Bei WiFi anmelden“ auf iOS- und Android-Geräten auslöst. Hier wird nun 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 Erfassung von E-Mail-Adressen, keinen Social Login, kein GDPR-Einwilligungsmanagement, keine CRM-Integration und keine aussagekräftigen Analysen, die über die Anzahl der Sitzungen hinausgehen. Wenn Sie einen External Portal Server konfigurieren - was die Einstellung ist, auf die wir uns heute konzentrieren -, weisen Sie den UniFi-Controller an, Gäste auf eine völlig separate Webanwendung umzuleiten. In unserem Fall ist das Purple. Die URL, die Sie in das Feld External Portal Server eingeben, wird zum Ziel für all diese 302-Redirects. 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 APs, 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 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 Autorisierungsendpunkt 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 auf 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 der Konfiguration. 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 verweist. Wenn Sie Social-Login nutzen - Facebook, Google, Microsoft - 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, einschließlich 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 genau 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 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 bestimmte 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 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 produktive Implementierungen 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 selbst gehosteten Server läuft - muss von der Infrastruktur von Purple 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 selbst gehosteten 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 Standard-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-Standort-Bereitstellungen, bei denen der RADIUS-Verkehr über das öffentliche Internet läuft, wird RADSEC dringend empfohlen. [IMPLEMENTATION RECOMMENDATIONS & PITFALLS - ca. 2 Minuten] Lassen Sie mich Ihnen die praktische Checkliste für die Implementierung geben, 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 in den Einstellungen unter 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 dieses Zertifikat verwendet wird. Dies löst 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 Captive Portal-Erkennungsdomänen für iOS, Android und Windows sowie alle von Ihnen verwendeten OAuth-Anbieter-Domains. Testen Sie mit einem Gerät, das noch nie zuvor mit dem Netzwerk verbunden war - zwischengespeicherte DNS- und Netzwerkzustände können Lücken im Walled Garden beim Testen maskieren. Höchstens 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 - dies ist sicherer und erfordert keine anmeldedatenbasierte Authentifizierung. Fünftens: Berücksichtigen Sie die Sitzungsdauer sorgfältig. Die Standard-Gastsitzungsdauer von UniFi kann auf nur acht Stunden eingestellt sein. Für Hotel- und Gastronomie-Umgebungen, in denen Gäste möglicherweise mehrere Nächte bleiben, sollten Sie die Sitzungsdauer in den Purple Portal-Einstellungen entsprechend anpassen und sicherstellen, dass diese Zeiten im API-Autorisierungsaufruf korrekt übergeben 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 zur Autorisierung der Gäste nicht erreichen kann, wird das Portal zwar geladen, aber die Authentifizierung schlägt stillschweigend fehl. Überprüfen Sie vor dem Live-Gang immer die API-Konnektivität von der Purple-Infrastruktur aus. [SCHNELLE FRAGEN UND ANTWORTEN - ca. 1 Minute] Funktioniert das auch mit der UniFi Dream Machine Pro? Ja. Alle UniFi OS-Konsolen - UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max - unterstützen die Konfiguration als External Portal Server. Die Network Application läuft direkt auf dem Gerät. Kann ich Purple für mehrere UniFi-Standorte über ein einziges Purple-Konto nutzen? Ja. Die Multi-Site-Architektur von Purple ist genau dafür ausgelegt. Jeder Standort wird in Purple als separater Standort eingerichtet 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 Portal-Domain über 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 genauen 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 und 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 Infrastruktur von Purple 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 angemessene Sitzungsdauer. Der geschäftliche Nutzen liegt auf der Hand. Das integrierte UniFi-Portal bietet Ihnen eine einfache Begrüßungsseite. Purple bietet Ihnen eine rechtskonforme, analysegestützte Plattform für das Gästeerlebnis, die sich in Ihr CRM integrieren lässt, First-Party-Daten unter Einhaltung der GDPR-Einwilligung erfasst und genau die Besucherstrom- und Verweilzeit-Analysen liefert, die Standortbetreiber 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. Detaillierte Konfigurationsdokumente, Walled-Garden-IP-Listen und API-Integrationshandbücher finden Sie auf purple.ai. Vielen Dank fürs Zuhören.