Risoluzione dei problemi del captive portal Ubiquiti UniFi: checklist per portale esterno, hotspot e walled garden

Un Captive Portal UniFi non funziona per uno di cinque motivi. L'indirizzo del server del portale esterno è errato, oppure i domini del portale e di login mancano dall'accesso di pre-autorizzazione. L'isolamento degli ospiti potrebbe bloccare l'host del portale. Il reindirizzamento potrebbe utilizzare HTTP verso un indirizzo IP. Oppure la console non è raggiungibile. Verifica ciascun punto in sequenza, quindi esegui un test da un client.

Come si presenta un Captive Portal UniFi che non funziona?

La maggior parte dei guasti si manifesta con uno di quattro sintomi. Identificare prima il sintomo restringe la causa prima ancora di aprire l'applicazione UniFi Network.

• Nessun portale. Il dispositivo si connette al SSID ospiti e riceve un indirizzo IP, ma non viene visualizzata alcuna richiesta di login. Il telefono potrebbe segnalare "nessuna connessione internet" o risultare connesso senza traffico dati.
• Una pagina vuota o che si carica all'infinito. Il Captive Network Assistant (CNA) si apre, ma la splash page non viene mai visualizzata. Il CNA è il piccolo browser avviato dal sistema operativo su una rete captive.
• Un avviso di certificato. I laptop mostrano "La tua connessione non è privata" prima della pagina di login. Gli ospiti devono superare l'avviso per continuare.
• Un portale parziale. La splash page si carica, ma un pulsante di social login o di pagamento gira a vuoto, fallisce o torna indietro in loop.

L'articolo di supporto sui Captive Portal di Purple spiega il CNA più nel dettaglio. Il CNA verifica un dominio predefinito per verificare se internet è raggiungibile. Successivamente notifica il dispositivo, avvia un browser e conferma lo stato "online". Quando una qualsiasi parte di questa catena si interrompe, i tuoi ospiti riscontrano uno dei sintomi descritti sopra.

Questa guida presuppone che il tuo portale hotspot UniFi o portale esterno sia già configurato. Si tratta di una checklist per la risoluzione dei problemi, non di una guida all'installazione.

Quali sono le cause più comuni di malfunzionamento di un Captive Portal UniFi?

Sei cause principali spiegano la maggior parte dei casi di risoluzione dei problemi del portale ospiti UniFi.

1. Impostazione errata del server del portale esterno. L'indirizzo punta a un vecchio host, presenta un errore di battitura o fa riferimento a un server che il gateway non riesce a raggiungere.
2. Accesso di pre-autorizzazione incompleto. UniFi definisce questa impostazione "Pre-Authorization Access". È il walled garden di UniFi: gli host e le subnet che un ospite può raggiungere prima di effettuare il login. Se il portale, le sue risorse o un provider di social login non sono presenti, la pagina rimane vuota o parziale.
3. Restrizioni della rete ospiti. Le reti ospiti UniFi bloccano gli intervalli di indirizzi privati. Di conseguenza, un server del portale o un server DNS su una subnet interna diventa irraggiungibile.
4. Incongruenze tra reindirizzamento HTTPS e hostname. Un reindirizzamento HTTPS verso un indirizzo IP, o verso un hostname privo di un certificato corrispondente, attiva gli avvisi del browser.
5. Raggiungibilità del controller o della console. I server UniFi Network autogestiti e le console cloud devono rimanere raggiungibili. Con un portale esterno, il controller deve anche raggiungere il server RADIUS che completa il login.
6. Interferenze sul lato client. VPN, impostazioni DNS personalizzate o una notifica CNA ignorata bloccano il reindirizzamento su quel dispositivo.

Come capire quale problema interessa il tuo Captive Portal UniFi?

Inizia con il sintomo, poi esegui il primo controllo nella tabella prima di modificare qualsiasi impostazione.

