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 system integrator che lavorano con UniFi Cloud Gateways, Dream Machines o con l'applicazione UniFi Network, questo episodio è per voi. Esamineremo 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 è la scelta architetturale corretta per le sedi che richiedono qualcosa in più di una semplice splash page.
Cominciamo.
[APPROFONDIMENTO TECNICO — circa 5 minuti]
In primo luogo, 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 vostro SSID guest, 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 dell'AP intercetta ogni query DNS effettuata dal dispositivo, indipendentemente dal server DNS che il dispositivo pensa di utilizzare. L'AP reindirizza tutto il traffico DNS verso se stesso.
Contemporaneamente, l'AP esegue un redirector HTTP leggero sulla porta 80. Non appena il browser dell'ospite effettua una 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 il portale Hotspot UniFi integrato, la splash page viene servita direttamente dall'applicazione UniFi Network. È funzionale, è rapido da configurare, ma è fortemente limitato. Si ottengono un'autenticazione tramite password di base, voucher e pagamenti Stripe. Non è previsto l'acquisizione di e-mail, il social login, la gestione del consenso GDPR, l'integrazione con CRM e nessuna analisi significativa oltre al conteggio delle sessioni.
Quando si configura un server portale esterno - che è l'impostazione 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 External Portal Server 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 all'applicazione di rete UniFi per autorizzare quell'indirizzo MAC.
Quella chiamata API è la stretta di mano cruciale. A partire da UniFi Network Application 9.1 e successive, è disponibile 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 si rivolge allo specifico ID client, con un corpo JSON che può 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. È fondamentale 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 login social - Facebook, Google, Microsoft - devi aggiungere anche i domini degli endpoint OAuth per tali provider. Gli endpoint di login di Google coprono più intervalli IP e diversi domini, tra cui accounts.google.com e oauth2.googleapis.com. L'infrastruttura di login di Facebook richiede analogamente diverse voci. La documentazione di Purple fornisce un elenco aggiornato delle voci esatte richieste, e questo elenco viene mantenuto aggiornato man mano che tali provider aggiornano la loro infrastruttura.
C'è una particolarità critica specifica di UniFi che mette in difficoltà molte distribuzioni. 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 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 è un requisito non negoziabile per le distribuzioni 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 di autorizzazione API 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 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 - rilevante quando si distribuisce Purple insieme a SSID WPA2-Enterprise o WPA3-Enterprise piuttosto che con il modello di SSID guest aperto - il server RADIUS integrato di UniFi supporta i metodi standard 802.1X EAP. Configura il profilo RADIUS in Impostazioni, Reti, Server RADIUS, quindi fai riferimento a quel 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'AP e il server di autenticazione. Per le distribuzioni multi-sito in cui il traffico RADIUS attraversa l'internet pubblico, RADSEC è fortemente raccomandato.
[RACCOMANDAZIONI DI IMPLEMENTAZIONE E TRAPPOLE COMUNI - circa 2 minuti]
Ecco la checklist pratica di 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 semplice: crea una rete dedicata in Impostazioni, Reti, assegnale un ID VLAN e associa l'SSID guest a tale rete. Abilita l'isolamento dei client sulla rete guest per impedire il traffico da guest a guest.
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 appropriato, ottieni un certificato Let's Encrypt o commerciale e configura UniFi per l'utilizzo di tale certificato. Questo risolve la maggior parte dei problemi di reindirizzamento HTTPS.
In terzo luogo, crea attentamente 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 che stai utilizzando. Esegui i test con un dispositivo che non si è mai connesso alla rete in precedenza - il DNS memorizzato nella cache 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 le autorizzazioni minime richieste. Non utilizzare le tue credenziali di amministratore principali. Se utilizzi Network Application 9.1 o versioni successive, utilizza il nuovo meccanismo di chiavi API in Control Plane, Integrazioni - è più sicuro e non richiede l'autenticazione basata su credenziali.
Quinto, valuta attentamente la durata della sessione. La scadenza predefinita della sessione ospite di UniFi può essere di sole otto ore. Per installazioni nel settore dell'ospitalità, in cui gli ospiti possono soggiornare per più notti, configura durate di sessione adeguate 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'installazione su un controller self-hosted 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 entrare in funzione.
[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 usare Purple su più siti UniFi da un singolo account Purple? Sì. L'architettura multi-sito di Purple è progettata esattamente per questo. Ogni sede è configurata come 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. 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 dal punto di vista dell'architettura solida. I passaggi chiave sono: configurare l'SSID ospite con l'opzione External Portal Server che punta all'URL del portale Purple, creare un walled garden completo che copra l'infrastruttura di Purple e tutti i provider OAuth in uso, 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 conforme alle normative e basata sull'analisi dei dati che si integra con il tuo CRM, acquisisce dati di prima parte con il consenso GDPR e fornisce le analisi delle presenze e del tempo di permanenza di cui i gestori delle sedi e i team di marketing hanno effettivamente bisogno.
Se sei un MSP o un system integrator che distribuisce UniFi su scala, la gestione multi-sito di Purple e le funzionalità white-label lo rendono la soluzione 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.
