Vai al contenuto principale
Italiano

Captive Portal per Ubiquiti UniFi

Questa guida tecnica autorevole illustra in dettaglio la configurazione di un captive portal esterno (Purple) sull'applicazione Ubiquiti UniFi Network. Copre i meccanismi di rete sottostanti, l'implementazione passo dopo passo della rete ospiti, la whitelist del walled garden, l'autenticazione RADIUS e le strategie di risoluzione dei problemi per professionisti IT senior e amministratori di rete.

📖 10 minuti di lettura📝 2,475 parole🔧 2 esempi pratici❓ 3 domande di esercitazione📚 8 definizioni chiave

Ascolta questa guida

Visualizza trascrizione del podcast
Captive Portal for Ubiquiti UniFi — A Purple Technical Briefing [INTRODUZIONE E CONTESTO — circa 1 minuto] Benvenuti alla serie Purple Technical Briefing. Sono il vostro ospite e oggi approfondiremo le specifiche della distribuzione di un Captive Portal esterno su infrastruttura Ubiquiti UniFi, una delle piattaforme di rete più diffuse a livello globale nei settori hospitality, retail e aziendale. Se siete IT manager, network architect o systems integrator e lavorate con UniFi Cloud Gateways, Dream Machines o con l'applicazione UniFi Network, questo episodio fa al caso vostro. Analizzeremo esattamente come funziona il meccanismo del portale esterno sotto il cofano, come configurarlo correttamente, quali sono i problemi più comuni e perché l'integrazione di Purple su una distribuzione UniFi rappresenta la scelta architetturale ideale per le strutture che richiedono molto di più di una semplice splash page di base. Iniziamo. [APPROFONDIMENTO TECNICO — circa 5 minuti] In primo luogo, cerchiamo di capire cosa accade effettivamente quando un dispositivo ospite si connette a un SSID UniFi con Captive Portal abilitato. Quando un dispositivo ospite si associa al vostro SSID ospite, l'Access Point UniFi gli assegna un indirizzo IP tramite DHCP, come di consueto. Tuttavia, il dispositivo viene immediatamente inserito in quello che UniFi definisce uno stato "in attesa". In questo stato, il processo DNSmasq integrato nell'AP intercetta ogni richiesta DNS effettuata dal dispositivo, indipendentemente dal server DNS che il dispositivo crede di utilizzare. L'AP reindirizza tutto il traffico DNS a se stesso. Contemporaneamente, l'AP esegue un redirector HTTP leggero sulla porta 80. Nel momento in cui il browser dell'ospite effettua una qualsiasi richiesta HTTP (e questa è la parola chiave: HTTP, non HTTPS), il redirector risponde con un reindirizzamento 302, inviando il browser alla splash page del Captive Portal. Questo è il meccanismo che attiva la notifica "Accedi al WiFi" sui dispositivi iOS e Android. Ora, è qui che la distinzione tra portale integrato e portale esterno diventa fondamentale. Con l'Hotspot Portal integrato di UniFi, la splash page viene servita direttamente dall'applicazione UniFi Network. È funzionale, è veloce da configurare, ma è estremamente limitata. Offre solo l'autenticazione tramite password di base, voucher e pagamenti Stripe. Non è prevista l'acquisizione di indirizzi e-mail, né l'accesso tramite social, né la gestione del consenso GDPR, né l'integrazione con CRM, né alcuna analisi significativa oltre al conteggio delle sessioni. Quando si configura un Server Portale Esterno (la configurazione su cui ci concentriamo oggi), si indica al controller UniFi di reindirizzare gli ospiti a un'applicazione web completamente separata. Nel nostro caso, si tratta di Purple. L'URL inserito nel campo Server Portale Esterno diventa la destinazione di tutti i reindirizzamenti 302. Ecco l'importante dettaglio tecnico relativo a quell'URL di reindirizzamento. Quando UniFi reindirizza un ospite al tuo portale esterno, aggiunge diversi parametri di query all'URL. Questi includono: l'indirizzo MAC dell'AP, l'indirizzo MAC del dispositivo client, un timestamp Unix, l'URL originale che il client stava cercando di raggiungere e il nome dell'SSID. Il tuo portale esterno — Purple in questo contesto — acquisisce tali parametri, li utilizza per identificare il dispositivo che si connette, presenta la Captive Portal appropriata, gestisce l'autenticazione e quindi effettua una chiamata API di ritorno all'applicazione di rete UniFi per autorizzare quell'indirizzo MAC. Quella chiamata API è la stretta di mano fondamentale. A partire dalla UniFi Network Application 9.1 e successive, è presente un'API REST ufficiale con una corretta autenticazione basata su chiavi. L'endpoint di autorizzazione è una richiesta POST alla versione uno dell'API dei siti, che si rivolge allo specifico ID client, con un corpo JSON in grado di specificare limiti di tempo in minuti, limiti di utilizzo dei dati in megabyte e limiti di velocità in kilobit al secondo. Una volta che il controller riceve tale autorizzazione, invia l'istruzione all'AP e l'ospite passa da in attesa ad autorizzato. L'accesso a Internet viene concesso. Parliamo ora del Walled Garden, che UniFi chiama Pre-Authorization Access. Si tratta della whitelist di domini e indirizzi IP che gli ospiti possono raggiungere prima di essersi autenticati. È essenziale ed è una delle fonti più comuni di configurazione errata. Come minimo, il tuo walled garden deve includere il nome di dominio completo del tuo portale Purple e gli indirizzi IP o gli intervalli CIDR a cui si risolve l'infrastruttura di Purple. Se utilizzi il social login — Facebook, Google, Microsoft — devi aggiungere anche i domini degli endpoint OAuth per tali provider. Gli endpoint di accesso di Google coprono più intervalli IP e diversi domini, tra cui accounts.google.com e oauth2.googleapis.com. Anche l'infrastruttura di accesso di Facebook richiede diversi inserimenti. La documentazione di Purple fornisce un elenco aggiornato delle voci esatte richieste, e questo elenco viene mantenuto aggiornato man mano che i provider aggiornano la loro infrastruttura. C'è una particolarità critica specifica di UniFi che mette in difficoltà molte installazioni. Il reindirizzatore HTTP sull'AP intercetta solo il traffico HTTP in chiaro sulla porta 80. I dispositivi moderni — iOS, Android, Windows, macOS — eseguono tutti il rilevamento del captive portal basato su HTTPS. I dispositivi Apple raggiungono captive.apple.com tramite HTTPS. I dispositivi Android raggiungono connectivitycheck.gstatic.com. Se tali richieste HTTPS non ricevono una risposta specifica, il dispositivo potrebbe decidere che non esiste alcun captive portal e semplicemente non mostrare la richiesta di accesso. La soluzione consiste nel garantire che il walled garden includa i domini di rilevamento del captive portal per i principali sistemi operativi e che il portale Purple sia accessibile tramite HTTPS con un certificato SSL valido e attendibile. I certificati autofirmati causeranno avvisi di sicurezza del browser che impediranno il caricamento del portale. Questo è non negoziabile per le installazioni di produzione. L'altra considerazione specifica per UniFi riguarda l'accessibilità del controller. L'UniFi Network Application — sia che sia in esecuzione su un Cloud Gateway, un Cloud Key o un server self-hosted — deve essere raggiungibile dall'infrastruttura di Purple affinché le chiamate API di autorizzazione vadano a buon fine. Se il controller si trova su una rete privata dietro NAT, dovrai assicurarti che le relative porte API siano accessibili. Per i controller self-hosted, si tratta in genere della porta 8443 per l'API legacy, o della porta HTTPS standard 443 per la versione più recente dell'API introdotta nella versione 9.1. La documentazione di supporto di Purple specifica gli intervalli IP esatti che richiedono l'accesso in entrata al controller. Per l'autenticazione basata su RADIUS — rilevante quando si distribuisce Purple insieme a SSID WPA2-Enterprise o WPA3-Enterprise piuttosto che con il modello di Captive Portal aperto per gli ospiti — il server RADIUS integrato di UniFi supporta i metodi standard EAP 802.1X. Configura il profilo RADIUS in Settings, Networks, RADIUS Servers, e poi fai riferimento a quel profilo nella configurazione del tuo SSID. UniFi supporta anche RADIUS su TLS, noto come RADSEC, a partire dalla versione 8.4, che crittografa il traffico RADIUS tra l'AP e il server di autenticazione. Per le installazioni multi-sito in cui il traffico RADIUS attraversa la rete internet pubblica, RADSEC è fortemente raccomandato. [RACCOMANDAZIONI DI IMPLEMENTAZIONE E TRAPPOLE DA EVITARE — circa 2 minuti] Ecco la checklist pratica di implementazione che seguirei con qualsiasi cliente che distribuisce Purple su UniFi. In primo luogo, la segmentazione della rete. Il tuo SSID ospite deve essere su una VLAN dedicata, isolata dalle reti aziendali e IoT. UniFi rende questo processo semplicissimo: crea una rete dedicata in Settings, Networks, assegna un ID VLAN e associa il tuo SSID ospite a quella rete. Abilita l'isolamento dei client sulla rete ospite per impedire il traffico tra gli utenti ospiti. In secondo luogo, il controller deve avere un FQDN valido e un certificato SSL attendibile. Non affidarti all'indirizzo IP. Usa un nome di dominio corretto, ottieni un certificato Let's Encrypt o commerciale e configura UniFi per utilizzare quel certificato. Questo risolve la maggior parte dei problemi di reindirizzamento HTTPS. In terzo luogo, crea con cura il tuo walled garden e testalo. Le voci minime sono: il dominio del tuo Captive Portal Purple e i suoi intervalli IP, i domini di rilevamento del Captive Portal per iOS, Android e Windows, e tutti i domini dei provider OAuth che stai utilizzando. Esegui i test con un dispositivo che non si è mai connesso alla rete prima d'ora: la cache DNS e lo stato della rete possono mascherare le lacune del walled garden durante i test. In quarto luogo, per l'integrazione API, utilizza un account amministratore locale dedicato nell'applicazione UniFi Network con i permessi minimi richiesti. Non utilizzare le tue credenziali di amministratore principali. Se utilizzi Network Application 9.1 o versioni successive, usa il nuovo meccanismo di chiavi API in Control Plane, Integrations: è più sicuro e non richiede l'autenticazione basata su credenziali. In quinto luogo, considera attentamente la durata della sessione. La scadenza predefinita della sessione ospite di UniFi può essere di appena otto ore. Per le installazioni nel settore dell'ospitalità in cui gli ospiti potrebbero soggiornare per più notti, configura durate di sessione adeguate nelle impostazioni del portale Purple e assicurati che tali durate siano trasmesse correttamente nella chiamata di autorizzazione API. L'errore più comune che riscontro è l'installazione su un controller self-hosted che non è accessibile pubblicamente. Se Purple non riesce a raggiungere il tuo controller per autorizzare gli ospiti, il portale si caricherà ma l'autenticazione fallirà in modo silenzioso. Verifica sempre la connettività API dall'infrastruttura di Purple prima del lancio. [Q&A RAPIDO — circa 1 minuto] Funziona su UniFi Dream Machine Pro? Sì. Tutte le console UniFi OS — UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max — supportano la configurazione External Portal Server. L'applicazione di rete viene eseguita sul dispositivo. Posso utilizzare Purple su più siti UniFi da un unico account Purple? Sì. L'architettura multi-sito di Purple è progettata esattamente per questo. Ogni sede è configurata come un sito separato in Purple, mappato al sito UniFi corrispondente. Devo aprire le porte del firewall sul gateway UniFi? Devi assicurarti che il traffico VLAN degli ospiti possa raggiungere il dominio del portale Purple sulla porta 443. Anche la porta API del controller deve essere raggiungibile dai server di Purple. La documentazione di Purple fornisce gli intervalli IP specifici. E per quanto riguarda il WPA3? UniFi supporta WPA3 Personal e WPA3 Enterprise. Il meccanismo del Captive Portal funziona con WPA3 Personal sulle reti ospiti. WPA3 Enterprise utilizza 802.1X e RADIUS, che è un flusso di autenticazione diverso. [RIASSUNTO E PROSSIMI PASSI — circa 1 minuto] Per riassumere: implementare Purple come Captive Portal esterno su UniFi è un'integrazione ben supportata e solida dal punto di vista architetturale. I passaggi chiave sono: configurare il tuo SSID ospite con l'opzione External Portal Server che punta all'URL del tuo portale Purple, creare un walled garden completo che copra l'infrastruttura di Purple e tutti i provider OAuth che stai utilizzando, assicurarti che il tuo controller UniFi abbia un certificato SSL valido e sia accessibile dai server API di Purple, e configurare durate di sessione adeguate per il tipo di sede. Il caso aziendale è semplice. Il portale UniFi integrato offre una splash page. Purple offre una piattaforma per l'esperienza degli ospiti pronta per la conformità e basata sugli analytics, che si integra con il tuo CRM, acquisisce dati di prima parte con il consenso GDPR e fornisce le analisi delle visite e dei tempi di sosta di cui i gestori delle sedi e i team di marketing hanno effettivamente bisogno. Se sei un MSP o un integratore di sistemi che implementa UniFi su larga scala, la gestione multi-sito e le funzionalità white-label di Purple la rendono la soluzione di overlay ideale per i tuoi clienti. Per la documentazione dettagliata sulla configurazione, gli elenchi IP del walled garden e le guide all'integrazione API, visita purple.ai. Grazie per l'ascolto.

