Ubiquiti UniFi Captive Portal Fehlerbehebung: Checkliste für externes Portal, Hotspot und Walled Garden

Ein UniFi Captive Portal funktioniert aus einem von fünf Gründen nicht. Die Adresse des externen Portalservers ist falsch, oder die Portal- und Login-Domains fehlen beim Pre-Authorisation Access. Die Gastisolierung blockiert möglicherweise den Portal-Host. Die Weiterleitung nutzt eventuell HTTP zu einer IP-Adresse. Oder die Konsole ist nicht erreichbar. Prüfen Sie diese Punkte nacheinander und testen Sie sie dann von einem Client aus.

Wie sieht ein UniFi Captive Portal aus, das nicht funktioniert?

Die meisten Fehler zeigen sich in Form von einem von vier Symptomen. Wenn Sie das Symptom zuerst benennen, grenzt das die Ursache ein, bevor Sie die UniFi Netzwerk-Anwendung öffnen.

• Kein Portal vorhanden. Das Gerät verbindet sich mit der Gäste-SSID und erhält eine IP-Adresse, aber es erscheint keine Aufforderung zur Anmeldung. Das Telefon meldet eventuell "kein Internet" oder zeigt an, dass es ohne Datenverkehr verbunden ist.
• Eine leere oder endlos ladende Seite. Der Captive Network Assistant (CNA) öffnet sich, aber die Splash Page wird nie gerendert. Der CNA ist der kleine Browser, den Ihr Betriebssystem in einem Captive Network startet.
• Eine Zertifikatswarnung. Laptops zeigen vor der Anmeldeseite "Ihre Verbindung ist nicht privat" an. Gäste müssen eine Warnung wegklicken, um fortzufahren.
• Ein unvollständiges Portal. Die Splash Page lädt, aber ein Social Login oder ein Zahlungs-Button dreht sich, schlägt fehl oder führt zu einer Schleife.

Der Captive Portal Support-Artikel von Purple erklärt den CNA genauer. Der CNA prüft eine vordefinierte Domain, um zu testen, ob das Internet erreichbar ist. Er benachrichtigt dann das Gerät, startet einen Browser und bestätigt den Status "Online". Wenn ein Teil dieser Kette bricht, sehen Ihre Gäste eines der oben genannten Symptome.

Diese Anleitung setzt voraus, dass Ihr UniFi Hotspot-Portal oder externes Portal bereits konfiguriert ist. Es handelt sich um eine Checkliste zur Fehlersuche, nicht um eine Einrichtungsanleitung.

Was sind die typischen Ursachen für den Ausfall eines UniFi Captive Portals?

Sechs Ursachen machen den Großteil aller Fehlerfälle beim UniFi Gäste-Portal aus.

1. Falsche Einstellung des externen Portalservers. Die Adresse verweist auf einen alten Host, enthält einen Tippfehler oder führt zu einem Server, den das Gateway nicht erreichen kann.
2. Unvollständiger Pre-Authorisation Access. UniFi bezeichnet diese Einstellung als "Pre-Authorization Access". Dies ist der Walled Garden von UniFi: die Hosts und Subnetze, die ein Gast vor der Anmeldung erreichen kann. Wenn das Portal, seine Ressourcen oder ein Social Login-Anbieter fehlen, bleibt die Seite leer oder unvollständig.
3. Einschränkungen des Gästenetzwerks. UniFi Gästenetzwerke blockieren private Adressbereiche. Ein Portalserver oder DNS-Server in einem internen Subnetz wird dadurch unerreichbar.
4. Fehlpaarungen bei HTTPS- und Hostnamen-Weiterleitungen. Eine HTTPS-Weiterleitung auf eine IP-Adresse oder auf einen Hostnamen ohne passendes Zertifikat löst Browser-Warnungen aus.
5. Erreichbarkeit des Controllers oder der Konsole. Selbst gehostete UniFi Network Server und Cloud-Konsolen müssen erreichbar bleiben. Bei einem externen Portal muss der Controller zudem den RADIUS-Server erreichen können, der die Anmeldung abschließt.
6. Client-seitige Störungen. VPNs, benutzerdefinierte DNS-Einstellungen oder eine geschlossene CNA-Benachrichtigung verhindern die Weiterleitung auf diesem Gerät.

Wie finden Sie heraus, welcher UniFi Captive Portal Fehler bei Ihnen vorliegt?

