Ubiquiti UniFi Guest Portal leitet nicht weiter: Ursachen und Lösungen

Ein UniFi Captive Portal leitet in der Regel nicht mehr weiter, weil die SSID kein aktiver Hotspot mehr ist, sich der Gastbenutzer nicht im unautorisierten Zustand befindet, die erforderlichen Pfade für die Vorautorisierung den externen Dienst nicht erreichen können oder das Portal die Autorisierung nicht an UniFi übermitteln kann. Überprüfen Sie diese Schritte genau in dieser Reihenfolge 1 2 3.

Welche Bedingungen müssen erfüllt sein, damit die UniFi Gästeweiterleitung funktioniert?

Dies ist eine Anleitung zur Fehlerbehebung für eine zuvor funktionierende Konfiguration. Sie werden nicht aufgefordert, Ihr Gäste WiFi Netzwerk von Grund auf neu aufzubauen. Stattdessen führt die Anleitung vom Gästegerät zum Controller und dann über den externen Dienst wieder zurück. Diese Reihenfolge verhindert einen häufigen Fehler: das Ändern einer SSID, Firewall oder DNS-Einstellung, bevor man überhaupt weiß, welcher Schritt tatsächlich fehlgeschlagen ist.

Ubiquiti definiert einen Hotspot als die Funktion, die auf eine WiFi SSID oder ein gesamtes Netzwerk oder VLAN angewendet werden kann. Das Captive Portal wird dann innerhalb dieser Hotspot-Konfiguration aktiviert. Folglich beweisen ein Gäste-VLAN, eine Gäste-SSID oder eine Richtlinie zur Netzwerkisolierung für sich genommen nicht, dass der Weiterleitungsfluss aktiv ist. Wenn sich die Benutzeroberfläche der UniFi Network-Anwendung nach einem Update geändert hat, bestätigen Sie den aktuellen Status von Hotspot und Captive Portal anhand der offiziellen Dokumentation von Ubiquiti, anstatt sich auf die historische Menüposition zu verlassen. 1

Für ein externes Portal beschreibt Ubiquiti einen präzisen Benutzerpfad. Ein Gerät verbindet sich mit einer SSID, die mit Hotspot und Captive Portal konfiguriert ist. Es startet als GUEST mit authorised: false. Wenn es versucht, eine Webanfrage zu senden, leitet UniFi es an den externen Portalserver weiter. Der Server empfängt die Identifikationsdaten des Clients und des Access Points, ruft die UniFi Client-ID ab und fordert dann die Autorisierung über die Network API an. Ein erfolgreich abgeschlossener Ablauf führt zu authorised: true. 2

Die Diagnoseregel: Betrachten Sie den Zustand "mit dem WiFi verbunden" nicht als Erfolgsbedingung. Die Erfolgsbedingung ist ein nicht autorisierter Test-Client, der den vorgesehenen Anmeldedienst erreicht, dessen Prozess abschließt, authorised: true anzeigt und dann den vorgesehenen Zugriff erhält. 2

Was benötigen Sie, bevor Sie mit der Fehlereingrenzung beginnen?

Verwenden Sie ein frisches, nicht autorisiertes Testgerät. Ein bereits autorisiertes Gerät ist ein schlechtes Diagnosewerkzeug, da es den Schritt überspringen kann, den Sie untersuchen müssen. Protokollieren Sie die SSID oder den Netzwerknamen, die Testzeit, den Gerätetyp, das Betriebssystem und ob das Gerät eine automatische Aufforderung zur Anmeldung oder nur ein normales Browserergebnis anzeigt. Apple gibt an, dass iOS und macOS beim ersten Zugriff auf ein Netzwerk ein Signal senden, um das Abfangen des Captive Portal zu erkennen und eine Anmeldeseite anzuzeigen. Das bedeutet, dass das Fehlen eines automatischen Fensters ein nützlicher Hinweis ist, aber kein schlüssiger Beweis dafür, dass das Gateway eine normale Browseranfrage nicht umleiten kann. 4

