Ubiquiti UniFi and Purple WiFi: Integration Guide

Executive Summary

Ubiquiti UniFi è una delle piattaforme WiFi aziendali più diffuse al mondo, scelta da hotel, catene retail, stadi e organizzazioni del settore pubblico per le sue prestazioni, scalabilità e convenienza. Tuttavia, le sue funzionalità native di portale ospiti sono limitate. La piattaforma di WiFi intelligence di Purple colma questa lacuna integrandoci direttamente con l'UniFi Network Controller tramite la funzione External Portal Server, offrendo un'esperienza di Captive Portal completamente personalizzata con il proprio brand e ricca di dati analitici, senza richiedere hardware aggiuntivo.

Questa guida fornisce un riferimento tecnico completo per tale integrazione. Copre l'architettura sottostante, un processo di configurazione passo-passo sia per le versioni UniFi attuali (v7.4+) che per quelle legacy (v7.3 e precedenti), le best practice per la sicurezza e la conformità, e un framework strutturato per la risoluzione dei problemi. Le organizzazioni che completano questa integrazione ottengono l'accesso ad analisi dei visitatori in tempo reale, acquisizione dati conforme al GDPR, integrazione CRM e capacità di inviare comunicazioni di marketing mirate, trasformando il WiFi ospiti da un centro di costo a una risorsa aziendale misurabile.

Approfondimento Tecnico

L'integrazione tra Ubiquiti UniFi e Purple si basa sulla funzionalità External Portal Server di UniFi. Questa funzione reindirizza gli utenti ospiti dal controller UniFi locale a un Captive Portal di terze parti designato, in questo caso la piattaforma Purple. Il meccanismo sottostante si affida a una serie di reindirizzamenti HTTP e chiamate API che gestiscono il ciclo di vita dell'autorizzazione degli ospiti.

Quando un ospite si connette all'SSID ad autenticazione aperta designato, il controller UniFi imposta il suo dispositivo in uno stato "in attesa". In questo stato, tutto il traffico HTTP viene intercettato e reindirizzato all'URL della splash page di Purple, con parametri chiave aggiunti alla query string dell'URL: l'indirizzo MAC dell'ospite, l'indirizzo MAC dell'AP e l'identificatore del sito. La piattaforma Purple acquisisce questi parametri, presenta l'esperienza di accesso appropriata e, a seguito dell'avvenuta autenticazione dell'utente (tramite social login, modulo e-mail o voucher), effettua una chiamata API HTTPS sicura al controller di rete UniFi per autorizzare l'indirizzo MAC dell'ospite per una durata di sessione specificata. Questa autorizzazione sposta il dispositivo dallo stato "in attesa" allo stato "autorizzato", garantendogli l'accesso a Internet.

Un componente critico di questa architettura è il Walled Garden — una whitelist di indirizzi IP e domini a cui i dispositivi degli ospiti possono accedere prima dell'autenticazione. Questo è essenziale per consentire l'accesso ai domini di Purple, ai provider di social login (Facebook, Google), agli endpoint di rilevamento CNA di Apple e a qualsiasi altro servizio esterno richiesto. Senza un Walled Garden configurato correttamente, il Captive Portal non si caricherà affatto.

Per implementazioni più avanzate, la funzionalità PurpleConnex di Purple introduce il supporto Passpoint (IEEE 802.11u), utilizzando un server RADIUS per una riconnessione fluida e senza credenziali per gli utenti che ritornano. Ciò richiede la configurazione di un profilo RADIUS all'interno di UniFi che punti al server di autenticazione di Purple all'IP 34.150.158.147, sulle porte 1812 (autenticazione) e 1813 (accounting).

Guida all'implementazione

Questa sezione fornisce una guida passo-passo per configurare il tuo UniFi Network Controller per l'integrazione con Purple. Le seguenti istruzioni si applicano a UniFi Network Application versione 7.4 o successive. Per le versioni legacy (v7.3 e precedenti), i principi di configurazione sono identici ma il percorso di navigazione differisce leggermente, utilizzando Profili > Guest Hotspot anziché Hotspot Manager.