Starten Sie mit dem Symptom und führen Sie die erste Prüfung in der Tabelle durch, bevor Sie Einstellungen ändern.

Symptom	Wahrscheinlichste Ursache	Erste Prüfung	Behebung
Kein Portal, keine Aufforderung	DNS nicht erreichbar oder CNA-Probe blockiert	Kann der Client vor dem Login einen öffentlichen Hostnamen auflösen?	Stellen Sie einen DNS-Server außerhalb der blockierten privaten Bereiche bereit oder lassen Sie ihn im Pre-Authorisation Access zu
Leere oder endlos ladende Seite	Portal-Host oder Assets fehlen im Pre-Authorisation Access	Lässt sich der Portal-Hostname von einem Gastgerät aus auflösen und laden?	Fügen Sie den Portal-Host, seine Asset-Domains und sein Subnetz zum Pre-Authorisation Access hinzu
Zertifikatswarnung auf Laptops	HTTPS-Weiterleitung an eine IP-Adresse oder falscher Hostname	Welche URL wird bei der Warnung in der Adresszeile angezeigt?	Deaktivieren Sie die HTTPS-Weiterleitung oder leiten Sie per Hostname mit einem öffentlich vertrauenswürdigen Zertifikat weiter, das zu diesem Hostnamen passt
Social-Login-Button lädt endlos oder schlägt fehl	Domains des Identity Providers fehlen	Welche Domain schlägt in der Netzwerkansicht des Browsers fehl?	Fügen Sie jede Domain hinzu, die die Login-Seite des Anbieters lädt
Zahlungsschritt schlägt fehl	Domains des Payment Gateways fehlen	Lädt die Zahlungsseite überhaupt?	Fügen Sie die Hosts des Zahlungsanbieters zum Pre-Authorisation Access hinzu
Portal lädt, aber Login wird nie abgeschlossen	RADIUS oder Controller nicht erreichbar	Erscheinen Authentifizierungsversuche in den Controller-Ereignissen?	Stellen Sie die Erreichbarkeit des Controllers wieder her und bestätigen Sie, dass die RADIUS-Details mit denen Ihres Portal-Anbieters übereinstimmen
Ein Gerät schlägt fehl, andere funktionieren	Client-seitiges VPN, benutzerdefiniertes DNS oder geschlossenes CNA	Funktioniert die Weiterleitung auf neverssl.com auf diesem Gerät?	Deaktivieren Sie das VPN oder das benutzerdefinierte DNS, ignorieren Sie das Netzwerk und treten Sie erneut bei

Zwei schnelle Tests grenzen die meisten Fehler ein. Rufen Sie zuerst neverssl.com auf einem verbundenen, aber nicht authentifizierten Gerät auf. Das Support-Team von Purple empfiehlt diese Seite, da sie Probleme mit SSL-Weiterleitungen vermeidet. Wenn neverssl.com zu Ihrem Portal weiterleitet, funktioniert die Weiterleitung und der Fehler liegt im Pre-Authorisation Access oder im Portal selbst. Wenn keine Weiterleitung erfolgt, überprüfen Sie das DNS, die Einstellung für den externen Portalserver oder den Controller.

Prüfen Sie zweitens den Client-Eintrag in der UniFi-Netzwerkanwendung. Die Client-Liste und die Ereignisse zeigen, ob sich das Gerät im Gastnetzwerk befindet und ob es autorisiert wurde. Ein Gerät, das als autorisiert markiert ist, aber immer noch das Portal anzeigt, deutet auf einen Client-seitigen Cache oder ein CNA-Problem hin.

Wie behebt man die einzelnen Ursachen des UniFi Captive Portals?

Purple bildet hier keine Menüpfade von UniFi ab, da sich diese zwischen den Versionen von UniFi Network ändern. Nutzen Sie die aktuelle Dokumentation von Ubiquiti für den genauen Speicherort der jeweiligen Einstellung.

Externer Portalserver

Stellen Sie sicher, dass der Wert für den externen Portalserver genau mit den Angaben Ihres Portal-Anbieters übereinstimmt. Ein einziges falsches Zeichen leitet jeden Gast auf einen toten Host um. Wenn Sie den Portal-Anbieter gewechselt haben, entfernen Sie die alte Adresse, anstatt sie neben der neuen stehenzulassen.Wenn Sie Purple verwenden, erfassen die Server der Splash Page die Gastdaten und erstellen ein einmaliges Login. Der Controller leitet dieses Login an den RADIUS-Server von Purple weiter, um die Authentifizierung abzuschließen. RADIUS ist das Protokoll, das Netzwerkgeräte verwenden, um Anmeldedaten mit einem zentralen Server abzugleichen. Wenn das Portal geladen wird, aber die Anmeldung fehlschlägt, überprüfen Sie als Nächstes das RADIUS-Profil.