Halten Sie den Test eingegrenzt. Beginnen Sie nicht mit dem Hinzufügen von umfassenden Zugriffsregeln für Gäste. Löschen Sie keine funktionierende Integration. Kopieren Sie keine Zulassungsliste für die Vorautorisierung von einem anderen Standort. Sie müssen den tatsächlichen Pfad des Gastes und die genaue Phase ermitteln, in der er abbricht. Wenn das Problem an mehreren Standorten auftritt, führen Sie denselben Test mit einem frischen Gerät an jedem Standort durch. Ein Unterschied zwischen den Standorten ist nützlicher als eine Theorie über ein gemeinsames Controller-Update. Halten Sie für eine Bereitstellung von Purple den aktuellen Artikel UniFi Integration: Best Practices & Common Questions während des Tests geöffnet. Purple nutzt eine direkte API-Anmeldung des Controllers anstelle eines RADIUS-Hintergrund-Authentifizierungskanals. Das dedizierte API-Konto muss daher lokal auf dem Controller liegen, über Administrator-Schreibrechte verfügen, 2FA deaktiviert haben und darf keine Kennwortänderung erfordern. Purple dokumentiert auch verschiedene Anforderungen an die Kontoplatzierung für Hardware-Konsolen und den selbstgehosteten UniFi OS Server. 3

Wie isoliert man den fehlgeschlagenen Schritt?

Beginnen Sie auf der Zugriffsebene. Bestätigen Sie, dass die betroffene WiFi-SSID oder die entsprechende Konfiguration des gesamten Netzwerks weiterhin als Hotspot mit aktiviertem Captive Portal konfiguriert ist. Ubiquiti dokumentiert den aktuellen WiFi-SSID-Pfad und separat einen Hotspot-Zonen-Pfad für eine netzwerkweite oder VLAN-Konfiguration. Diese Unterscheidung ist die Antwort auf die häufige Verwirrung bezüglich UniFi guest network vs hotspot. Ein isoliertes Gastnetzwerk kann das richtige Segment sein und dennoch den Anmeldeflow nicht starten, wenn die Hotspot-Funktion nicht aktiv ist. 1 Überprüfen Sie als Nächstes den neu verbundenen Client. Sie müssen den dokumentierten nicht autorisierten Status überprüfen, nicht nur eine einfache drahtlose Verbindung. Wenn der Status nicht vorhanden ist, kehren Sie zur Hotspot-Konfiguration und der ausgewählten SSID oder dem Netzwerk zurück. Fahren Sie erst mit DNS, einem externen Anbieter oder einer UDM Pro-Integration fort, wenn dieser Schritt korrekt ist. Ein externer Dienst kann keinen Gast autorisieren, der den externen Hotspot-Flow nie betreten hat. 2

Lösen Sie dann eine normale Webanfrage von demselben Gerät aus. Wenn die Anfrage den externen Dienst erreicht, speichern Sie das Ergebnis als Beleg. Wenn nicht, konzentrieren Sie sich auf den Pre-Authorization-Pfad des Gastsegments. Purple verbindet Gäste erst nach Abschluss ihres externen Prozesses, und die Support-Richtlinien bringen einen leeren Bildschirm nach dem Absenden des Formulars mit Gastregeln in Verbindung, die den für den Abschluss des Logins erforderlichen versteckten Web-Traffic blockieren. Überprüfen Sie die Pre-Auth-ACL und die Post-Authorization-Einstellungen. Deklarieren Sie die wesentlichen Ziel-Routing-Pfade aus der aktuellen Dokumentation des Anbieters. 3