Passo 1: Verificare e stabilire l'accessibilità del controller. Prima di iniziare qualsiasi configurazione, conferma che il tuo UniFi Network Controller sia accessibile da internet pubblico. La piattaforma cloud di Purple deve essere in grado di comunicare con l'API del tuo controller per autorizzare le sessioni degli ospiti. Per i controller UniFi basati su software, ciò richiede una regola di port forwarding sul firewall che mappi la porta TCP 8443 sull'indirizzo IP LAN interno del controller. Per le implementazioni basate su hardware — inclusi UniFi Dream Machine Pro (UDM Pro), UDM Special Edition, UDR e CloudKey Gen2+ — la porta pertinente è la TCP 443.

Passo 2: Creare un account amministratore locale dedicato. Per motivi di sicurezza, non utilizzare mai le credenziali del tuo account super-admin Ubiquiti o cloud principale per l'integrazione con l'API di Purple. Crea un nuovo account amministratore locale dedicato sul tuo controller UniFi specificamente per questo scopo. Questo account deve disporre di privilegi amministrativi completi per il sito pertinente. L'utilizzo di un account dedicato limita il raggio d'azione di un'eventuale compromissione delle credenziali e garantisce che l'integrazione non venga interrotta da modifiche al tuo account principale. Step 3: Create the Guest WiFi SSID. In the UniFi Network Application, navigate to Settings > WiFi and click Create New. Assign a public-facing name (e.g., 'Hotel Guest WiFi'). Set the Security Protocol to Open — this is mandatory for the captive portal redirect mechanism to function. Assign the SSID to your designated Guest VLAN. Enable the Hotspot Portal toggle.

Step 4: Configure the Hotspot Portal and External Server. Navigate to Hotspot Manager > Landing Page. Under Authentication, select External Portal Server and enter the External Portal IP address provided by Purple. Under Settings, configure as follows: enable Secure Portal, enable Redirect using Hostname and enter the Access Domain provided by Purple, and ensure HTTPS Redirection is set to Disabled. The session Default Expiration should be set to 8 hours.

Step 5: Configure the Walled Garden. In the Hotspot Manager settings, locate the Pre-Authorization Access section. Add all domains from the list provided by Purple. This list typically includes Purple's own platform domains, social login provider domains (facebook.com, google.com, accounts.google.com), Apple's Captive Network Assistant (CNA) detection endpoints, and any other third-party services used on your splash page. This step is the most common source of deployment failures and must be completed with precision.

Step 6: Enter Controller Details in the Purple Portal. Log in to your Purple account and navigate to the relevant Venue's settings. Enter the public IP address or hostname of your UniFi Controller and the credentials for the dedicated local administrator account created in Step 2. Save the configuration. Purple will attempt to validate the connection.

Step 7: Test and Validate. Using a mobile device not previously connected to the network, connect to the new guest SSID. You should be automatically redirected to the Purple captive portal. Authenticate using one of the configured methods. Upon success, you should be granted internet access. If the redirect fails or internet access is not granted after authentication, refer to the Troubleshooting section below.

Best Practices

Network segmentation is the foundational security requirement for any guest WiFi deployment. The guest SSID must be assigned to a dedicated VLAN that is firewalled from all corporate and administrative networks. This prevents guest devices from accessing internal resources, satisfies PCI DSS network isolation requirements, and limits the impact of any security incident on the guest network.

Bandwidth management is equally important in high-density environments. UniFi's per-user rate limiting feature should be configured to set reasonable upload and download caps for guest users. This prevents a small number of high-bandwidth users from degrading the experience for all guests, which is particularly relevant in hotel and conference centre deployments.

Il Walled Garden richiede una manutenzione continua. I provider di social login e altri servizi di terze parti aggiornano periodicamente le loro strutture di dominio. Una revisione trimestrale della configurazione del Walled Garden, confrontata con l'elenco dei domini consigliati più recente di Purple, è una solida pratica operativa. La mancata manutenzione di questo elenco è la causa principale dei malfunzionamenti del portale post-implementazione.

Per l'integrazione API, utilizza sempre un account amministratore locale dedicato anziché un account collegato al cloud. Si tratta sia di una best practice di sicurezza sia di una misura di affidabilità: le credenziali dell'account cloud sono soggette a flussi di autenticazione a più fattori che possono interrompere le chiamate API automatizzate che Purple effettua per autorizzare gli ospiti.

Risoluzione dei problemi e mitigazione dei rischi