Sintomo	Causa più probabile	Primo controllo	Risoluzione
Nessun portale, nessuna richiesta	DNS non raggiungibile o probe CNA bloccato	Il client riesce a risolvere un hostname pubblico prima del login?	Fornisci un server DNS al di fuori degli intervalli privati bloccati, o consentilo nell'accesso pre-autorizzazione
Pagina vuota o a caricamento infinito	Host del portale o risorse mancanti dall'accesso pre-autorizzazione	L'hostname del portale si risolve e si carica da un dispositivo ospite?	Aggiungi l'host del portale, i domini delle sue risorse e la sua sottorete all'accesso pre-autorizzazione
Avviso di certificato sui laptop	Reindirizzamento HTTPS a un indirizzo IP o hostname non corrispondente	Quale URL appare nella barra degli indirizzi in corrispondenza dell'avviso?	Disabilita il reindirizzamento HTTPS, o reindirizza tramite hostname con un certificato pubblicamente attendibile corrispondente a quell'hostname
Il pulsante di login social gira o fallisce	Domini dell'identity provider mancanti	Quale dominio fallisce nella visualizzazione di rete del browser?	Aggiungi ogni dominio caricato dalla pagina di login del provider
Fase di pagamento fallita	Domini del gateway di pagamento mancanti	La pagina di pagamento si carica?	Aggiungi gli host del provider di pagamento all'accesso pre-autorizzazione
Il portale si carica, il login non si completa mai	RADIUS o controller non raggiungibili	I tentativi di autenticazione appaiono negli eventi del controller?	Ripristina la raggiungibilità del controller e conferma che i dettagli RADIUS corrispondano al tuo provider del portale
Un dispositivo fallisce, altri funzionano	VPN lato client, DNS personalizzato o CNA ignorato	Il sito neverssl.com reindirizza su quel dispositivo?	Disabilita la VPN o il DNS personalizzato, dimentica la rete e riconnettiti

Due rapidi test isolano la maggior parte dei guasti. Per prima cosa, naviga su neverssl.com su un dispositivo connesso ma non autenticato. Il team di supporto di Purple consiglia questo sito perché evita problemi con i reindirizzamenti SSL. Se neverssl.com reindirizza al tuo portale, il reindirizzamento funziona e il problema risiede nell'accesso pre-autorizzazione o nel portale stesso. Se non reindirizza, controlla il DNS, l'impostazione del server del portale esterno o il controller.

In secondo luogo, controlla la voce del client nell'applicazione UniFi Network. L'elenco dei client e gli eventi mostrano se il dispositivo si trova sulla rete ospite e se si è autorizzato. Un dispositivo contrassegnato come autorizzato che mostra ancora il portale indica un problema di cache lato client o di CNA.

Come risolvere ogni causa del Captive Portal UniFi?

Purple non riproduce qui i percorsi dei menu UniFi, poiché cambiano tra le diverse versioni di UniFi Network. Utilizza la documentazione corrente di Ubiquiti per la posizione esatta di ciascuna impostazione.

Server del portale esterno

Conferma che il valore del server del portale esterno corrisponda a quello specificato dal tuo provider del portale. Un singolo carattere errato invia ogni ospite a un host inattivo. Se hai cambiato provider del portale, rimuovi il vecchio indirizzo anziché lasciarlo accanto a quello nuovo. Quando utilizzi Purple, i server della pagina di cortesia raccolgono i dettagli dei visitatori ed emettono un login unico. Il controller passa tale login al server RADIUS di Purple per completare l'autenticazione. RADIUS è il protocollo utilizzato dagli apparati di rete per verificare le credenziali rispetto a un server centrale. Se il portale si carica ma il login non va a buon fine, verifica come passo successivo il profilo RADIUS.

Accesso di pre-autorizzazione per il portale, social login e domini di pagamento

Questa è la risoluzione più comune. Aggiungi queste voci all'accesso di pre-autorizzazione:

• L'host del server del portale e qualsiasi subnet su cui risiede.
• Ogni dominio caricato dalla pagina di cortesia, inclusi font, immagini e script provenienti da reti di distribuzione dei contenuti (CDN).
• I domini di autenticazione di ciascun provider di social login, se offri l'accesso con Facebook, Google o Apple.
• Gli host del tuo gateway di pagamento, se prevedi un costo per l'accesso premium.

Apri la pagina di cortesia da un laptop su una rete non limitata, con gli strumenti per sviluppatori del browser che mostrano le richieste di rete. Ogni dominio elencato deve essere raggiungibile prima del login. Qualora la tua versione di UniFi Network accetti solo indirizzi IP, verificali nuovamente ogni volta che un provider cambia i propri indirizzi.

Isolamento della rete guest e subnet bloccate

L'isolamento degli ospiti non blocca il Captive Portal da solo. L'isolamento dei dispositivi client impedisce ai dispositivi guest di comunicare tra loro. Le restrizioni di subnet della rete guest bloccano gli intervalli di indirizzi privati, e tali restrizioni colpiscono i server DNS o i portali interni.

Se il server del tuo portale o il risolutore DNS si trova su una subnet interna, aggiungi quello specifico host all'accesso di pre-autorizzazione. Un approccio più pulito consiste nell'assegnare ai guest un risolutore DNS pubblico e ospitare il portale su un indirizzo pubblico.