📚 Part of our core series: Multi-Tenant WiFi →

header_image.png

Sintesi Esecutiva

Mentre le sedi fisiche aziendali — che spaziano dalle grandi catene di vendita al dettaglio [1] e gruppi alberghieri multi-sito [2] fino ai principali hub di trasporto [3] e istituti scolastici [4] — cercano di massimizzare il valore della loro infrastruttura wireless, i limiti dei controller hotspot integrati diventano un collo di bottiglia operativo significativo. L'ecosistema Ubiquiti UniFi fornisce hardware altamente affidabile, conveniente e scalabile. Tuttavia, il suo portale ospiti nativo manca delle funzionalità avanzate di acquisizione dati, analisi multi-sito, integrazione CRM, conformità alla privacy globale (GDPR, CCPA, PCI DSS) e monetizzazione richieste dalle moderne operazioni aziendali.

Questa guida tecnica di riferimento fornisce una panoramica architetturale completa per l'integrazione di Enterprise WiFi Intelligence Platform di Purple [5] su un'architettura Ubiquiti UniFi Network. Utilizzando la funzionalità External Portal Server di UniFi, i progettisti di rete e gli integratori di sistemi possono superare i limiti del controller locale. Questa integrazione instrada l'autenticazione degli ospiti attraverso il motore di identità e analisi sicuro e ospitato in cloud di Purple, trasformando un servizio di base in una risorsa di marketing e operativa di livello aziendale.