La modalità di errore più comune è un Captive Portal che non si carica. Quando un ospite si connette all'SSID ma non vede alcun reindirizzamento, o la pagina del portale non viene visualizzata, la causa principale è quasi invariabilmente un Walled Garden incompleto. Inizia la risoluzione dei problemi connettendo un dispositivo di test e provando a navigare su un URL HTTP noto. Se il reindirizzamento avviene ma la pagina non si carica, aggiungi i domini mancanti al Walled Garden. Verifica inoltre che il DNS della rete ospiti sia configurato correttamente per risolvere gli hostname esterni.

Il secondo errore più comune è uno scenario in cui l'ospite si autentica con successo sul portale Purple ma non riceve l'accesso a Internet. Ciò indica un errore nella comunicazione API tra Purple e il controller UniFi. I passaggi diagnostici sono: in primo luogo, confermare che il controller sia accessibile pubblicamente sulla porta corretta provando a raggiungerlo da una rete esterna; in secondo luogo, verificare che le credenziali dell'amministratore locale inserite nel portale Purple siano corrette e che l'account non sia stato bloccato; in terzo luogo, esaminare i log degli eventi del controller UniFi per verificare la presenza di eventuali errori di autenticazione API.

Per le implementazioni in produzione, la disponibilità del controller è un fattore di rischio critico. Se il controller UniFi va offline, le nuove autorizzazioni degli ospiti falliranno. Le strategie di mitigazione includono l'implementazione di un controller UniFi ospitato in cloud (che fornisce una ridondanza intrinseca), l'implementazione di una coppia di controller ad alta disponibilità o la configurazione di monitoraggio e avvisi sulla disponibilità del controller. La piattaforma di Purple metterà in coda i tentativi di autorizzazione e riproverà, ma un downtime prolungato del controller comporterà un'esperienza ospite degradata.

Dal punto di vista della conformità, i dati raccolti tramite il Captive Portal sono soggetti al GDPR e a normative equivalenti sulla protezione dei dati. La piattaforma di Purple è progettata per la conformità, fornendo gestione del consenso, strumenti per le richieste di accesso ai dati da parte degli interessati (DSAR) e policy di conservazione dei dati configurabili. Tuttavia, la responsabilità legale per il trattamento lecito dei dati rimane in capo al gestore della struttura. Assicurati che la tua informativa sulla privacy sia chiaramente collegata nella splash page, di disporre di una base giuridica documentata per la raccolta dei dati e che le impostazioni di conservazione dei dati siano in linea con la policy aziendale.

ROI e impatto aziendale

L'integrazione di Purple con UniFi non è un semplice aggiornamento tecnico; si tratta di una decisione aziendale strategica che trasforma il WiFi per gli ospiti da un centro di costo a una risorsa potente. Il ritorno sull'investimento è misurabile attraverso diverse dimensioni chiave.

La business intelligence è il principale motore di valore. Purple acquisisce dati ricchi e anonimizzati sul comportamento dei visitatori, inclusi affluenza, tempi di permanenza, frequenza delle visite e modelli di movimento. Per una catena di vendita al dettaglio, questi dati possono influenzare direttamente le decisioni sul layout del punto vendita, i livelli di personale e la tempistica delle promozioni. Per un hotel, possono rivelare quali servizi sono più utilizzati e in quali orari, consentendo un upselling più mirato e una maggiore efficienza operativa.

Le funzionalità di marketing e coinvolgimento rappresentano un significativo vantaggio secondario. Acquisendo i dettagli di contatto degli ospiti previo consenso, le organizzazioni possono creare un database di marketing di prima parte che non è soggetto alle limitazioni della deprecazione dei cookie di terze parti. Le campagne e-mail post-visita, i sondaggi sulla soddisfazione e gli inviti ai programmi di fidelizzazione possono essere automatizzati direttamente dalla piattaforma Purple, generando miglioramenti misurabili nei tassi di visite ripetute e nel valore del ciclo di vita del cliente.

Per le grandi strutture come stadi, centri congressi e centri commerciali, l'intelligence operativa derivata dall'analisi dell'affluenza in tempo reale e dalle mappe di calore può generare significativi guadagni di efficienza, ottimizzando i programmi di pulizia, il dispiegamento della sicurezza e il posizionamento delle concessioni commerciali sulla base di dati reali sui movimenti dei visitatori anziché su ipotesi.

In determinati contesti, l'infrastruttura WiFi per gli ospiti stessa può essere monetizzata attraverso modelli di accesso a livelli, splash page sponsorizzate o pubblicità mirata, creando un flusso di entrate diretto che compensa il costo dell'investimento infrastrutturale.