In dieser Phase müssen Sie den Begriff allow list präzise beibehalten. Es handelt sich hierbei nicht um eine Liste allgemeiner Web-Ziele für einen autorisierten Gast. Es ist die Menge der Pfade, die vor der Genehmigung erforderlich sind, wie z. B. der externe Dienst und die Elemente, die zum Abschluss der Anmeldetransaktion benötigt werden. Der Support-Artikel von Purple ist die maßgebliche Quelle für die aktuellen Anforderungen. Fügen Sie den Link zum Support-Artikel in Ihr Incident-Ticket ein und erfassen Sie das Versionsdatum, anstatt eine kopierte und veraltete Liste in ein Runbook einzubetten. 3

Wie überprüft man die Autorisierung des externen Portals und den UDM-Pfad?

Wenn die Anmeldeseite geladen wird, wechselt Ihre Untersuchung vom Abfangen zur Autorisierung. Ubiquiti gibt an, dass die Weiterleitung die MAC-Adresse des Access Points, die MAC-Adresse des Clients, die ursprünglich angeforderte URL und die SSID an das externe Portal übergibt. Der externe Dienst kann die MAC-Adresse des Clients verwenden, um die Client-ID von der Netzwerk-API abzurufen, und dann eine Autorisierungsanfrage senden. Die Bestätigung auf der Controller-Seite ist der Status authorised: true des Clients. 2

Prüfen Sie die Nachweise in dieser Reihenfolge. Erstens: Hat der Provider eine Weiterleitung für den betroffenen Client erhalten? Zweitens: Hat er denselben Client identifiziert, den UniFi auflistet? Drittens: Hat er eine Autorisierungsanfrage gesendet? Viertens: Hat UniFi den Client als autorisiert gemeldet? Diese Sequenz bietet einem lokalen IT-Team und einem MSP ein gemeinsames Incident-Protokoll. Zudem unterbricht sie den unproduktiven Kreislauf, in dem eine Partei behauptet, „das Portal wurde geladen“, während die andere darauf beharrt, dass „die Firewall in Ordnung ist“.

Das Thema rund um das UDM Pro guest portal erfordert dieselbe Überprüfung, mit einer zusätzlichen Kontrolle der Controller-Klassifizierung. Die Richtlinien von Purple weisen darauf hin, dass aktuelle Bereitstellungen auf UniFi-Hardwarekonsolen und modernen Versionen von UniFi OS Server die aktuelle Integrationsoption von UniFi Network verwenden müssen, während nur ältere, nicht aktualisierte Standalone-Controller-Anwendungen die Legacy-Auswahl nutzen. Auf Hardwarekonsolen empfiehlt Purple, das dedizierte Konto im Haupt-Dashboard von UniFi OS zu erstellen. Wenn eine Bereitstellung aktualisiert, migriert oder neu klassifiziert wurde, überprüfen Sie die Position dieses Kontos und die Integrationsklassifizierung, bevor Sie die Firewall-Richtlinien für Gäste ändern. 3

Die Support-Richtlinien von Purple identifizieren die Erreichbarkeit des Controllers ebenfalls als eine separate Grenze. Wenn der externe Dienst Ihren Controller an seiner stabilen öffentlichen Adresse oder FQDN über den freigegebenen Firewall-Pfad nicht erreichen kann, kann die Autorisierung nicht abgeschlossen werden. Überprüfen Sie die für die Integration registrierte Adresse, den zugehörigen eingehenden Pfad und die vom Provider genehmigten Freigaberegeln. Folgen Sie dem Support-Artikel für die aktuellen und für Ihre Version passenden Implementierungsschritte, anstatt Verbindungswerte in einer lokalen Checkliste zu reproduzieren. 3

Was läuft schief und wie lässt sich das Problem beheben?

Das Gästenetzwerk ist isoliert, aber die Anmeldeseite wird nicht gestartet