Opzioni di reindirizzamento HTTPS e hostname

I browser moderni richiedono l'HTTPS per le pagine di login. L'articolo sul certificato Cisco WLC di Purple descrive lo stesso scenario sull'hardware Cisco. Un reindirizzamento a un indirizzo HTTP come un semplice IP genera un avviso di sicurezza, che i guest devono ignorare cliccando per procedere.

La risoluzione segue lo stesso principio su UniFi. Disattiva il reindirizzamento HTTPS lasciando che il CNA utilizzi HTTP, oppure reindirizza tramite hostname. Un reindirizzamento tramite hostname richiede un certificato SSL/TLS attendibile pubblicamente, e l'hostname deve corrispondere al Common Name del certificato. Un certificato autofirmato o un nome non corrispondente farà riapparire immediatamente l'avviso.

Raggiungibilità del controller per console self-hosted e in cloud

Per un UniFi Network Server self-hosted, verifica che il server sia attivo e raggiungibile dal tuo gateway e dagli access point. Controlla le regole del firewall tra le sedi se il server si trova in una sede centrale o in un data center. Per le console in cloud, verifica che la console risulti online e che il gateway sia adottato. Successivamente, conferma che il traffico in uscita verso il tuo server RADIUS sia consentito.

Verifiche del client

Chiedere all'ospite di dimenticare la rete e riconnettersi. Disabilitare qualsiasi VPN o impostazione DNS personalizzata, che può bypassare completamente il reindirizzamento. Se la notifica CNA è andata persa, aprire un browser e andare su neverssl.com. Su Android, toccando la notifica "potrebbe essere necessario accedere" si avvia la sessione del browser CNA.

Esempi pratici nei settori ospitalità, retail ed eventi

Questi esempi pratici mostrano come si applica la checklist a livello di sede.

Un hotel da 200 camere con una pagina di cortesia vuota

Situazione. Un hotel gestiva un UniFi Network Server in self-hosting e un portale esterno. Dopo una modifica della rete, gli ospiti sull'SSID ospite visualizzavano una pagina vuota. Il personale della reception registrava circa una dozzina di reclami a notte.

Cosa è stato fatto. Il sito neverssl.com non reindirizzava, quindi il team ha controllato prima il DNS. Lo scope DHCP della VLAN ospite distribuiva un server DNS interno su una subnet privata. Le restrizioni per gli ospiti bloccavano quella subnet. Il team ha impostato lo scope dell'ospite su un risolutore pubblico.

Risultato. I reindirizzamenti del portale hanno ripreso a funzionare alla connessione successiva. La reception non ha registrato ulteriori reclami relativi al WiFi per il resto della settimana.

Una catena retail di 40 negozi con un login social bloccato

Situazione. Una catena retail ha aggiunto il social sign-in alla sua pagina di cortesia. Il modulo per l'email funzionava, ma il pulsante social caricava all'infinito in ogni negozio.

Cosa è stato fatto. Il team ha aperto la pagina di cortesia con gli strumenti per sviluppatori e ha mappato ogni dominio caricato dal login del provider. Li ha aggiunti all'accesso di pre-autorizzazione in un negozio pilota, ha effettuato i test su Android e iOS, quindi ha esteso la modifica a tutti i 40 negozi.

Risultato. Il social sign-in è stato completato con successo in tutti i 40 negozi. Ora il team esegue un test nel negozio pilota dopo ogni aggiornamento del provider.

Un centro congressi con avvisi di certificato

Situazione. I delegati sui laptop visualizzavano l'errore "La tua connessione non è privata" prima del portale. I telefoni funzionavano tramite il CNA, quindi il guasto sembrava intermittente.

Cosa è stato fatto. La barra degli indirizzi mostrava un reindirizzamento HTTPS a un indirizzo IP. Il team ha disattivato il reindirizzamento HTTPS fino a quando non è stato installato un certificato pubblicamente attendibile corrispondente all'hostname di reindirizzamento.

Risultato. L'avviso è scomparso sui laptop. L'helpdesk dell'evento ha smesso di ricevere ticket sul portale per il resto della conferenza.

Come evitare che il Captive Portal UniFi fallisca di nuovo?