Approfondimento Tecnico

Per implementare un Captive Portal esterno sicuro e stabile, gli ingegneri di rete devono comprendere la comunicazione a basso livello e le transizioni di stato che si verificano quando un client non autenticato si connette alla rete wireless.

Il Ciclo di Vita della Connessione e del Reindirizzamento dell'Ospite

Il flusso di lavoro del Captive Portal UniFi opera su un rigoroso modello basato sullo stato. Quando un client si associa a un SSID abilitato per gli ospiti, viene avviato il seguente processo sequenziale:

Fase Componente Azione / Transizione di Stato Meccanismo Tecnico
1. Associazione Client & Access Point Il client si associa all'SSID; il server DHCP assegna l'indirizzo IP, la subnet mask, il gateway e i server DNS. Associazione 802.11 standard e lease DHCP.
2. Quarantena UniFi Access Point (AP) L'AP inserisce l'indirizzo MAC del client in uno stato In Quarantena / In Attesa (authorized: false). Regole di blocco Layer 2/3 applicate localmente sull'interfaccia virtuale dell'AP.
3. Intercettazione DNS Demone Locale AP L'AP esegue un processo DNSmasq locale che intercetta tutte le query DNS dai client in attesa. L'AP reindirizza tutto il traffico sulla porta 53 (UDP/TCP) al proprio risolutore DNS locale, indipendentemente dalle impostazioni DNS del client.
4. Intercettazione HTTP Reindirizzatore AP L'AP esegue un demone di reindirizzamento HTTP leggero sulla porta 80. Qualsiasi richiesta HTTP effettuata dal client viene intercettata. L'AP risponde con un reindirizzamento HTTP 302 Found.
5. Redirection Client Browser Il browser del client (o l'assistente del Captive Portal del sistema operativo) viene reindirizzato all'URL del portale esterno configurato. All'URL di reindirizzamento 302 vengono aggiunti parametri di query critici contenenti i metadati del client e dell'AP.
6. Authentication External Portal (Purple) Il client interagisce con la splash page di Purple, completando l'autenticazione (es. social login, registrazione e-mail, OTP via SMS). Sessione HTTPS sicura ospitata sull'infrastruttura cloud di Purple.
7. API Handshake Purple Cloud & UniFi Controller Purple convalida le credenziali ed emette una chiamata API sicura verso l'applicazione di rete UniFi. Chiamata REST API (richiesta POST) contenente il MAC address del client, l'ID del sito e i parametri di sessione.
8. Authorization UniFi Controller & AP Il controller UniFi aggiorna lo stato del client a authorized: true e invia l'ACL aggiornata all'AP. L'AP rimuove i blocchi di Livello 2/3 per il MAC address del client, concedendo il routing completo verso il gateway Internet.

The Redirection Query Parameters

Quando l'AP UniFi emette il reindirizzamento HTTP 302, aggiunge un set standardizzato di parametri di query all'URL del portale esterno. Il portale esterno deve acquisire questi parametri per identificare il client ed eseguire la successiva autorizzazione API:

https://portal.purplehotspot.com/guest/s/default/?ap=94:2a:6f:d0:30:57&id=1c:71:25:63:e4:24&t=1742398732&url=http://connectivitycheck.gstatic.com%2F&ssid=purple-guest
  • ap: Il MAC address dello specifico Access Point UniFi a cui è associato il client.
  • id: Il MAC address del dispositivo client che richiede l'accesso alla rete.
  • t: Un timestamp epoch Unix che rappresenta l'ora di inizio del reindirizzamento, utilizzato per la verifica della sicurezza.
  • url: L'URL originale a cui il client ha tentato di accedere (spesso un endpoint di rilevamento del captive portal del sistema operativo).
  • ssid: Il nome dell'SSID a cui si è connesso il client, consentendo al portale di presentare un branding specifico per il sito.

architecture_overview.png

The Walled Garden (Pre-Authorization Access Control)

Prima che un client sia autorizzato, tutto il traffico viene bloccato ad eccezione delle destinazioni esplicitamente definite nell'elenco di Pre-Authorization Access (comunemente noto come Walled Garden). Poiché i moderni dispositivi client eseguono assistenti Captive Portal automatici che testano la connettività tramite HTTPS, e poiché l'autenticazione esterna si affida spesso a provider di identità (IdP) di terze parti, la configurazione di un walled garden robusto e accurato è fondamentale.

Se un dominio o un intervallo IP richiesto viene omesso dal walled garden, la splash page non si caricherà, i pulsanti di social login si bloccheranno o il dispositivo client interromperà completamente la connessione WiFi, presumendo una rete non funzionante.

Implementation Guide

Questa sezione illustra la configurazione dettagliata richiesta per integrare il Captive Portal esterno di Purple con Ubiquiti UniFi Network Application (Controller).

Passaggio 1: Segmentazione della rete e configurazione VLAN

Per garantire la sicurezza e la conformità di livello aziendale (come PCI DSS e GDPR), il traffico degli ospiti deve essere completamente isolato dalle risorse aziendali, dai sistemi POS e dalle reti IoT.

  1. Passare a Impostazioni > Reti in UniFi Network Application.
  2. Fare clic su Crea nuova rete.
  3. Configurare le impostazioni di rete come segue:
    • Nome: Purple Guest Network
    • ID VLAN: 90 (o qualsiasi tag VLAN dedicato agli ospiti)
    • Tipo di rete: Ospite (applica automaticamente l'isolamento dei client, impedendo la comunicazione tra ospiti).
    • IP gateway/Subnet: Configurare una subnet appropriata (ad es. 10.90.0.1/22 per supportare fino a 1022 lease simultanei per gli ospiti).
    • Intervallo DHCP: Abilitare il DHCP e definire l'intervallo (ad es. da 10.90.0.10 a 10.90.3.254).
    • Server DNS: Impostare risolutori pubblici affidabili (ad es. Cloudflare 1.1.1.1 e Google 8.8.8.8) per garantire una risoluzione DNS rapida.

Passaggio 2: Configurazione dell'SSID ospite

  1. Passare a Impostazioni > WiFi e fare clic su Crea nuova rete WiFi.
  2. Configurare i parametri SSID:
    • Nome (SSID): Purple Guest WiFi
    • Protocollo di sicurezza: Aperto (l'autenticazione sarà gestita dal Captive Portal).
    • Rete: Selezionare la Purple Guest Network (VLAN 90) creata nel Passaggio 1.
    • Isolamento dispositivo client: Assicurarsi che sia impostato su ON.
  3. Scorrere fino a Hotspot Portal e selezionare la casella Abilita Captive Portal.

Passaggio 3: Configurazione del server del portale esterno

Una volta abilitato l'Hotspot Portal, è necessario reindirizzare l'autenticazione ai server cloud sicuri di Purple.

  1. Passare a Impostazioni > Profili > Hotspot ospite (o Impostazioni > Controllo ospiti nelle versioni precedenti del controller).
  2. In Autenticazione, selezionare Server del portale esterno.
  3. Configurare i seguenti campi:
    • IP / FQDN: Inserire l'FQDN fornito da Purple (ad es. portal.purplehotspot.com).
    • Usa portale sicuro (HTTPS): Attivare su ON (obbligatorio per la sicurezza e la compatibilità con i browser moderni).
    • Reindirizza utilizzando il nome host: Attivare su ON e inserire l'FQDN portal.purplehotspot.com.
    • Porta: 443 (HTTPS standard).
    • Reindirizzamento HTTPS: Attivare su ON (consente all'AP di intercettare le richieste HTTPS iniziali e reindirizzarle, sebbene richieda una gestione attenta del DNS).

Passaggio 4: Configurazione dell'accesso di pre-autorizzazione (Walled Garden)

Per consentire agli ospiti non autenticati di caricare la splash page di Purple e autenticarsi tramite provider di identità (IdP) di terze parti, aggiungere i seguenti domini e intervalli IP all'elenco Accesso di pre-autorizzazione in Impostazioni > Profili > Hotspot ospite > Accesso di pre-autorizzazione:

[
  "portal.purplehotspot.com",
  "*.purple.ai",
  "*.purplehotspot.com",
  "accounts.google.com",
  "ssl.gstatic.com",
  "*.googleapis.com",
  "*.facebook.com",
  "*.facebook.net",
  "*.fbcdn.net",
  "*.apple.com",
  "captive.apple.com",
  "connectivitycheck.gstatic.com",
  "*.microsoft.com",
  "*.live.com"
]

Nota: Per le installazioni che utilizzano l'elaborazione dei pagamenti Stripe, aggiungere *.stripe.com e *.stripe.network all'elenco di pre-autorizzazione.

Passaggio 5: Stabilire l'Handshake API

Affinché Purple possa autorizzare gli ospiti, i suoi server cloud devono comunicare con la tua applicazione UniFi Network.

Per UniFi Network Application 9.1 e versioni successive (REST API consigliata)

  1. Nel controller UniFi, vai su Settings > Control Plane > Integrations.
  2. Nella sezione API Keys, fai clic su Generate New API Key.
  3. Assegna un nome (es. Purple Integration Key) e imposta i permessi su Administrator.
  4. Copia la chiave API generata.
  5. Accedi al tuo Purple Portal, vai su Venue Settings > Integration > Ubiquiti UniFi e incolla la chiave API insieme al FQDN pubblico del tuo controller UniFi (es. unifi.yourdomain.com:443).

Per i controller legacy (API basata su credenziali)

  1. Vai su Settings > System > Admins.
  2. Crea un account amministratore locale dedicato (es. purple_api).
  3. Assegna i privilegi di Administrator o Hotspot Operator.
  4. Configura una password complessa e univoca.
  5. Nel Purple Portal, inserisci queste credenziali nella scheda UniFi Integration.

Best Practice

1. Requisiti del Certificato SSL

Non utilizzare mai un certificato SSL autofirmato su un controller UniFi di produzione o su un External Portal Server. I browser web moderni e i Captive Portal Assistant (CPA) dei sistemi operativi impongono una rigida convalida SSL/TLS. Un certificato autofirmato genererà un avviso di sicurezza altamente visibile (es. "La connessione non è privata"), con conseguenti tassi di abbandono elevati e danni all'immagine del brand.

  • Distribuisci un certificato SSL valido e pubblicamente attendibile (es. Let's Encrypt o un certificato CA commerciale) sul FQDN del controller UniFi.
  • Assicurati che l'FQDN del controller si risolva correttamente sia dalla VLAN ospiti interna che da internet pubblico.

2. Configurazione DNS

Una risoluzione DNS lenta è la causa principale del reindirizzamento lento al Captive Portal.

  • Non indirizzare il DNS degli ospiti all'IP locale del gateway UniFi, a meno che sul gateway non sia configurato un forwarding DNS ad alte prestazioni.
  • Invece, configura lo scope DHCP degli ospiti per distribuire server DNS pubblici veloci e resilienti direttamente ai client (es. Primario: 1.1.1.1, Secondario: 8.8.8.8).

3. Configurazione WiFi Ospiti RADIUS (Alternativa Enterprise)

Per le sedi che richiedono una sicurezza 802.1X basata su certificati o credenziali anziché un SSID aperto con un portale web, UniFi supporta l'integrazione con Cloud RADIUS esterni.

  • Configura un RADIUS Profile in Settings > Profiles > RADIUS.
  • Inserisci gli IP dei server RADIUS primario e secondario e i segreti condivisi (Shared Secrets) forniti da Purple.* Abilita RADIUS Accounting e imposta l'Interim Update Interval su 300 secondi per garantire il tracciamento delle sessioni in tempo reale.
  • Sotto le impostazioni SSID, imposta il protocollo di sicurezza su WPA2 Enterprise o WPA3 Enterprise [7] e seleziona il Profilo RADIUS.

comparison_chart.png

Risoluzione dei problemi e mitigazione dei rischi

Durante la distribuzione di Captive Portal esterni, gli amministratori di rete riscontrano frequentemente alcuni scenari di errore comuni. La tabella seguente illustra in dettaglio questi problemi, le loro cause principali e i passaggi esatti di mitigazione:

Sintomo Analisi della causa principale Azione correttiva e mitigazione
Schermata bianca / Impossibile caricare il portale Il dispositivo client non riesce a risolvere o raggiungere l'FQDN del server del portale esterno. 1. Verifica che portal.purplehotspot.com sia presente nell'elenco dei pre-authorisation access.
2. Assicurati che il client guest abbia ricevuto un IP valido e un server DNS tramite DHCP.
3. Esegui una ricerca DNS sul dispositivo client per verificare la risoluzione dell'FQDN del portale.
Errore SSL "La connessione non è privata" Il controller UniFi utilizza un certificato autofirmato o l'FQDN di reindirizzamento non corrisponde al nome comune del certificato SSL. 1. Installa un certificato SSL pubblicamente attendibile sul controller UniFi.
2. Verifica che Redirect Using Hostname sia abilitato e corrisponda esattamente all'FQDN sul certificato.
3. Disabilita "Redirect HTTPS" nelle impostazioni di controllo guest di UniFi per evitare che l'AP tenti di intercettare il traffico HTTPS sulla porta 443, il che genera naturalmente avvisi SSL.
L'autenticazione riesce, ma l'accesso a Internet è bloccato Il cloud Purple è riuscito ad autenticare l'utente, ma la chiamata API per autorizzare l'indirizzo MAC del client sul controller UniFi è fallita. 1. Controlla le regole del firewall per assicurarti che la porta 443 (o 8443 per i sistemi legacy) sia aperta in ingresso verso il controller UniFi dagli intervalli IP di Purple.
2. Verifica che la chiave API o le credenziali dell'amministratore locale inserite nel Portale Purple siano valide e dispongano dei permessi di amministratore.
3. Controlla i log del controller UniFi (server.log) per individuare eventuali errori di autenticazione API.
I pulsanti di accesso social (es. Google) non funzionano I domini di autenticazione dell'IdP sono bloccati dall'elenco di controllo degli accessi dell'AP. 1. Aggiungi i domini con wildcard completi per lo specifico IdP all'elenco dei pre-authorisation access (es. *.google.com, *.googleapis.com).
2. Se utilizzi Facebook, assicurati che i domini dell'SDK di Facebook siano completamente inseriti in whitelist.
Disconnessioni frequenti / Richieste di autenticazione ripetute Il timeout della sessione del Controller UniFi è più breve della durata della sessione di Purple, oppure i tempi di lease DHCP sono troppo brevi. 1. Allinea l'impostazione Session Timeout del Guest Hotspot UniFi con la policy di sessione di Purple (ad es., 24 ore).
2. Aumenta il tempo di lease DHCP sulla VLAN Guest ad almeno 12 o 24 ore per prevenire l'esaurimento degli indirizzi IP e la riautenticazione a metà sessione.

ROI e impatto sul business

Sebbene l'implementazione di un captive portal esterno richieda un'attenta ingegnerizzazione della rete, i risultati aziendali e il ritorno sull'investimento (ROI) superano di gran lunga la complessità dell'implementazione iniziale.

Acquisizione dati aziendali e arricchimento del CRM

Il portale ospiti nativo di UniFi è uno strumento "cieco"; concede l'accesso a Internet senza acquisire l'identità dell'utente. Integrando Purple, le strutture possono acquisire preziosi dati di prima parte (e-mail, numeri di telefono, profili social) in modo completamente conforme a GDPR e CCPA. Questi dati vengono sincronizzati automaticamente in tempo reale con i sistemi CRM, le piattaforme di marketing (ad es. Salesforce, HubSpot, Mailchimp) e i programmi di fidelizzazione, consentendo campagne di marketing altamente mirate che stimolano le visite ripetute e il valore del cliente nel tempo (customer lifetime value).

Gestione multi-sito e white-labeling

Per i Managed Service Provider (MSP) e gli operatori aziendali multi-sito, la gestione del WiFi per gli ospiti in centinaia di sedi tramite singoli controller UniFi è altamente inefficiente. Purple offre un'unica dashboard cloud centralizzata per gestire splash page, termini di conformità e analisi in tutte le sedi a livello globale, indipendentemente dalla distribuzione del controller UniFi sottostante.

Analisi in tempo reale e intelligenza spaziale

Purple trasforma la rete wireless UniFi in un potente array di sensori. Analizzando le probe request e i metadati di connessione, Purple fornisce una profonda intelligenza spaziale, tra cui:

  • Footfall Analytics: visitatori totali, traffico di passaggio e tassi di conversione (da passanti a visitatori entrati).
  • Dwell Time: durata media delle visite, segmentata per tipo di cliente (nuovo vs. di ritorno).
  • Recency e Frequency: frequenza con cui i clienti ritornano e tempo trascorso tra le visite.
  • Mappe termiche delle sedi (Heatmap): rappresentazione visiva del flusso e della densità dei visitatori, consentendo ai gestori di negozi e strutture di ottimizzare il layout e il personale.

Monetizzazione tramite i Retail Media Network

Per grandi spazi come stadi, centri commerciali e aeroporti, la splash page del captive portal rappresenta uno spazio digitale di grande valore. Purple consente alle strutture di monetizzare questo spazio integrandolo con i retail media network, offrendo pubblicità programmatica mirata, esperienze di login sponsorizzate e promozioni localizzate direttamente agli ospiti al momento della connessione.

Riferimenti

Definizioni chiave

Captive Portal

Una pagina web che intercetta la connessione di rete iniziale di un ospite e richiede l'autenticazione, la registrazione o l'accettazione dei termini prima di concedere l'accesso completo a Internet.

Si incontra immediatamente dopo la connessione a un SSID guest aperto; gestito dal redirector dell'AP e dal server del portale esterno.

External Portal Server

Un'applicazione web di terze parti (come Purple) che ospita la splash page per gli ospiti e gestisce l'autenticazione degli utenti, superando i limiti del portale del controller integrato.

Configurato nelle impostazioni di UniFi Guest Hotspot per sostituire la landing page nativa di UniFi.

Walled Garden (Pre-Authorization Access)

Una whitelist di domini, sottodomini o indirizzi IP a cui i client non autenticati possono accedere prima di completare il processo di login del Captive Portal.

Essenziale per caricare la pagina stessa del portale, le risorse CSS/JS e gli endpoint di login OAuth di terze parti.

DNSmasq

Un forwarder DNS leggero e server DHCP eseguito localmente sugli Access Point UniFi per intercettare e reindirizzare le query DNS dei guest durante lo stato di pre-autorizzazione.

Gestisce il reindirizzamento DNS iniziale che costringe i dispositivi client ad attivare i propri assistenti integrati per il Captive Portal.

API Authorization Handshake

Il processo in cui il server del portale esterno (Purple) effettua una chiamata API sicura al controller UniFi per far passare l'indirizzo MAC di un client da 'quarantined' a 'authorized'.

Avviene immediatamente dopo che l'utente ha completato con successo il flusso di login sulla splash page.

Client Device Isolation

Una funzionalità di sicurezza che impedisce ai client wireless sullo stesso SSID o VLAN di comunicare tra loro, mitigando il rischio di attacchi alla rete locale.

Abilitato nelle impostazioni WiFi e Network di UniFi per proteggere la privacy degli ospiti e mettere in sicurezza la rete della struttura.

RADSEC (RADIUS over TLS)

Un protocollo che protegge il traffico di autenticazione e accounting RADIUS racchiudendolo in un tunnel TLS sicuro, impedendo l'intercettazione e la manomissione sulle reti pubbliche.

Supportato in UniFi Network 8.4+ per implementazioni aziendali multi-sito sicure che utilizzano WPA2/WPA3 Enterprise.

CPA (Captive Portal Assistant)

Un'utilità di sistema integrata su iOS, Android, Windows e macOS che rileva automaticamente un Captive Portal tentando di recuperare un endpoint HTTP/HTTPS noto.

Attiva la finestra pop-up 'Accedi al WiFi' sul dispositivo dell'utente immediatamente dopo la connessione.

Esempi pratici

Un centro commerciale ad alta affluenza con 150 AP UniFi e un'applicazione UniFi Network self-hosted su AWS deve implementare Purple. Il team IT desidera utilizzare il social login con Google e Facebook per l'autenticazione degli ospiti. Tuttavia, durante i test iniziali, gli ospiti che fanno clic sui pulsanti di social login si trovano di fronte a una schermata vuota o a un errore di risoluzione DNS.

Il problema è causato da un walled garden restrittivo (Pre-Authorization Access) che impedisce al dispositivo dell'ospite di risolvere o raggiungere gli endpoint di autenticazione di Google e Facebook prima di essere autorizzato. Per risolvere questo problema, l'amministratore di rete deve accedere all'applicazione UniFi Network, andare su Settings > Profiles > Guest Hotspot ed espandere la sezione Pre-Authorization Access. Deve aggiungere i domini wildcard completi per i provider di identità Google e Facebook. Per Google, questo include accounts.google.com, ssl.gstatic.com e *.googleapis.com. Per Facebook, richiede *.facebook.com, *.facebook.net e *.fbcdn.net. Inoltre, assicurarsi che lo scope DHCP della rete ospiti sia configurato per distribuire server DNS pubblici e veloci (ad esempio, 1.1.1.1 e 8.8.8.8) direttamente ai client, invece di indirizzarli al gateway UniFi locale, che può diventare un collo di bottiglia per le query DNS di pre-autorizzazione.

Commento dell'esaminatore: Questo è un classico fallimento dovuto a una lacuna nel walled garden. Poiché i flussi di social login si basano su reindirizzamenti OAuth complessi su più sottodomini, l'omissione anche di un solo dominio di distribuzione dei contenuti (come il CDN di Facebook `fbcdn.net`) impedirà il rendering della pagina. I progettisti di rete dovrebbero sempre utilizzare le wildcard (`*.domain.com`) ove supportate dal controller e verificare la risoluzione DNS da un client non autenticato utilizzando strumenti standard come `nslookup` o `dig` sui domini inseriti nella whitelist.

Un MSP sta implementando Purple in una catena di 50 boutique hotel. Ogni hotel ha un UniFi Cloud Gateway Max locale in loco. L'MSP desidera gestire tutti i siti da un unico account Purple, ma è preoccupato per la sicurezza e per come il cloud di Purple comunicherà con i singoli controller locali per autorizzare gli indirizzi MAC degli ospiti, dato che i gateway locali si trovano dietro IP pubblici dinamici con NAT.

L'architettura ottimale utilizza l'API REST ufficiale di UniFi con port forwarding in entrata o un reverse proxy, combinato con il DNS dinamico (DDNS). Per ogni hotel: 1) Configurare un nome host DDNS sul Cloud Gateway Max (ad es. hotel01.mspdomain.com) in modo che l'IP pubblico del gateway sia sempre tracciabile. 2) Configurare una regola di port forwarding sul gateway per inoltrare il traffico HTTPS in entrata su una porta alta non standard (ad es. 10443) all'IP di gestione del gateway locale sulla porta 443. 3) Nel controller UniFi, andare su Settings > Control Plane > Integrations e generare una API Key univoca. 4) Nel Portale Purple, configurare una 'Venue' univoca per ogni hotel, selezionando l'integrazione Ubiquiti UniFi. Inserire l'indirizzo DDNS univoco con la porta inoltrata (ad es. hotel01.mspdomain.com:10443) e la API Key specifica generata per quel sito. Infine, proteggere il port forwarding in entrata su ciascun gateway limitando gli IP di origine agli intervalli IP del cloud pubblico di Purple, impedendo l'accesso non autorizzato dal resto di Internet.

Commento dell'esaminatore: L'uso di una porta alta non standard per il port forwarding, combinato con una whitelist rigorosa degli IP di origine per consentire solo i blocchi IP cloud di Purple, riduce i rischi di sicurezza legati all'esposizione della porta API del controller a Internet pubblico. Questa architettura evita la necessità di costosi IP pubblici statici in ogni sito, mantenendo al contempo solide funzionalità di autorizzazione MAC in tempo reale.

Domande di esercitazione

Q1. Un amministratore di rete ha configurato un captive portal esterno su una rete guest UniFi. Durante i test, nota che la splash page del captive portal si carica correttamente, ma dopo che l'ospite inserisce il proprio indirizzo email e clicca su 'Connetti', il browser si blocca e infine mostra un errore di timeout. Il client rimane in quarantena. Qual è la causa più probabile di questo problema e come dovrebbe essere esaminata?

Suggerimento: La pagina del portale è stata caricata, il che significa che il DNS e il walled garden funzionano. L'errore si verifica *dopo* che l'ospite ha inviato le proprie credenziali.

Visualizza risposta modello

La causa più probabile è un errore nell'handshake di autorizzazione API tra il cloud Purple e il controller UniFi. Poiché la pagina del portale è stata caricata e l'ospite ha potuto interagire con essa, le configurazioni DNS e di Pre-Authorization Access (Walled Garden) sono corrette. Tuttavia, quando l'ospite completa l'autenticazione, Purple tenta di inviare una chiamata API REST sicura (richiesta POST) al controller UniFi per autorizzare l'indirizzo MAC del client. Se il controller UniFi si trova dietro un firewall, NAT, o su una rete privata senza un corretto port forwarding, o se le credenziali API (o la chiave API) non sono corrette, la richiesta di autorizzazione fallirà o andrà in timeout. Per indagare: 1) Verificare che l'FQDN e la porta del controller UniFi siano accessibili pubblicamente dagli intervalli IP di Purple. 2) Controllare le regole del firewall in entrata sul gateway che protegge il controller UniFi per assicurarsi che la porta 443 (o 8443) sia aperta. 3) Nel portale Purple, verificare che le impostazioni di integrazione di UniFi contengano la chiave API o le credenziali di amministratore corrette e che l'URL del controller sia accurato. 4) Esaminare il file server.log del controller UniFi per eventuali tentativi di connessione in entrata o errori di autenticazione API provenienti dagli IP di Purple.

