Captive Portal per Ubiquiti UniFi

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.