• Tenere un registro di pre-autorizzazione. Elencare ogni host e subnet, il motivo della loro presenza e chi ne è il proprietario. Esaminarlo quando si aggiunge un metodo di login o un provider di pagamento.
• Testare dopo ogni modifica. Utilizzare un telefono Android, un iPhone e un laptop. Verificare che neverssl.com reindirizzi correttamente e che il login venga completato.
• Monitorare la scadenza dei certificati. Un certificato scaduto su un reindirizzamento dell'hostname produce lo stesso avviso di un certificato assente.
• Monitorare il controller. Configurare un avviso per ricevere notifiche se un server in self-hosting va offline prima che se ne accorgano gli ospiti.
• Gestire una rete ospiti aperta. Purple consiglia reti ospiti aperte poiché la familiarità riduce l'attrito al momento del login.

La stessa disciplina si applica ad altri fornitori. La guida alla risoluzione dei problemi del captive portal HPE Aruba di Purple e la guida alla risoluzione dei problemi del captive portal Cisco Meraki di Purple seguono la stessa checklist per quelle piattaforme.

Domande frequenti

Purple funziona con gli access point Ubiquiti UniFi che già possediamo?

Sì, Purple funziona su Ubiquiti UniFi come portale esterno e servizio RADIUS, consentendoti di mantenere i tuoi access point esistenti. Purple è indipendente dall'hardware e supporta anche Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Cambium, Extreme e Fortinet. Questo è fondamentale per le proprietà multi-sito con hardware misto, perché un'unica configurazione di WiFi per ospiti copre ogni fornitore. La piattaforma di Purple è attiva in oltre 80.000 sedi reali, secondo i dati di Purple.

Possiamo mantenere un UniFi Network Server in self-hosting con un portale esterno?

Sì, un UniFi Network Server in self-hosting funziona con un portale esterno, a condizione che rimanga raggiungibile. Il gateway e gli access point devono raggiungere il server, e il server deve raggiungere il servizio RADIUS del fornitore del portale. Verifica le regole del firewall tra i siti se il server si trova in una sede centrale. Le console cloud eliminano l'attività di hosting ma richiedono comunque l'accesso in uscita a RADIUS.

La nostra rete per ospiti UniFi dovrebbe essere aperta o protetta da password?

La rete aperta è la scelta consigliata per l'accesso degli ospiti. Purple consiglia di fornire il WiFi per ospiti su una rete aperta perché rappresenta ormai lo standard e riduce gli ostacoli al login. Il captive portal controlla comunque l'accesso, raccoglie i consensi espliciti e rilascia a ciascun ospite un login monouso. Le reti per ospiti protette da password aggiungono un passaggio e generano un maggior numero di richieste alla reception.

Dobbiamo acquistare un certificato SSL per il nostro captive portal?

Sì, se reindirizzi gli ospiti tramite HTTPS o tramite hostname. I browser si aspettano un certificato pubblicamente attendibile e l'hostname di reindirizzamento deve corrispondere al Common Name del certificato. Senza di esso, i laptop mostrano un avviso di sicurezza prima del caricamento del portale. Se non puoi gestire un certificato, disattiva il reindirizzamento HTTPS e lascia che il CNA del dispositivo utilizzi invece un reindirizzamento HTTP.

In che modo il passaggio a Purple influisce sulla nostra posizione rispetto al GDPR?

Purple ti aiuta a soddisfare i requisiti GDPR anziché aggiungere rischi. Purple possiede le certificazioni ISO 27001, GDPR, CCPA e Cyber Essentials, e la splash page registra i consensi espliciti per il marketing. I dati di prima parte che raccogli rimangono legati al consenso fornito da ciascun ospite. Informativa sulla privacy e policy di conservazione rimangono di tua competenza, quindi ti invitiamo a verificarle entrambe prima del lancio.

Quanto sforzo richiede il passaggio dall'hotspot UniFi integrato a Purple?

Passare a Purple è una modifica di configurazione, non un progetto hardware. È sufficiente indirizzare il server del portale esterno e le impostazioni RADIUS verso Purple, quindi aggiornare l'accesso di pre-autorizzazione per i domini della splash page. Purple si integra sopra la tua infrastruttura UniFi esistente, evitando così costose sostituzioni hardware. Testa prima un sito, poi copia le impostazioni su tutto il tuo parco macchine.

Purple è in grado di gestire l'accesso degli ospiti in ambienti ad alto volume?

Sì, Purple ha gestito 440 milioni di accessi nel 2024, secondo i dati interni di Purple. Questo volume copre hotel, retail, treni e strutture healthcare con picchi di traffico intensi. Su UniFi, la capacità del portale raramente rappresenta un collo di bottiglia. La raggiungibilità del DNS e un accesso di pre-autorizzazione completo sono gli elementi più importanti: applica questa checklist prima di un grande evento.