Q2. Un'implementazione aziendale richiede la configurazione di una rete ospiti con un Captive Portal esterno. L'architetto di rete desidera utilizzare HTTPS per tutto il traffico del Captive Portal per evitare lo sniffing delle credenziali. Abilita "Use Secure Portal (HTTPS)" e "Redirect Using Hostname" in UniFi, puntando all'FQDN del portale esterno. Tuttavia, quando i client si connettono, i loro browser visualizzano immediatamente un grave avviso di "SSL Certificate Common Name Mismatch" o "Certificate Not Trusted", bloccando l'accesso. Come si può risolvere questo problema?

Suggerimento: Pensa a quale dispositivo sta effettuando il reindirizzamento iniziale e quale certificato SSL sta presentando al client.

Visualizza risposta modello

Questo problema si verifica perché l'Access Point o il controller UniFi tenta di intercettare una richiesta HTTPS dal client e di reindirizzarla al Captive Portal. Quando un client si connette e tenta di visitare un sito web HTTPS (ad esempio, https://www.google.com), il redirector dell'AP intercetta il traffico. Per eseguire il reindirizzamento tramite HTTPS, l'AP deve presentare un certificato SSL. Poiché l'AP non possiede un certificato SSL valido per www.google.com, il browser del client rileva una condizione di Man-in-the-Middle (MITM) e genera un grave avviso SSL. Per risolvere questo problema: 1) Assicurarsi che il controller UniFi stesso abbia installato un certificato SSL valido e pubblicamente attendibile corrispondente all'FQDN configurato. 2) Nelle impostazioni della rete ospiti di UniFi, disabilitare "Redirect HTTPS" (lasciare abilitato solo il reindirizzamento HTTP). Ciò impedisce all'AP di tentare di intercettare il traffico HTTPS. Al contrario, la rete si affiderà al Captive Portal Assistant (CPA) del sistema operativo del dispositivo client, che verifica la connettività utilizzando endpoint HTTP semplici (ad esempio, http://captive.apple.com o http://connectivitycheck.gstatic.com). L'AP può intercettare in modo sicuro queste richieste HTTP sulla porta 80 e reindirizzarle all'URL HTTPS sicuro del portale Purple (https://portal.purplehotspot.com) senza attivare alcun avviso SSL del browser.

Q3. Una catena alberghiera desidera implementare la sicurezza WPA3-Enterprise per la propria rete ospiti VIP, mantenendo al contempo l'integrazione con la piattaforma di analisi di Purple. Il team IT locale non è sicuro di poter utilizzare il reindirizzamento standard del Captive Portal esterno con WPA3-Enterprise. Qual è l'approccio architetturale corretto per questo scenario?

Suggerimento: WPA3-Enterprise utilizza l'autenticazione 802.1X, che avviene nella fase di associazione, prima che venga assegnato un indirizzo IP. Questo è fondamentalmente diverso da un SSID aperto con un Captive Portal.

Visualizza risposta modello

WPA3-Enterprise (e WPA2-Enterprise) utilizza l'autenticazione 802.1X, che è fondamentalmente incompatibile con il reindirizzamento web standard del Captive Portal. In una rete 802.1X, l'autenticazione avviene nella fase di associazione (Layer 2) utilizzando metodi EAP (come EAP-TLS o PEAP) prima che al client venga assegnato un indirizzo IP o sia consentito l'accesso alla rete. Pertanto, non è possibile reindirizzare un client a una splash page basata sul web. Per integrare WPA3-Enterprise con Purple: 1) Passare dal modello 'External Portal Server' a un modello RADIUS esterno. 2) Configurare un Profilo RADIUS nell'applicazione UniFi Network, inserendo gli indirizzi IP dei server Cloud RADIUS di Purple, le porte di autenticazione (solitamente 1812), le porte di accounting (solitamente 1813) e il segreto condiviso. 3) Abilitare RADIUS Accounting e impostare un Intervallo di aggiornamento intermedio di 300 secondi. 4) Configurare l'SSID VIP per utilizzare WPA3 Enterprise e selezionare il profilo RADIUS. Quando un ospite VIP si connette, il suo dispositivo si autentica direttamente con il server Cloud RADIUS di Purple utilizzando le proprie credenziali aziendali univoche o un certificato. Il server RADIUS di Purple autorizza la connessione e riceve gli aggiornamenti di accounting, consentendo alla location di acquisire dati analitici sulla connessione, durata della sessione e utilizzo dei dati senza richiedere una splash page basata sul web.

