Come configurare l'autenticazione OAuth di WeChat per i Captive Portal

COME CONFIGURARE L'AUTENTICAZIONE WECHAT OAUTH PER I CAPTIVE PORTAL Un briefing tecnico Purple - Circa 10 minuti --- INTRODUZIONE E CONTESTO (circa 1 minuto) Benvenuto. Se sei responsabile del WiFi per gli ospiti in un hotel, una catena di negozi, uno stadio o un centro congressi che accoglie visitatori cinesi, questo briefing fa al caso tuo. WeChat conta 1,38 miliardi di utenti attivi mensili, secondo i dati di Tencent del 2024. La stragrande maggioranza si trova in Cina, ma la piattaforma ha anche un'importante presenza internazionale - 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 voucher, incontra un ostacolo immediato. Potrebbe non avere un indirizzo e-mail locale configurato su quel dispositivo. Sicuramente possiede WeChat. Quindi la domanda non è se offrire il login con WeChat - ma come configurarlo in modo corretto, sicuro e in grado di generare dati di prima parte che sia possibile utilizzare concretamente. Questo è ciò che tratteremo oggi. Esamineremo il flusso OAuth 2.0, le due registrazioni alla piattaforma necessarie, la scelta dell'ambito (scope) che determina quali dati raccogliere, il meccanismo di applicazione lato rete e le considerazioni sulla conformità rilevanti nel 2026. --- APPROFONDIMENTO TECNICO (circa 5 minuti) Iniziamo con l'architettura. Un Captive Portal intercetta il traffico HTTP da un dispositivo non autenticato e lo reindirizza a una pagina di login. Tale pagina di login è ospitata su un server del portale - in locale o nel cloud. Quando aggiungi WeChat OAuth, stai inserendo un provider di identità di terze parti in quel 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 il login WeChat. Il server del tuo portale reindirizza il browser all'endpoint di autorizzazione di WeChat all'indirizzo open.weixin.qq.com, passando il tuo AppID, l'URI di reindirizzamento, il tipo di risposta 'code' 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 utilizza il browser in-app di WeChat, l'esperienza può essere silenziosa con lo scope snsapi_base - senza alcuna richiesta di consenso. WeChat reindirizza quindi all'URI di reindirizzamento del tuo portale con un codice di autorizzazione temporaneo. Il server del tuo portale scambia quel codice con un token di accesso chiamando api.weixin.qq.com/sns/oauth2/access_token, passando il tuo AppID, AppSecret, il codice e il tipo di concessione authorization_code. WeChat restituisce un token di accesso, un token di aggiornamento, l'OpenID dell'utente e lo scope concesso. Se hai richiesto lo scope snsapi_userinfo, puoi effettuare una seconda chiamata API per recuperare il nickname, l'avatar, il sesso e la città dell'utente.Ora, parliamo delle due registrazioni sulla piattaforma. Questo è il punto in cui la maggior parte delle implementazioni fallisce. WeChat dispone di due piattaforme di sviluppo distinte. La WeChat Open Platform su open.weixin.qq.com gestisce le applicazioni web e le app mobili. La WeChat Official Accounts Platform su mp.weixin.qq.com gestisce gli account pubblici, ovvero ciò di cui la maggior parte delle strutture ha effettivamente bisogno. Per un Captive Portal che serve gli 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 OAuth. Un Service Account li possiede e supporta sia gli scope 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 un'applicazione web registrata sulla Open Platform. Questa utilizza lo scope 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 ed autenticarsi. Oppure potrebbe seguire un link all'interno di WeChat stesso, atterrare nel browser in-app ed autenticarsi in modo silenzioso con snsapi_base. Parliamo della selezione dello scope, perché si tratta di un vero e proprio punto decisionale. snsapi_base restituisce solo l'OpenID - 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 che hai già profilato, o per le strutture in cui desideri zero attrito al costo di zero nuovi dati. snsapi_userinfo restituisce l'OpenID più il nickname di WeChat dell'utente, l'immagine del profilo, il genere, la lingua impostata e la città. Richiede una schermata di consenso esplicito. L'utente visualizza una richiesta in cui si domanda se consente al tuo Official Account di accedere alle proprie informazioni. La maggior parte degli utenti accetta, ma c'è un elemento di attrito. La scelta corretta dipende dal tuo caso d'uso. Per la registrazione di un ospite che accede per la prima volta, dove 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 attesta 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 RADIUS Change of Authorisation, definito in RFC 3576, e il MAC address bypass. Con RADIUS CoA, il server del portale invia una richiesta CoA al controller di rete dopo che l'OAuth è andato a buon fine, e il controller sposta il dispositivo dalla VLAN non autenticata alla VLAN ospiti. Questo funziona con Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist e la maggior parte dei controller di livello enterprise. Con il MAC bypass, il server del portale registra l'indirizzo MAC del dispositivo come client autorizzato e il controller lo consente. Il MAC bypass è più semplice da implementare ma meno sicuro, perché gli indirizzi MAC possono essere falsificati. La piattaforma Guest WiFi di Purple gestisce entrambi i meccanismi. Al completamento dell'OAuth di WeChat, l'overlay cloud di Purple invia il segnale appropriato all'hardware sottostante - che si tratti di Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme Networks o Fortinet. L'operatore della sede non deve gestire questa traduzione manualmente. - RACCOMANDAZIONI DI IMPLEMENTAZIONE ED ERRORI DA EVITARE (circa 2 minuti) Ecco i cinque motivi per cui le implementazioni del captive portal con OAuth di WeChat falliscono. 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 portale utilizza un sottodominio diverso, un percorso diverso o HTTP invece di HTTPS, il flusso OAuth fallisce con l'errore 40029 - codice non valido. Registra ogni variante di dominio utilizzata, inclusi gli ambienti di staging. Secondo: l'AppSecret lato client. Il tuo AppSecret non deve mai apparire nel JavaScript lato client o nel file binario di un'app mobile. Deve risiedere sul tuo server. Se viene esposto, chiunque può impersonare la tua applicazione e chiamare le API di WeChat a tuo nome. Terzo: mancanza di protezione CSRF. Il parametro di stato nella richiesta OAuth esiste specificamente per prevenire la cross-site request forgery. Genera un valore di stato crittograficamente casuale, memorizzalo nella sessione dell'utente e convalidalo quando WeChat reindirizza all'indietro. Ignorare questo passaggio significa esporre il sistema a una reale vulnerabilità. Quarto: il divario di rilevamento del browser in-app. Il browser in-app di WeChat imposta una stringa user agent specifica contenente "MicroMessenger". Se il tuo portale non rileva questo elemento e non fornisce il flusso OAuth corretto - flusso Official Account per il browser in-app, flusso QR di Open Platform per i browser standard - gli utenti avranno un'esperienza interrotta o un errore. Quinto: allineamento con GDPR e PIPL. Se offri il servizio a visitatori europei, il GDPR si applica ai dati raccolti tramite l'OAuth di WeChat. Se offri il servizio a visitatori cinesi, la legge cinese sulla protezione delle informazioni personali - PIPL - si applica al modo in cui elabori i loro dati. Entrambi 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 tu raccolga, documenta la tua base giuridica e il periodo di conservazione. - DOMANDE E RISPOSTE RAPIDE (circa 1 minuto) Domanda: Posso utilizzare il login WeChat su un portale che offre anche l'accesso tramite e-mail e SMS? Sì. La maggior parte delle piattaforme di portali aziendali, inclusa Purple, supporta più metodi di autenticazione sulla stessa pagina del portale. WeChat appare come un'opzione insieme alle altre. Domanda: L'OAuth di WeChat funziona su iOS? Sì, ma con una sfumatura. Il framework App Tracking Transparency di Apple non influisce sui flussi OAuth lato server. Il login WeChat in Safari su iOS funziona tramite il flusso con codice QR o il flusso di reindirizzamento. L'app WeChat stessa gestisce l'autenticazione. Domanda: Cosa succede se l'API di WeChat non è disponibile? Il tuo portale dovrebbe implementare un fallback. Se la chiamata all'API di WeChat va in timeout o restituisce un errore, reindirizza l'utente a un metodo di login alternativo. Non lasciarli con una schermata vuota. Domanda: Posso utilizzare l'OpenID come identificativo persistente del cliente? All'interno del tuo Official Account, sì. L'OpenID è stabile per un determinato utente e un determinato Official Account. Se disponi di più Official Account, lo stesso utente avrà OpenID diversi tra di essi. Per la risoluzione dell'identità tra account diversi, WeChat fornisce un UnionID, che richiede che i tuoi account siano collegati sulla Open Platform. - RIASSUNTO E PROSSIMI PASSI (circa 1 minuto) Per riassumere. L'autenticazione OAuth di WeChat per i Captive Portal è un esercizio di registrazione su due piattaforme, una decisione sull'ambito, un'integrazione per l'applicazione delle regole di rete e una revisione della conformità. Se fai bene queste quattro cose, avrai un metodo di login che serve oltre un miliardo di potenziali visitatori con zero attriti legati alle password. I prossimi passi pratici sono questi. Per prima cosa, determina se i tuoi visitatori incontrano il portale all'interno del browser in-app di WeChat o in un browser mobile standard - questo determina quale registrazione di piattaforma ti serve. In secondo luogo, decidi l'ambito - snsapi_base per gli ospiti che ritornano, snsapi_userinfo per la registrazione iniziale con consenso. In terzo luogo, conferma che l'hardware di rete supporti RADIUS CoA o configura il bypass MAC come alternativa. In quarto luogo, verifica la tua informativa sulla privacy e il flusso di consenso rispetto ai requisiti GDPR e PIPL. In quinto luogo, testa l'URI di reindirizzamento, la validazione del parametro di stato e il rilevamento del browser in-app prima di andare online. Se vuoi vedere come Purple gestisce l'OAuth di WeChat come parte di una più ampia piattaforma di Guest WiFi e analytics - in 80.000 location e con 440 milioni di accessi nel 2024 - visita purple.ai o parla con il team del tuo account. Grazie per l'ascolto. - FINE DELLO SCRIPT