Vorab-Autorisierungszugriff für das Portal, Social Login und Zahlungsdomänen

Dies ist die häufigste Lösung. Fügen Sie diese Einträge zum Vorab-Autorisierungszugriff hinzu:

• Der Host des Portalservers und jedes Subnetz, in dem er sich befindet.
• Jede Domäne, die von der Splash Page geladen wird, einschließlich Schriftarten, Bilder und Skripte von Content Delivery Networks.
• Die Authentifizierungsdomänen jedes Social-Login-Anbieters, wenn Sie die Anmeldung über Facebook, Google oder Apple anbieten.
• Die Hosts Ihres Zahlungs-Gateways, wenn Sie Gebühren für Premium-Zugang verlangen.

Öffnen Sie die Splash Page von einem Laptop in einem uneingeschränkten Netzwerk aus, wobei die Entwicklertools des Browsers die Netzwerkanfragen anzeigen. Jede dort aufgelistete Domäne muss vor dem Login erreichbar sein. Wenn Ihre UniFi-Netzwerkversion nur IP-Einträge akzeptiert, überprüfen Sie diese jedes Mal, wenn ein Anbieter seine Adressen ändert.

Gastnetzwerk-Isolierung und blockierte Subnetze

Die Gast-Isolierung blockiert das Captive Portal nicht von sich aus. Die Isolierung von Client-Geräten verhindert, dass Gastgeräte miteinander kommunizieren. Die Subnetz-Einschränkungen des Gastnetzwerks blockieren private Adressbereiche, und diese Einschränkungen betreffen auch interne Portal- oder DNS-Server.

Wenn sich Ihr Portalserver oder DNS-Resolver in einem internen Subnetz befindet, fügen Sie diesen spezifischen Host zum Vorab-Autorisierungszugriff hinzu. Ein saubereres Muster besteht darin, Gästen einen öffentlichen DNS-Resolver zuzuweisen und das Portal auf einer öffentlichen Adresse zu hosten.

HTTPS- und Hostnamen-Weiterleitungsoptionen

Moderne Browser erwarten HTTPS für Anmelseiten. Der Purple Artikel zum Cisco WLC-Zertifikat beschreibt dasselbe Muster auf Cisco Hardware. Eine Weiterleitung zu einer HTTP-Adresse wie einer bloßen IP löst eine Sicherheitswarnung aus, die Gäste wegklicken müssen.

Die Lösung folgt auf UniFi demselben Prinzip. Lassen Sie entweder die HTTPS-Weiterleitung deaktiviert und erlauben Sie dem CNA, HTTP zu verwenden, oder leiten Sie nach Hostnamen weiter. Eine Hostnamen-Weiterleitung erfordert ein öffentlich vertrauenswürdiges SSL/TLS-Zertifikat, und der Hostname muss mit dem Common Name des Zertifikats übereinstimmen. Ein selbstsigniertes Zertifikat oder ein nicht übereinstimmender Name führt direkt wieder zur Warnung.

Controller-Erreichbarkeit für selbstgehostete und Cloud-Konsolen

Bestätigen Sie bei einem selbstgehosteten UniFi Network Server, dass der Server läuft und von Ihrem Gateway und Ihren Access Points aus erreichbar ist. Überprüfen Sie die Firewall-Regeln zwischen den Standorten, wenn sich der Server in einer Hauptniederlassung oder einem Rechenzentrum befindet. Bestätigen Sie bei Cloud-Konsolen, dass die Konsole online ist und das Gateway eingebunden ist. Bestätigen Sie anschließend, dass ausgehender Datenverkehr an Ihren RADIUS-Server zulässig ist.

Client-Prüfungen

Bitten Sie den Gast, das Netzwerk zu ignorieren und sich erneut anzumelden. Deaktivieren Sie alle VPNs oder benutzerdefinierten DNS-Einstellungen, da diese die Weiterleitung komplett umgehen können. Wenn die CNA-Benachrichtigung verpasst wurde, öffnen Sie einen Browser und rufen Sie neverssl.com auf. Unter Android startet das Tippen auf die Benachrichtigung "Möglicherweise müssen Sie sich anmelden" die CNA-Browsersitzung.