Continua a leggere questa serie

Integrazione di CommScope Ruckus con Purple WiFi: Guida alla Configurazione e all'Installazione

Questa guida di riferimento tecnico fornisce un manuale di configurazione autorevole per l'integrazione delle architetture CommScope Ruckus con Purple WiFi. Dettaglia passo dopo passo le implementazioni per i Captive Portal per Guest WiFi, il WiFi aziendale sicuro per il personale tramite 802.1X e l'isolamento di rete Multi-Tenant utilizzando Ruckus Dynamic PSK.

Leggi la guida →

Integrazione degli Access Point Allied Telesis con Purple WiFi

Questa guida fornisce un playbook di configurazione completo per integrare gli access point Allied Telesis serie TQ con Purple WiFi. Copre il reindirizzamento al Captive Portal esterno, l'autenticazione RADIUS 802.1X e lo steering dinamico delle VLAN utilizzando le chiavi PPSK (Private Pre-Shared Keys) per implementazioni multi-tenant sicure.

Leggi la guida →

Integrazione degli Access Point Grandstream GWN con Purple WiFi

Questa guida tecnica di riferimento dettagliata spiega come integrare gli access point Grandstream GWN con la piattaforma di Guest WiFi e analytics di Purple. Copre la configurazione del Captive Portal Grandstream, le impostazioni RADIUS AAA, la configurazione del walled garden, l'autenticazione sicura del personale tramite 802.1X con instradamento VLAN dinamico e la segmentazione PPSK multi-tenant, offrendo una guida pratica e passo dopo passo per MSP e team IT che implementano WiFi per ospiti e personale su larga scala.

Leggi la guida →