Behandeln Sie dieses Problem als eine Überprüfung des Hotspot-Status vor einem DNS-Vorfall. Bestätigen Sie, ob für die betroffene WiFi SSID oder das betroffene Netzwerk die Hotspot- und Captive Portal Funktion aktiviert ist. Ubiquiti trennt eine reine WiFi-Hotspot-Konfiguration explizit von einer Konfiguration des gesamten Netzwerks oder VLAN. Stellen Sie die gewünschte Konfiguration wieder her, verbinden Sie ein neues Gerät und bestätigen Sie, dass UniFi nun einen nicht autorisierten Gast registriert, bevor Sie eine externe Verbindung testen. 1 2

Die Weiterleitung schlägt fehl, bevor die externe Seite geladen wird

Behandeln Sie dieses Problem als einen Test des Pre-Authorization-Pfads. Erfassen Sie den DNS-Resolver des Gastgeräts, das Ergebnis der Zielauflösung und das Browser-Ergebnis. Vergleichen Sie anschließend die Gästeregeln mit den aktuellen Anforderungen des Portal-Providers. Die Richtlinien von Purple sind eindeutig: Wenn ein Gast nach dem Absenden des Formulars einen leeren Bildschirm sieht, blockieren die Einstellungen der Pre-Auth ACL oder der Post-Authorization möglicherweise den für den Prozess erforderlichen Datenverkehr. Ersetzen Sie eine gezielte Pre-Authorization-Richtlinie nicht durch einen uneingeschränkten Internetzugang für Gäste. 3

Die externe Seite wird geladen, aber der Gast bleibt offline

Dies ist ein Autorisierungskonflikt. Validieren Sie die Client-Identität im Event des Providers, die Anfrage des Providers an UniFi und den endgültigen Client-Status des Controllers. Der externe Ablauf von Ubiquiti unterscheidet die Weiterleitung von der nachfolgenden Autorisierungsaktion via API. Das Laden einer Seite beweist, dass die erste Phase stattgefunden hat, belegt jedoch nicht, dass der Client anschließend als autorisiert markiert wurde. 2

Ein Update von UniFi Network oder von UDM hat den erwarteten Pfad geändert

Gehen Sie nicht davon aus, dass eine Legacy-Controller-Konfiguration noch mit der aktuellen Integration übereinstimmt. Purple unterscheidet ein modernes UniFi Network Deployment von einem älteren Standalone-Controller und dokumentiert separate Richtlinien für die Accounterstellung für Hardware-Konsolen und selbst gehostete UniFi OS Server. Überprüfen Sie den dedizierten lokalen Account, seine Schreibberechtigung, den Status der 2FA, die Einstellung zur Passwortänderung und die Integrationsklassifizierung erneut. Führen Sie den Test dann mit einem neuen Gerät durch. 3

Können Pi-hole oder vorgelagerte DNS-Filter den UniFi Hotspot blockieren?

Dies kann Teil der Analyse sein, sollte aber nicht ohne Beweise die Schlussfolgerung sein. Die primären genehmigten Quellen belegen nicht, dass Pi-hole die Ursache für einen UniFi Umleitungsfehler ist. Behandeln Sie DNS als messbaren Pfad. Bestätigen Sie den für das Guest-Segment bereitgestellten Resolver, prüfen Sie, ob das Ziel des externen Dienstes aufgelöst wird, testen Sie den genehmigten DNS-Pfad unter Änderungskontrolle und vergleichen Sie die Ergebnisse. Das Apple-Geräte-Probe ist ein weiterer Grund, sowohl das automatische Login-Erlebnis als auch eine normale Browser-Anfrage zu protokollieren. 4

Wie beweist man, dass die Lösung vor der nächsten Spitzenzeit funktioniert?

