Ubiquiti UniFi guest portal not redirecting: causes and fixes
This guide isolates a UniFi guest portal redirect failure by following the guest state, redirect, pre-authorisation route and controller authorisation in sequence. It gives venue IT teams a sourced method to address guest-network versus Hotspot confusion, external portal hand-offs, current UniFi OS account requirements and DNS isolation testing.
Listen to this guide
View podcast transcript
Part of our core series: Captive Portal Guide →
Un Captive Portal UniFi di solito smette di reindirizzare perché l'SSID non è più un Hotspot attivo, l'utente ospite non si trova nello stato non autorizzato, i percorsi di pre-autorizzazione richiesti non riescono a raggiungere il servizio esterno, o il portale non riesce a comunicare l'autorizzazione a UniFi. Verifica questi passaggi esattamente in questo ordine 1 2 3 .
Quali condizioni devono essere soddisfatte affinché avvenga il reindirizzamento ospite UniFi?
Questa è una guida per la risoluzione dei problemi di una configurazione precedentemente funzionante. Non ti verrà chiesto di ricostruire la tua rete WiFi ospiti da zero. Al contrario, la guida procede dal dispositivo ospite verso il controller, per poi tornare indietro attraverso il servizio esterno. Questo ordine previene un errore comune: modificare un SSID, un firewall o un'impostazione DNS prima di sapere quale passaggio ha effettivamente fallito.
Ubiquiti definisce un Hotspot come la funzionalità che può essere applicata a un SSID WiFi o a un'intera rete o VLAN. Il Captive Portal viene poi abilitato all'interno di quella configurazione Hotspot. Di conseguenza, una VLAN ospiti, un SSID ospiti o una policy di isolamento della rete non dimostrano di per sé che il flusso di reindirizzamento sia attivo. Se l'interfaccia utente dell'applicazione UniFi Network è cambiata dopo un aggiornamento, conferma lo stato attuale di Hotspot e Captive Portal seguendo la documentazione ufficiale di Ubiquiti, invece di fare affidamento sulla posizione storica del menu. 1
Per un portale esterno, Ubiquiti descrive un percorso utente preciso. Un dispositivo si connette a un SSID configurato con Hotspot e Captive Portal. Inizia come GUEST con authorised: false. Quando tenta di effettuare una richiesta web, UniFi lo reindirizza al server del portale esterno. Il server riceve i dettagli identificativi del client e dell'access point, ottiene l'ID del client UniFi, quindi richiede l'autorizzazione tramite l'API Network. Un flusso completato correttamente si traduce in authorised: true. 2
| Cosa osservi su un nuovo dispositivo | Limite da esaminare per primo | Prove da raccogliere | Prossima azione sicura |
|---|---|---|---|
| Il dispositivo si connette, ma non entra mai nello stato di ospite non autorizzato | Attivazione dell'Hotspot | SSID o assegnazione di rete e stato del client | Ripristina la configurazione pianificata di Hotspot e Captive Portal, quindi esegui nuovamente il test. 1 2 |
| Il dispositivo non è autorizzato, ma non appare alcuna pagina di accesso esterna | Reindirizzamento e percorso di pre-autorizzazione | Risultato della richiesta del browser, policy ospiti e percorso DNS | Verifica i percorsi di instradamento di pre-autorizzazione richiesti confrontandoli con le linee guida attuali del provider del portale. 3 |
| La pagina appare, ma il processo non si completa | Raggiungibilità del servizio esterno | Esito della richiesta dal segmento ospiti e registro degli eventi lato provider | Isola il percorso degli ospiti verso il servizio esterno prima di modificare le impostazioni del controller. 2 3 |
| Il modulo viene completato, ma l'accesso rimane bloccato | Autorizzazione del controller | Evento di autorizzazione del provider esterno e stato del client UniFi | Verifica se il servizio esterno è in grado di autorizzare esattamente quel client e se UniFi segnala authorised: true. 2 |
La regola diagnostica: non considerare la condizione "connesso al WiFi" come la condizione di successo. La condizione di successo è un client di test non autorizzato che raggiunge il servizio di accesso previsto, completa il relativo processo, mostra
authorised: truee quindi riceve l'accesso previsto. 2
Di cosa hai bisogno prima di iniziare l'isolamento dei guasti?
Utilizza un dispositivo di test fresco e non autorizzato. Un dispositivo già autorizzato è uno strumento diagnostico scadente perché potrebbe saltare il passaggio che devi esaminare. Registra lo SSID o il nome della rete, l'ora del test, il tipo di dispositivo, il sistema operativo e se il dispositivo visualizza una richiesta di accesso automatica o solo un normale risultato del browser. Apple afferma che iOS e macOS inviano un probe al primo accesso a una rete per rilevare l'intercettazione del Captive Portal e visualizzare una pagina di accesso. Ciò significa che la mancanza di una finestra automatica è un indizio utile, ma non è una prova conclusiva che il gateway non possa reindirizzare una normale richiesta del browser. 4
Tieni il test circoscritto. Non iniziare aggiungendo ampie regole di accesso per gli ospiti. Non eliminare un'integrazione funzionante. Non copiare un elenco di consentiti di pre-autorizzazione da un'altra struttura. È necessario stabilire il percorso effettivo dell'ospite e la fase esatta in cui si interrompe. Se il problema riguarda più sedi, esegui lo stesso test con un dispositivo fresco in ciascuna di esse. Una differenza tra i siti è più utile di una teoria su un aggiornamento del controller condiviso.
Per una distribuzione Purple, tieni aperto l'articolo corrente UniFi Integration: Best Practices & Common Questions durante il test. Purple utilizza un login API diretto del controller anziché un canale di autenticazione in background RADIUS. L'account API dedicato deve quindi essere locale rispetto al controller, avere diritti di scrittura come amministratore, avere il 2FA disabilitato e non richiedere la modifica della password. Purple documenta anche diversi requisiti di posizionamento dell'account per le console hardware e per il UniFi OS Server self-hosted. 3
Come si isola il passaggio non riuscito?
Inizia dal livello di accesso. Conferma che lo SSID WiFi interessato, o la relativa configurazione dell'intera rete, sia ancora impostato come Hotspot con Captive Portal abilitato. Ubiquiti documenta l'attuale percorso WiFi-SSID e documenta separatamente un percorso Hotspot Zone per una configurazione dell'intera rete o VLAN. Questa distinzione è la risposta alla comune confusione UniFi guest network vs hotspot. Una rete ospite isolata può essere il segmento corretto e non riuscire comunque ad avviare il flusso di lavoro di accesso se la funzione Hotspot non è attiva. 1 Successivamente, ispeziona il client appena connesso. Devi verificare lo stato non autorizzato documentato, non una semplice associazione wireless. Se lo stato non è presente, torna alla configurazione del Hotspot e al SSID o alla rete selezionata. Non procedere con il DNS, un provider esterno o un'integrazione UDM Pro finché questa fase non è corretta. Un servizio esterno non può autorizzare un ospite che non è mai entrato nel flusso dell'Hotspot esterno. 2
Quindi attiva una normale richiesta web dallo stesso dispositivo. Se la richiesta raggiunge il servizio esterno, conserva il risultato come prova. In caso contrario, concentrati sul percorso di pre-autorizzazione del segmento ospiti. Purple connette gli ospiti solo al completamento del loro processo esterno, e le sue linee guida di supporto associano una schermata vuota dopo l'invio del modulo a regole per gli ospiti che bloccano il traffico web nascosto necessario per completare l'accesso. Verifica l'ACL di Pre-Auth e le impostazioni di post-autorizzazione. Dichiara i percorsi di instradamento di destinazione essenziali tratti dalla documentazione corrente del provider. 3
In questa fase, mantieni preciso il termine allow list. Non si tratta di un elenco di destinazioni web generali per un ospite autorizzato. È l'insieme di percorsi richiesti prima dell'approvazione, come il servizio esterno e gli elementi necessari per completare la transazione di accesso. L'articolo di supporto di Purple è la fonte autorevole per i propri requisiti correnti. Inserisci il link all'articolo di supporto nel tuo ticket di incidente e registra la data della versione, anziché incorporare un elenco copiato e non aggiornato in un runbook. 3
Come si verifica l'autorizzazione del portale esterno e il percorso UDM?
Se la pagina di accesso si carica, la tua indagine passa dall'intercettazione all'autorizzazione. Ubiquiti afferma che il reindirizzamento passa l'indirizzo MAC dell'access point, l'indirizzo MAC del client, l'URL originale richiesto e il SSID al portale esterno. Il servizio esterno può utilizzare l'indirizzo MAC del client per ottenere l'ID del client dall'API di rete, quindi emettere una richiesta di autorizzazione. La conferma lato controller è lo stato authorised: true del client. 2
Esamina le prove in questo ordine. In primo luogo, il provider ha ricevuto un reindirizzamento per il client interessato? In secondo luogo, ha identificato lo stesso client elencato da UniFi? In terzo luogo, ha inviato una richiesta di autorizzazione? In quarto luogo, UniFi ha segnalato il client come autorizzato? Questa sequenza fornisce a un team IT locale e a un MSP un record di incidente condiviso. Inoltre, interrompe il ciclo improduttivo in cui una parte afferma che "il portale si è caricato" mentre l'altra sostiene che "il firewall è a posto".
La questione relativa al UDM Pro guest portal richiede la stessa verifica, con un ulteriore controllo sulla classificazione del controller. Le linee guida di Purple indicano che le implementazioni attuali su console hardware UniFi e su versioni moderne di UniFi OS Server devono utilizzare l'opzione di integrazione UniFi Network corrente, mentre solo le applicazioni controller standalone meno recenti e non aggiornate utilizzano la selezione legacy. Sulle console hardware, Purple suggerisce di creare l'account dedicato nella dashboard principale di UniFi OS. Se un'implementazione è stata aggiornata, migrata o riclassificata, riesamina la posizione di quell'account e la classificazione dell'integrazione prima di modificare i criteri del firewall per gli ospiti. 3
Le linee guida di supporto di Purple identificano inoltre la raggiungibilità del controller come un confine separato. Se il servizio esterno non riesce a raggiungere il tuo controller al suo indirizzo pubblico stabile o FQDN attraverso il percorso approvato del firewall, l'autorizzazione non può essere completata. Verifica l'indirizzo registrato per l'integrazione, il relativo percorso in entrata e le regole di consenso approvate dal provider. Segui l'articolo di supporto per i passaggi di implementazione correnti e appropriati per la versione, anziché riprodurre i valori di connessione in una checklist locale. 3
Got questions about your specific setup?
Our team works with venue operators, IT managers, and network engineers across 80,000 venues. Book a 20-minute call and we will show you how others like you solved it.
Cosa va storto e come risolvere il problema?
La rete ospite è isolata, ma la pagina di accesso non si avvia mai
Gestisci questo problema come una verifica dello stato dell'Hotspot prima di un incidente DNS. Conferma se l'SSID WiFi o la rete interessata ha la funzione Hotspot e Captive Portal abilitata. Ubiquiti separa esplicitamente una configurazione Hotspot solo WiFi da una configurazione dell'intera rete o VLAN. Ripristina la configurazione desiderata, riconnetti un nuovo dispositivo e conferma che UniFi registri ora un ospite non autorizzato prima di testare qualsiasi collegamento esterno. 1 2
Il reindirizzamento fallisce prima che la pagina esterna venga caricata
Gestisci questo problema come un test del percorso di pre-autorizzazione. Acquisisce il resolver DNS del dispositivo ospite, il risultato della risoluzione di destinazione e l'esito del browser. Successivamente, confronta le regole degli ospiti con i requisiti attuali del provider del portale. Le linee guida di Purple sono specifiche: quando un ospite visualizza una schermata vuota dopo l'invio del modulo, le impostazioni della Pre-Auth ACL o di post-autorizzazione potrebbero bloccare il traffico necessario per completare il processo. Non sostituire una policy di pre-autorizzazione mirata con un ampio accesso internet per gli ospiti. 3
La pagina esterna si carica, ma l'ospite rimane offline
Questo è un limite di autorizzazione. Convalida l'identità del client nell'evento del provider, la richiesta del provider a UniFi e lo stato finale del client del controller. Il flusso esterno di Ubiquiti distingue il reindirizzamento dalla successiva azione di autorizzazione tramite API. Il caricamento di una pagina dimostra che la prima fase è avvenuta, ma non prova che il client sia stato successivamente contrassegnato come autorizzato. 2
Un aggiornamento di UniFi Network o di UDM ha modificato il percorso previsto
Non dare per scontato che una configurazione legacy del controller corrisponda ancora all'integrazione corrente. Purple distingue un moderno deployment UniFi Network da un controller standalone precedente e documenta linee guida separate per la creazione di account per console hardware e UniFi OS Server self-hosted. Verificare nuovamente l'account locale dedicato, la sua autorizzazione di scrittura, lo stato della 2FA, l'impostazione di modifica della password e la classificazione dell'integrazione. Quindi eseguire nuovamente il test con un nuovo dispositivo. 3
Pi-hole o il filtraggio DNS a monte possono bloccare l'hotspot UniFi?
Può far parte dell'analisi, ma non dovrebbe essere la conclusione senza prove. Le fonti primarie approvate non stabiliscono che Pi-hole sia la causa di un errore di reindirizzamento UniFi. Tratta il DNS come un percorso misurabile. Conferma il resolver fornito al segmento guest, verifica se la destinazione del servizio esterno si risolve, testa il percorso DNS approvato sotto controllo delle modifiche e confronta i risultati. Il probe del dispositivo Apple è un altro motivo per registrare sia l'esperienza di accesso automatico sia una normale richiesta del browser. 4
Come si dimostra che la soluzione funziona prima del successivo periodo di punta?
Utilizza una verifica di rilascio ripetibile. Dovrebbe seguire lo stesso percorso di un vero ospite, non un semplice controllo di connettività del solo controller. Per prima cosa, dissocia la rete o utilizza un nuovo dispositivo di test. In secondo luogo, connettiti all'SSID interessato. In terzo luogo, conferma che il client non è autorizzato. In quarto luogo, avvia una normale richiesta web. In quinto luogo, conferma che il servizio esterno riceva il reindirizzamento. In sesto luogo, completa il processo di accesso approvato. In settimo luogo, conferma lo stato authorised: true e testa il normale accesso. 2
Esegui la verifica prima degli arrivi di punta in una struttura del settore Hospitality , prima di un periodo di campagna nel Retail , prima di un evento nei Transport o prima che aumenti la domanda dei visitatori nell' Healthcare . Conserva il risultato come registro operativo: esito positivo o negativo a ogni passaggio, tipo di dispositivo, classificazione del controller ed eventuale modifica applicata. Questo è molto più fruibile rispetto a un generico avviso di "guest WiFi non disponibile".
Scenario di esempio reale: incidente della schermata vuota in un 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 .
Domande frequenti
Ho bisogno di una VLAN guest e di un UniFi Hotspot per mostrare una pagina di accesso?
No. Ubiquiti documenta un Hotspot sia su un SSID WiFi che su un'intera rete o VLAN. La condizione fondamentale è che il relativo SSID o rete abbia la funzione Hotspot e Captive Portal abilitata. Una VLAN guest isolata è una scelta di segmentazione. Non stabilisce di per sé lo stato di client non autorizzato né avvia un reindirizzamento esterno. 1 2
Cosa dovrebbe essere inserito in una lista di pre-autorizzazione UniFi?
Solo i percorsi necessari per completare il processo di accesso guest selezionato prima dell'approvazione. Purple collega schermate vuote post-modulo a regole guest che bloccano il traffico necessario per completare l'accesso. Verifica l'ACL di pre-autorizzazione e le impostazioni di post-autorizzazione confrontandole con la documentazione attuale del tuo provider. Non copiare un elenco di domini da un altro sito o aggiungere un accesso a internet non protetto solo per caricare la pagina. 3
Perché il portale guest UniFi ha smesso di funzionare dopo un aggiornamento dell'applicazione?
Verifica lo stato dell'Hotspot, la classificazione del controller e l'account di integrazione prima di modificare la rete. La documentazione attuale di Ubiquiti distingue la configurazione dell'Hotspot da una rete guest generale. Purple distingue inoltre le attuali integrazioni di rete UniFi dalle implementazioni con controller autonomi legacy, con linee guida diverse per gli account per console hardware e UniFi OS Server auto-ospitato. Esegui nuovamente il test con un dispositivo pulito dopo ogni correzione. 1 3
Perché un portale esterno si carica sul mio UDM Pro ma non autorizza l'ospite?
Una pagina caricata dimostra la fase di reindirizzamento, non la fase di autorizzazione finale. Verifica che il provider esterno abbia ricevuto l'identità del client, trovato la corrispondenza con il client UniFi, inviato una richiesta di autorizzazione e che il controller mostri authorised: true. Per Purple, verifica anche che l'account locale dedicato disponga dei permessi di scrittura, non abbia la 2FA e non presenti modifiche obbligatorie della password. 2 3
Pi-hole interrompe il reindirizzamento dell'hotspot UniFi?
Non dare per scontato che sia così. Le fonti primarie approvate non identificano Pi-hole come una causa principale comprovata per UniFi. Testa il resolver effettivo del segmento guest, la risoluzione di destinazione e il percorso DNS approvato sotto il controllo delle modifiche. Registra sia la richiesta automatica del dispositivo che il risultato di un normale browser, poiché i dispositivi Apple utilizzano un probe di rete captive quando si connettono. 4
Devo sostituire i miei access point UniFi per risolvere un errore di reindirizzamento?
No, non come prima misura. Il flusso esterno documentato indica una sequenza di passaggi di configurazione e autorizzazione: stato dell'Hotspot, stato del client non autorizzato, reindirizzamento, elaborazione esterna e approvazione del controller. Individua il passaggio non riuscito con un nuovo dispositivo di test prima di considerare una sostituzione hardware. 1 2
Riferimenti
Key Definitions
Captive Portal
The Hotspot sign-in function that controls a guest's access before approval. In UniFi, it is enabled within a Hotspot configuration. [1]
Check it when the guest SSID is present but a fresh device never begins the sign-in flow.
Guest network
A network or VLAN used to separate guest traffic from other network traffic. It is not, by itself, proof that a Captive Portal is active.
Use the distinction to avoid confusing isolation with the external sign-in workflow.
Hotspot
The UniFi feature that can apply to a WiFi SSID or an entire network or VLAN and forms the basis for Captive Portal control. [1]
Verify it first when no fresh guest receives a redirect.
Unauthorised client state
The initial state in Ubiquiti's documented external Hotspot flow, where the guest is marked authorised false. [2]
This is the first controller-side confirmation that the external redirect path should be under test.
Pre-Auth ACL
The UniFi access-control area used to declare routes required before a guest completes the sign-in process. [3]
Review it when a form submission or sign-in hand-off leads to a blank or incomplete page.
External portal server
A third-party service that receives the UniFi redirect and can authorise the guest through the Network API. [2]
It is the boundary to inspect when a guest reaches the sign-in service but does not obtain access.
Controller API account
A dedicated account used by an integration to authenticate to the UniFi controller and change guest access state. Purple requires a local account with write rights and no interactive authentication challenge. [3]
Review it when the external service reaches the controller but cannot approve the guest.
Authorised true
The client state returned after the documented external authorisation process completes. [2]
Use it as a measurable completion point before declaring the incident fixed.
DNS path
The resolver and name-resolution route supplied to the guest segment before access is approved.
Test it as a controlled dependency when the external service destination does not resolve or load from the affected guest segment.
Worked Examples
Representative hotel incident: guests join the branded SSID, but the sign-in screen is blank.
Use a fresh device to confirm the unauthorised guest state. If the state is present but the sign-in process will not complete, compare the actual guest pre-authorisation path with the external provider's current requirements, validate the assigned DNS path, then retest. The acceptance condition is a completed sign-in, authorised true in UniFi and expected access. [2] [3]
Representative retail incident: shoppers connect after a controller change, but no sign-in page appears.
Confirm that the SSID remains a Hotspot with Captive Portal enabled in the current UniFi configuration. Verify the fresh device enters the unauthorised state before diagnosing DNS or the provider. The acceptance condition is a redirect event followed by completed controller authorisation. [1] [2]
Representative conference-venue incident: the external form submits, but attendees remain offline.
Trace the authorisation transaction. Confirm the external provider received the client identity, matched that client, sent the authorisation request and that UniFi shows authorised true. For Purple, review the local API account, write permission, 2FA, password-change setting, controller reachability and classification. [2] [3]
Continue reading in this series
Cisco Meraki splash page not working: a troubleshooting flowchart
This practical day-two guide isolates where a Cisco Meraki splash flow has failed: client authorisation, HTTP redirect initiation, walled-garden reachability or RADIUS sign-on. It gives venue IT teams a controlled evidence path, so they can restore Guest WiFi without making broad changes to a live estate.
Enterprise Guest WiFi Setup Guide: VLAN Segmentation, Security, and Captive Portals
This technical guide shows IT teams how to set up Guest WiFi as a controlled internet-access service, using VLAN segmentation, firewall policy and a captive portal. It also explains how Purple's registration forms and onboarding controls support a proportionate visitor experience without weakening the boundary around staff, payment and operational systems.
Captive portal for Ruijie: set it up with Purple guest WiFi
How Purple's cloud guest WiFi sits on top of Ruijie RG Series access points using web authentication and RADIUS, configured from the command line, and where to find the exact setup steps.
Got questions about your specific setup?
Our team works with venue operators, IT managers, and network engineers across 80,000 venues. Book a 20-minute call and we will show you how others like you solved it.