Praxisbeispiele aus Hotellerie, Einzelhandel und Events

Diese Praxisbeispiele zeigen, wie die Checkliste auf Standortebene funktioniert.

Ein 200-Zimmer-Hotel mit einer leeren Splash Page

Situation. Ein Hotel betrieb einen selbstgehosteten UniFi Network Server und ein externes Portal. Nach einer Netzwerkänderung sahen Gäste auf der Gäste-SSID eine leere Seite. Die Rezeption verzeichnete rund ein Dutzend Beschwerden pro Nacht.

Was getan wurde. neverssl.com leitete nicht weiter, daher überprüfte das Team zuerst das DNS. Der DHCP-Bereich des Gäste-VLANs wies einen internen DNS-Server in einem privaten Subnetz zu. Die Gästebeschränkungen blockierten dieses Subnetz. Das Team stellte den Gästebereich auf einen öffentlichen Resolver um.

Ergebnis. Die Portal-Weiterleitungen funktionierten bei der nächsten Verbindung. Die Rezeption verzeichnete in dieser Woche keine weiteren WiFi-Beschwerden.

Eine Einzelhandelskette mit 40 Filialen und blockiertem Social-Login

Situation. Eine Kette im Einzelhandel fügte ihrer Splash Page ein Social-Login hinzu. Das E-Mail-Formular funktionierte, aber der Social-Button lud in jeder Filiale unendlich lange.

Was getan wurde. Das Team öffnete die Splash Page mit den Entwicklertools und listete jede Domain auf, die das Login des Anbieters lud. Diese wurden in einer Pilotfiliale zu den Pre-Authorisation-Zugriffen hinzugefügt, unter Android und iOS getestet und anschließend auf alle 40 Filialen ausgerollt.

Ergebnis. Das Social-Login funktionierte in allen 40 Filialen. Das Team testet die Pilotfiliale nun nach jedem Anbieter-Update erneut.

Ein Konferenzzentrum mit Zertifikatswarnungen

Situation. Teilnehmer auf Laptops sahen vor dem Portal die Meldung "Ihre Verbindung ist nicht privat". Smartphones funktionierten über die CNA, sodass der Fehler unregelmäßig erschien.

Was getan wurde. Die Adressleiste zeigte eine HTTPS-Weiterleitung zu einer IP-Adresse. Das Team deaktivierte die HTTPS-Weiterleitung, bis ein öffentlich vertrauenswürdiges Zertifikat installiert war, das mit dem Hostnamen der Weiterleitung übereinstimmte.

Ergebnis. Die Warnung verschwand auf den Laptops. Der Event-Helpdesk erhielt für den Rest der Konferenz keine Portal-Tickets mehr.

Wie verhindern Sie, dass das UniFi Captive Portal erneut ausfällt?

• Führen Sie ein Pre-Authorisation-Register. Listen Sie jeden Host und jedes Subnetz auf, warum es existiert und wem es gehört. Überprüfen Sie es, wenn Sie eine neue Login-Methode oder einen Zahlungsanbieter hinzufügen.
• Testen Sie nach jeder Änderung. Verwenden Sie ein Android-Smartphone, ein iPhone und einen Laptop. Bestätigen Sie, dass neverssl.com weiterleitet und der Login erfolgreich abgeschlossen wird.
• Überwachen Sie den Zertifikatsablauf. Ein abgelaufenes Zertifikat bei einer Hostnamen-Weiterleitung erzeugt dieselbe Warnung wie ein fehlendes Zertifikat.
• Überwachen Sie den Controller. Richten Sie Alarme ein, wenn ein selbstgehosteter Server offline geht, bevor die Gäste es bemerken.
• Betreiben Sie ein offenes Gästenetzwerk. Purple empfiehlt offene Gästenetzwerke, da Vertrautheit die Reibung beim Login verringert. Dieselbe Disziplin gilt auch für andere Hersteller. Purples Leitfaden zur Fehlerbehebung für das HPE Aruba Captive Portal und der Leitfaden zur Fehlerbehebung für das Cisco Meraki Captive Portal folgen derselben Checkliste für diese Plattformen.

Häufig gestellte Fragen

Funktioniert Purple mit den Ubiquiti UniFi Access Points, die wir bereits besitzen?