Nutzen Sie eine wiederholbare Freigabeprüfung. Diese sollte denselben Pfad wie ein echter Gast durchlaufen und nicht nur eine einfache Konnektivitätsprüfung des Controllers sein. Trennen Sie zuerst das Netzwerk oder verwenden Sie ein neues Testgerät. Verbinden Sie sich zweitens mit der betroffenen SSID. Bestätigen Sie drittens, dass der Client nicht autorisiert ist. Starten Sie viertens eine normale Webanfrage. Bestätigen Sie fünftens, dass der externe Dienst die Umleitung empfängt. Schließen Sie sechstens den genehmigten Login-Prozess ab. Bestätigen Sie siebtens den Status authorised: true und testen Sie den normalen Zugriff. 2

Führen Sie die Prüfung vor den Stoßzeiten in einer Einrichtung der Branche Hospitality durch, vor einer Kampagnenphase im Retail, vor einer Veranstaltung im Bereich Transport oder bevor die Besuchernachfrage im Healthcare steigt. Bewahren Sie das Ergebnis als Betriebsprotokoll auf: Erfolg oder Fehler bei jedem Schritt, Gerätetyp, Controller-Klassifizierung und jede angewendete Änderung. Dies ist weitaus nützlicher als eine allgemeine Warnung, dass das "guest WiFi nicht verfügbar" ist.

Praxisbeispiel aus der Realität: Vorfall mit leerem Bildschirm in einem Hotel

Un hotel da 200 camere segnala che gli ospiti si collegano all'SSID del brand ma visualizzano una pagina di accesso vuota. L'ingegnere di turno utilizza un nuovo dispositivo e conferma lo stato authorised: false, il che significa che la fase di Hotspot è presente. La pagina inizia a caricarsi ma la transazione non si completa. L'ingegnere confronta i percorsi di pre-autorizzazione guest con le attuali linee guida di supporto del provider, convalida il resolver effettivamente assegnato al segmento guest e ripete il test. La condizione di completamento misurabile è che il dispositivo completi l'accesso, passi a authorised: true e raggiunga l'accesso previsto. 2 3

Scenario di esempio reale: punti vendita retail dopo la modifica del controller

Un team retail segnala che gli acquirenti si connettono a un SSID isolato ma non vedono mai la pagina di accesso dopo una modifica del controller. L'ingegnere non inizia con il DNS. Conferma che il SSID è isolato, quindi verifica se le opzioni Hotspot e Captive Portal sono abilitate nella configurazione UniFi corrente. Dopo aver ripristinato lo stato Hotspot desiderato, riconnette un nuovo dispositivo e verifica lo stato non autorizzato documentato prima di testare il servizio esterno. Il risultato osservabile è un evento di reindirizzamento seguito da uno stato di autorizzazione completato. 1 2

Scenario di esempio reale: guasto dell'autorizzazione esterna in una sede congressuale

La pagina di accesso di una sede congressuale si carica e accetta il modulo ospite, ma i partecipanti rimangono offline. Il team registra l'indirizzo MAC del client e controlla l'evento del provider esterno per il reindirizzamento. Successivamente convalida che il provider abbia riconosciuto lo stesso client, inviato la richiesta di autorizzazione e che UniFi registri authorised: true. Per un'integrazione Purple, verificano anche l'account API locale, i diritti di scrittura, l'impostazione 2FA e la classificazione corrente del controller. Il risultato atteso è una catena di prove tracciabile, non una supposizione sulla causa. 2 3

Una volta chiuso l'incidente, utilizza lo stesso controllo di rilascio nel tuo processo operativo Guest WiFi. La sezione Guest WiFi fornisce il contesto del servizio, mentre WiFi Analytics può aiutare i team operativi a monitorare l'esperienza post-ripristino. Per i controlli operativi adiacenti, consulta Guest WiFi Management: Smart Authentication & Segmentation, Cloud Wifi Management: Secure Enterprise Connectivity 2026, la guida Cisco Meraki splash page not working: a troubleshooting flowchart e WiFi 7 Venue Deployment: Infrastructure Readiness for Stadiums and Hospitality Sites.

Häufig gestellte Fragen

Benötige ich ein Guest VLAN und einen UniFi Hotspot, um eine Anmeldeseite anzuzeigen?

