Guida alla configurazione del captive portal 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 presentatore e oggi entreremo nei dettagli dell'implementazione 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 sei un IT manager, un progettista di rete o un integratore di sistemi che lavora con UniFi Cloud Gateways, Dream Machines o con l'applicazione UniFi Network, questa puntata fa al caso tuo. Esamineremo esattamente come funziona il meccanismo del portale esterno sotto il cofano, come configurarlo correttamente, quali sono i punti critici più comuni e perché sovrapporre Purple a un'installazione UniFi rappresenta la scelta architetturale corretta per le sedi che richiedono qualcosa di più di una semplice splash page di base. Iniziamo. [APPROFONDIMENTO TECNICO - circa 5 minuti] Per prima cosa, cerchiamo di capire cosa succede effettivamente quando un dispositivo ospite si connette a un SSID UniFi con un captive portal abilitato. Quando un dispositivo ospite si associa al tuo 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 ritiene di utilizzare. L'AP reindirizza tutto il traffico DNS a se stesso. Contemporaneamente, l'AP esegue un redirector HTTP leggero sulla porta 80. Non appena 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. A questo punto, la distinzione tra portale integrato e portale esterno diventa fondamentale. Con il portale hotspot UniFi integrato, la splash page viene servita direttamente dall'applicazione UniFi Network. È funzionale, è veloce da configurare, ma è fortemente limitata. Offre un'autenticazione di base tramite password, voucher e pagamenti Stripe. Non c'è acquisizione di email, nessun social login, nessuna gestione del consenso GDPR, nessuna integrazione CRM e nessuna analisi significativa oltre al conteggio delle sessioni. Quando configuri un External Portal Server - che è l'impostazione su cui ci concentriamo oggi - stai dicendo 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 External Portal Server diventa la destinazione di tutti i reindirizzamenti 302. Ecco l'importante dettaglio tecnico riguardante l'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 all'applicazione UniFi Network per autorizzare quell'indirizzo MAC. Quella chiamata API rappresenta la stretta di mano fondamentale. A partire dalla versione 9.1 e successive di UniFi Network Application, è presente una REST API ufficiale con una corretta autenticazione basata su chiavi. L'endpoint di autorizzazione è una richiesta POST alla versione uno dell'API dei siti, che punta 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 dallo stato in sospeso a quello autorizzato. L'accesso a Internet viene così concesso. Parliamo ora del Walled Garden, che UniFi definisce Accesso Pre-Autorizzazione. 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 punta 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. L'infrastruttura di accesso di Facebook richiede allo stesso modo diverse voci. La documentazione di Purple fornisce un elenco aggiornato delle voci esatte richieste, e questo elenco viene mantenuto aggiornato man mano che i provider modificano la propria 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 contattano captive.apple.com tramite HTTPS. I dispositivi Android contattano connectivitycheck.gstatic.com. Se queste richieste HTTPS non ricevono una risposta specifica, il dispositivo potrebbe decidere che non è presente alcun Captive Portal e semplicemente non mostrare la schermata di accesso. La soluzione consiste nell'assicurarsi 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 aspetto non è negoziabile per le installazioni in 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, sarà necessario assicurarsi che le relative porte API siano accessibili. Per i controller self-hosted, si tratta in genere della porta 8443 per le API legacy, o della porta HTTPS standard 443 per le API più recenti introdotte 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 - che è rilevante quando si distribuisce Purple insieme a SSID WPA2-Enterprise o WPA3-Enterprise piuttosto che con il modello SSID guest aperto - il server RADIUS integrato di UniFi supporta i metodi standard 802.1X EAP. È possibile configurare il profilo RADIUS in Settings, Networks, RADIUS Servers, e quindi fare riferimento a tale profilo nella configurazione dell'SSID. UniFi supporta anche RADIUS su TLS, noto come RADSEC, a partire dalla versione 8.4, che crittografa il traffico RADIUS tra l'access point e il server di autenticazione. Per le distribuzioni multi-sito in cui il traffico RADIUS attraversa la rete internet pubblica, RADSEC è caldamente raccomandato. [CONSIGLI DI IMPLEMENTAZIONE E TRAPPOLE DA EVITARE - circa 2 minuti] Ecco la checklist pratica per l'implementazione che esaminerei con qualsiasi cliente che distribuisce Purple su UniFi. In primo luogo, la segmentazione della rete. L'SSID guest deve trovarsi su una VLAN dedicata, isolata dalle reti aziendali e IoT. UniFi rende questo processo lineare - crea una rete dedicata in Settings, Networks, assegna un VLAN ID e associa l'SSID guest a tale rete. Abilita l'isolamento dei client sulla rete guest per impedire il traffico tra dispositivi guest. In secondo luogo, il controller deve avere un FQDN valido e un certificato SSL attendibile. Non fare affidamento sull'indirizzo IP. Utilizza un nome di dominio appropriato, ottieni un certificato Let's Encrypt o un certificato commerciale su di esso e configura UniFi per utilizzare tale certificato. Questo risolve la maggior parte dei problemi di reindirizzamento HTTPS. In terzo luogo, costruisci con attenzione il tuo walled garden e testalo. Le voci minime sono: il dominio del portale Purple e i relativi intervalli IP, i domini di rilevamento del Captive Portal per iOS, Android e Windows, e tutti i domini dei provider OAuth in uso. Effettua i test con un dispositivo che non si è mai connesso alla rete in precedenza - 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'UniFi Network Application con i permessi minimi richiesti. Non utilizzare le tue credenziali di amministratore principali. Se utilizzi Network Application 9.1 o versioni successive, utilizza il nuovo meccanismo con chiave API in Control Plane, Integrations - è più sicuro e non richiede un'autenticazione basata su credenziali. In quinto luogo, considera attentamente la durata della sessione. La scadenza predefinita della sessione ospite di UniFi può essere di sole otto ore. Per le installazioni nel settore hospitality, dove gli ospiti possono soggiornare per più notti, configura le durate delle sessioni appropriate nelle impostazioni del portale Purple e assicurati che tali durate vengano passate correttamente nella chiamata di autorizzazione API. L'errore più comune che riscontro è l'implementazione 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à silenziosamente. Verifica sempre la connettività API dall'infrastruttura di Purple prima di andare online. [D&R RAPIDE - 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 dell'External Portal Server. L'applicazione Network 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 sul corrispondente sito UniFi. Devo aprire le porte del firewall sul gateway UniFi? Devi assicurarti che il traffico della VLAN ospite 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. Il WPA3 Enterprise utilizza 802.1X e RADIUS, che rappresenta 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 dell'architettura. I passaggi chiave sono: configurare l'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, assicurarsi che il controller UniFi abbia un certificato SSL valido e sia accessibile dai server API di Purple, e configurare durate di sessione adeguate al tipo di sede. Il vantaggio aziendale è evidente. Il portale integrato UniFi offre una splash page. Purple offre una piattaforma per l'esperienza degli ospiti pronta per la conformità e basata sull'analisi che si integra con il tuo CRM, acquisisce dati di prima parte nel rispetto del consenso GDPR e fornisce le analisi di affluenza e tempo di permanenza di cui i gestori delle sedi e i team di marketing hanno effettivamente bisogno. Se sei un MSP o un integratore di sistemi che distribuisce UniFi su scala, la gestione multi-sito e le funzionalità white-label di Purple lo rendono l'overlay ideale per i tuoi clienti. Per la documentazione dettagliata sulla configurazione, gli elenchi IP del walled garden e le guide all'integrazione delle API, visita purple.ai. Grazie per l'attenzione.