Integrazione dell'autenticazione WeChat con i Captive Portal delle reti Guest WiFi

COME CONFIGURARE L'AUTENTICAZIONE OAUTH DI WECHAT PER I CAPTIVE PORTAL Un briefing tecnico di Purple - Circa 10 minuti --- INTRODUZIONE E CONTESTO (circa 1 minuto) Benvenuto. Se hai la responsabilità del WiFi per gli ospiti presso un hotel, una catena di negozi, uno stadio o un centro congressi che accoglie visitatori cinesi, questo briefing è rivolto a te. WeChat conta 1,38 miliardi di utenti attivi mensili, secondo i dati del 2024 di Tencent. La stragrande maggioranza si trova in Cina, ma la piattaforma vanta anche un'impronta internazionale significativa: quattro milioni di utenti negli Stati Uniti, 12 milioni in Malesia e numeri in crescita in tutto il Sud-est asiatico, in Europa e in Medio Oriente. Quando un ospite cinese si connette al tuo WiFi e visualizza una pagina di login che richiede solo un'e-mail, Facebook o un codice coupon, incontra un ostacolo immediato. Potrebbe non avere un indirizzo e-mail locale configurato su quel dispositivo. Di contro, avrà quasi certamente WeChat. Pertanto, la questione non è se offrire o meno l'accesso con WeChat, ma come configurarlo correttamente, in sicurezza e in modo da generare dati di prima parte che si possano effettivamente utilizzare. Questo è l'argomento che affronteremo oggi. Esamineremo il flusso OAuth 2.0, le due registrazioni di piattaforma necessarie, la scelta dello scope che determina quali dati raccogliere, il meccanismo di enforcement lato rete e le considerazioni di conformità fondamentali nel 2026. --- APPROFONDIMENTO TECNICO (circa 5 minuti) Iniziamo dall'architettura. Un Captive Portal intercetta il traffico HTTP proveniente da un dispositivo non autenticato e lo reindirizza a una pagina di login. Tale pagina di login è ospitata su un server del portale, sia on-premise che in cloud. Quando si aggiunge WeChat OAuth, si inserisce un provider di identità terzo in questo flusso. Ecco la sequenza. L'ospite si connette al tuo SSID. L'access point o il controller wireless rileva che il dispositivo non ha una sessione autenticata e reindirizza tutto il traffico HTTP all'URL del tuo Captive Portal. La pagina del portale si carica e presenta le opzioni di login, incluso WeChat. L'ospite seleziona l'accesso tramite WeChat. Il server del tuo portale reindirizza il browser all'endpoint di autorizzazione di WeChat, passando l'App ID, l'URI di reindirizzamento, il tipo di risposta basato su codice e lo scope. WeChat gestisce l'autenticazione interamente sui propri server. Se l'ospite ha già effettuato l'accesso a WeChat nel proprio browser, visualizza una schermata di consenso. Se sta utilizzando il browser in-app di WeChat, l'esperienza può avvenire in background con lo scope snsapi base, senza alcuna richiesta di consenso. WeChat reindirizza poi all'URI di reindirizzamento del tuo portale con un codice di autorizzazione temporaneo. Il server del tuo portale scambia tale codice con un token di accesso, passando l'App ID, l'App Secret, il codice e il tipo di concessione di codice di autorizzazione. WeChat restituisce un token di accesso, un token di aggiornamento, l'Open ID dell'utente e lo scope concesso. Se hai richiesto lo scope snsapi userinfo, puoi quindi effettuare una seconda chiamata API per recuperare il nickname, l'avatar, il genere e la città dell'utente. Ora, le due registrazioni della piattaforma. Questo è il punto in cui la maggior parte delle implementazioni fallisce. WeChat ha due diverse piattaforme per sviluppatori. La WeChat Open Platform gestisce le applicazioni web e le app mobile. La WeChat Official Accounts Platform gestisce gli account pubblici, ossia ciò di cui la maggior parte delle strutture ha effettivamente bisogno. Per un Captive Portal destinato agli ospiti all'interno del browser in-app di WeChat, è necessario un Service Account sulla Official Accounts Platform. Un Subscription Account non funzionerà, poiché non dispone dei permessi di autorizzazione per le pagine web tramite OAuth. Un Service Account, invece, li possiede e supporta sia l'ambito snsapi base che snsapi userinfo. Per un Captive Portal a cui si accede da un normale browser mobile al di fuori di WeChat (Chrome su Android, Safari su iOS), è necessaria una Website Application registrata sulla Open Platform. Questa utilizza l'ambito snsapi login e presenta un codice QR che l'utente scansiona con la propria app WeChat. In pratica, la maggior parte delle installazioni nelle strutture utilizza entrambi. Un ospite sulla rete WiFi di un hotel potrebbe aprire il portale in Chrome, vedere un codice QR, scansionarlo con WeChat e autenticarsi. Oppure potrebbe seguire un link all'interno di WeChat stessa, atterrare sul browser in-app e autenticarsi in modo silenzioso con snsapi base. Parliamo della selezione dell'ambito (scope), perché rappresenta un vero e proprio punto decisionale. snsapi base restituisce solo l'Open ID, un identificatore univoco per quell'utente all'interno del tuo Official Account. Non richiede alcuna richiesta di consenso all'utente. L'autenticazione è invisibile per l'utente. Questo è l'ideale per gli ospiti che ritornano e di cui hai già creato un profilo, o per le strutture in cui desideri azzerare gli attriti. snsapi userinfo restituisce l'Open ID insieme al nickname di WeChat dell'utente, all'immagine del profilo, al genere, alle impostazioni della lingua e alla città. Richiede una schermata di consenso esplicito. La maggior parte degli utenti accetta, ma si crea un attrito. La scelta corretta dipende dal tuo caso d'uso. Per la registrazione di un ospite che accede per la prima volta e di cui desideri creare un profilo, utilizza snsapi userinfo e associalo a un livello di consenso conforme al GDPR sulla pagina del tuo portale. Per un ospite che ritorna, che ha già fornito il consenso e di cui possiedi già il profilo, utilizza snsapi base per una ri-autenticazione silenziosa. Ora, passiamo al lato dell'applicazione di rete. L'ottenimento di un token OAuth prova l'identità, ma non apre automaticamente la rete. È necessario un meccanismo per tradurre un'autenticazione riuscita in accesso alla rete. I due approcci standard sono il RADIUS Change of Authorisation (CoA), definito nella specifica RFC 3576, e il bypass del MAC address. Con il RADIUS CoA, il server del tuo portale invia una richiesta CoA al controller di rete dopo che l'autenticazione OAuth è andata a buon fine, e il controller sposta il dispositivo dalla VLAN non autenticata alla VLAN ospiti. Questo sistema funziona con Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist e la maggior parte dei controller di livello enterprise. Con il bypass del MAC, il server del portale registra l'indirizzo MAC del dispositivo come client autorizzato e il controller lo abilita. Il bypass del MAC è più semplice da implementare ma meno sicuro, in quanto gli indirizzi MAC possono essere contraffatti. La piattaforma Guest WiFi di Purple gestisce entrambi i meccanismi. Al completamento di WeChat OAuth, l'overlay cloud di Purple invia il segnale appropriato all'hardware sottostante, sia esso Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme o Fortinet. L'operatore della sede non deve gestire questa traduzione manualmente. --- RACCOMANDAZIONI DI IMPLEMENTAZIONE E TRAPPOLE DA EVITARE (circa 2 minuti) Permettetemi di elencarvi i cinque fattori che causano il fallimento delle implementazioni del Captive Portal con WeChat OAuth. Primo: la mancata corrispondenza dell'URI di reindirizzamento. WeChat convalida l'URI di reindirizzamento rispetto al dominio autorizzato registrato sulla piattaforma. Se il server del vostro portale utilizza un sottodominio diverso, un percorso diverso o HTTP anziché HTTPS, il flusso OAuth fallisce con l'errore 40029 - codice non valido. Registrate ogni variante di dominio utilizzata, inclusi gli ambienti di staging. Secondo: l'App Secret sul lato client. Il vostro App Secret non deve mai apparire nel JavaScript lato client. Appartiene al vostro server. Se viene esposto, chiunque può impersonare la vostra applicazione e chiamare le API di WeChat per vostro conto. Terzo: mancanza di protezione CSRF. Il parametro di stato nella richiesta OAuth esiste specificamente per prevenire la falsificazione delle richieste intersito (cross-site request forgery). Generate un valore di stato crittograficamente casuale, memorizzatelo nella sessione dell'utente e convalidatelo al reindirizzamento di WeChat. Saltate questo passaggio e avrete una reale vulnerabilità. Quarto: il gap di rilevamento del browser in-app. Il browser in-app di WeChat imposta una stringa user agent specifica contenente MicroMessenger. Se il vostro portale non rileva questo elemento e non fornisce il corretto flusso OAuth, gli utenti riceveranno un'esperienza interrotta o un errore. Quinto: allineamento GDPR e PIPL. Se offrite servizi a visitatori europei, si applica il GDPR. Se vi rivolgete a visitatori cinesi, si applica la legge cinese sulla protezione delle informazioni personali (PIPL). Entrambe richiedono una base giuridica per il trattamento, una chiara limitazione delle finalità e la minimizzazione dei dati. "snsapi base" è più facile da giustificare in base ai principi di minimizzazione dei dati rispetto a "snsapi userinfo". Qualsiasi dato raccogliate, documentate la vostra base giuridica e il periodo di conservazione. --- DOMANDE E RISPOSTE RAPIDE (circa 1 minuto) Posso usare l'accesso WeChat su un portale che offre anche l'accesso tramite email e SMS? Sì. La maggior parte delle piattaforme di portali aziendali, inclusa Purple, supporta più metodi di autenticazione sulla stessa pagina del portale. WeChat OAuth funziona su iOS? Sì. L'accesso a WeChat in Safari su iOS funziona tramite il flusso del codice QR o il flusso di reindirizzamento. L'app WeChat stessa gestisce l'autenticazione. Cosa succede se l'API di WeChat non è disponibile? Implementate un fallback. Se la chiamata API di WeChat va in timeout o restituisce un errore, reindirizzate l'utente a un metodo di accesso alternativo. Posso utilizzare l'Open ID come identificatore cliente persistente? All'interno del vostro account ufficiale, sì. Per la risoluzione dell'identità cross-account su più proprietà, utilizzate invece l'UnionID. --- RIEPILOGO E PROSSIMI PASSI (circa 1 minuto) In sintesi. L'autenticazione WeChat OAuth per i Captive Portal richiede un'operazione di registrazione su due piattaforme, una decisione sull'ambito (scope), un'integrazione per l'applicazione delle policy di rete e una revisione della conformità. Gestendo correttamente questi quattro elementi, otterrai un metodo di accesso in grado di servire oltre un miliardo di potenziali visitatori, azzerando le frizioni legate alle password. I prossimi passi pratici: determina se i tuoi visitatori visualizzano il portale all'interno del browser in-app di WeChat o in un browser mobile standard. Definisci l'ambito (scope): snsapi base per gli utenti ricorrenti, snsapi userinfo per la prima registrazione previo consenso. Verifica che l'hardware di rete supporti RADIUS CoA. Esamina la tua informativa sulla privacy in conformità al GDPR e alla PIPL. Testa l'URI di reindirizzamento, la validazione del parametro di stato (state parameter) e il rilevamento del browser in-app prima del lancio ufficiale. Se desideri scoprire come Purple gestisce WeChat OAuth all'interno di una piattaforma più ampia di Guest WiFi e analytics — attiva su 80.000 location con 440 milioni di accessi nel 2024 — visita purple.ai o contatta il tuo account team. Grazie per l'attenzione. --- FINE DELLO SCRIPT