Nein. Ubiquiti dokumentiert einen Hotspot sowohl auf einer WiFi SSID als auch auf einem gesamten Netzwerk oder VLAN. Die grundlegende Voraussetzung ist, dass die entsprechende SSID oder das Netzwerk die Hotspot- und Captive Portal-Funktion aktiviert hat. Ein isoliertes Guest VLAN ist eine Segmentierungsentscheidung. Es begründet an sich weder den Zustand eines nicht-autorisierten Clients noch initiiert es eine externe Weiterleitung. 1 2

Was sollte in eine UniFi Pre-Authorisation-Liste eingetragen werden?

Nur die Pfade, die erforderlich sind, um den ausgewählten Guest-Anmeldevorgang vor der Freigabe abzuschließen. Purple verbindet leere Bildschirme nach dem Formular mit Guest-Regeln, die den für den Abschluss der Anmeldung erforderlichen Datenverkehr blockieren. Überprüfen Sie die Pre-Authorisation ACL und die Post-Authorisation-Einstellungen anhand der aktuellen Dokumentation Ihres Anbieters. Kopieren Sie keine Domänenliste von einer anderen Website und fügen Sie keinen ungeschützten Internetzugang hinzu, nur um die Seite zu laden. 3

Warum funktioniert das UniFi Guest Portal nach einem Anwendungs-Update nicht mehr?

Überprüfen Sie den Hotspot-Status, die Controller-Klassifizierung und das Integrationskonto, bevor Sie das Netzwerk ändern. Die aktuelle Dokumentation von Ubiquiti unterscheidet die Hotspot-Konfiguration von einem allgemeinen Guest-Netzwerk. Purple unterscheidet zudem aktuelle UniFi Netzwerkintegrationen von Implementierungen mit Legacy-Standalone-Controllern, mit unterschiedlichen Richtlinien für Konten von Hardware-Konsolen und selbst gehosteten UniFi OS Servern. Führen Sie nach jeder Korrektur einen erneuten Test mit einem sauberen Gerät durch. 1 3

Warum lädt ein externes Portal auf meiner UDM Pro, autorisiert aber den Gast nicht?

Eine geladene Seite beweist die Weiterleitungsphase, nicht die finale Autorisierungsphase. Stellen Sie sicher, dass der externe Anbieter die Identität des Clients empfangen, den passenden UniFi Client gefunden und eine Autorisierungsanfrage gesendet hat und dass der Controller authorised: true anzeigt. Stellen Sie bei Purple außerdem sicher, dass das dedizierte lokale Konto über Schreibrechte verfügt, keine 2FA aktiv hat und keine ausstehenden Passwortänderungen erfordert. 2 3

Blockiert Pi-hole die UniFi Hotspot-Weiterleitung?

Gehen Sie nicht davon aus. Die primären, verifizierten Quellen weisen Pi-hole nicht als nachgewiesene Ursache für UniFi aus. Testen Sie den tatsächlichen Resolver des Guest-Segments, die Zielauflösung und den genehmigten DNS-Pfad unter Änderungskontrolle. Protokollieren Sie sowohl die automatische Anfrage des Geräts als auch das Ergebnis eines normalen Browsers, da Apple-Geräte beim Verbinden einen Captive-Netzwerk-Probe verwenden. 4

Muss ich meine UniFi Access Points austauschen, um einen Weiterleitungsfehler zu beheben?

Nein, nicht als erste Maßnahme. Der dokumentierte externe Datenfluss zeigt eine Abfolge von Konfigurations- und Autorisierungsschritten: Hotspot-Status, nicht autorisierter Client-Status, Weiterleitung, externe Verarbeitung und Controller-Freigabe. Identifizieren Sie den fehlerhaften Schritt mit einem neuen Testgerät, bevor Sie einen Hardwareaustausch in Erwägung ziehen. 1 2

Referenzen