Ja, Purple läuft auf Ubiquiti UniFi als externes Portal und RADIUS-Service, sodass Sie Ihre bestehenden Access Points behalten können. Purple ist hardwareunabhängig und unterstützt auch Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Cambium, Extreme und Fortinet. Das ist wichtig für Standorte mit gemischter Hardware, da eine einzige Guest WiFi Konfiguration alle Hersteller abdeckt. Die Plattform von Purple läuft laut eigenen Angaben an über 80.000 Live-Standorten.

Können wir einen selbstgehosteten UniFi Network Server mit einem externen Portal weiter nutzen?

Ja, ein selbstgehosteter UniFi Network Server funktioniert mit einem externen Portal, vorausgesetzt, er bleibt erreichbar. Das Gateway und die Access Points müssen den Server erreichen und der Server muss den RADIUS-Service Ihres Portalanbieters erreichen. Überprüfen Sie die Firewall-Regeln zwischen den Standorten, wenn sich der Server in einer Zentrale befindet. Cloud-Konsolen nehmen Ihnen das Hosting ab, benötigen aber dennoch ausgehenden Zugriff auf RADIUS.

Sollte unser UniFi Gastnetzwerk offen oder passwortgeschützt sein?

Für den Gastzugang wird ein offenes Netzwerk empfohlen. Purple empfiehlt, Guest WiFi über ein offenes Netzwerk bereitzustellen, da dies inzwischen der Standard ist und Reibungsverluste beim Login reduziert. Das Captive Portal steuert weiterhin den Zugriff, erfasst bewusste Opt-ins und weist jedem Gast ein einmaliges Login zu. Passwortgeschützte Gastnetzwerke erfordern einen zusätzlichen Schritt und führen zu mehr Nachfragen am Empfang.

Müssen wir ein SSL-Zertifikat für unser Captive Portal kaufen?

Ja, wenn Sie Gäste über HTTPS oder per Hostnamen weiterleiten. Browser erwarten ein öffentlich vertrauenswürdiges Zertifikat, und der Hostname der Weiterleitung muss mit dem Common Name des Zertifikats übereinstimmen. Ohne ein solches Zertifikat zeigen Laptops eine Sicherheitswarnung an, bevor das Portal geladen wird. Wenn Sie kein Zertifikat verwalten können, lassen Sie die HTTPS-Weiterleitung deaktiviert und erlauben Sie dem CNA des Geräts stattdessen eine HTTP-Weiterleitung.

Wie wirkt sich der Wechsel zu Purple auf unsere GDPR-Konformität aus?

Purple hilft Ihnen, die GDPR einzuhalten, anstatt zusätzliche Risiken zu schaffen. Purple besitzt Zertifizierungen nach ISO 27001, GDPR, CCPA und Cyber Essentials, und die Splash Page erfasst bewusste Opt-ins für Marketing-Zustimmungen. Die von Ihnen erfassten First-Party-Daten bleiben an die Einwilligung des jeweiligen Gasts gebunden. Ihre eigenen Datenschutzhinweise und Aufbewahrungsrichtlinien gelten weiterhin, prüfen Sie daher beide vor dem Start.

Wie viel Aufwand ist der Wechsel vom integrierten UniFi Hotspot zu Purple?

Der Wechsel zu Purple ist eine reine Konfigurationsänderung, kein Hardwareprojekt. Sie weisen den externen Portalserver und die RADIUS-Einstellungen auf Purple hin und aktualisieren dann den Pre-Authorisation-Zugriff für die Splash-Page-Domains. Purple legt sich über Ihre bestehende UniFi-Infrastruktur, sodass kein Austausch von Hardware erforderlich ist. Testen Sie zuerst einen Standort und kopieren Sie die Einstellungen dann auf Ihr gesamtes Netzwerk.

Kann Purple Gast-Logins an stark frequentierten Standorten bewältigen?

Ja, Purple hat laut eigenen Angaben im Jahr 2024 440 Millionen Logins verarbeitet. Dieses Volumen verteilt sich auf Hotels, den Einzelhandel, Züge und Standorte im Gesundheitswesen mit extremen Spitzenzeiten. Bei UniFi ist die Kapazität am Portal selten der Engpass. Die Erreichbarkeit des DNS und ein vollständiger Pre-Authorisation-Zugriff sind wichtiger - überprüfen Sie daher diese Checkliste vor einer großen Veranstaltung.