Come configurare l'autenticazione WeChat OAuth per i Captive Portal

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 ti occupi del WiFi per gli ospiti in un hotel, una catena retail, uno stadio o un centro congressi che accoglie visitatori cinesi, questo briefing è pensato per te. 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 una presenza internazionale significativa: quattro milioni di utenti negli Stati Uniti, 12 milioni in Malaysia 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 l'e-mail, Facebook o un codice coupon, incontra un ostacolo immediato. Potrebbe non avere un indirizzo e-mail locale configurato su quel dispositivo. Ma quasi certamente ha WeChat. Quindi la domanda non è se dovresti offrire il login con WeChat, ma come configurarlo correttamente, in modo sicuro e in una modalità che generi dati di prima parte effettivamente utilizzabili. Questo è l'argomento che tratteremo oggi. Analizzeremo il flusso OAuth 2.0, le due registrazioni sulla piattaforma necessarie, la scelta dello scope che determina quali dati raccogliere, il meccanismo di applicazione lato rete e le considerazioni sulla conformità che contano 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, on-premise o in cloud. Quando aggiungi l'OAuth di WeChat, inserisci un provider di identità di terze parti 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 il login con WeChat. Il server del tuo portale reindirizza il browser all'endpoint di autorizzazione di WeChat su open.weixin.qq.com, passando il tuo AppID, il redirect URI, il response type "code" e lo scope. WeChat gestisce l'autenticazione interamente sui propri server. Se l'ospite ha già effettuato l'accesso a WeChat nel 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 al redirect URI del tuo portale con un codice di autorizzazione temporaneo. Il server del tuo portale scambia quel codice con un access token chiamando api.weixin.qq.com/sns/oauth2/access_token, passando il tuo AppID, l'AppSecret, il codice e il grant type "authorization_code". WeChat restituisce un access token, un refresh token, 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 genere e la città dell'utente. Ora, le due registrazioni sulla piattaforma. Questo è il punto in cui la maggior parte delle implementazioni fallisce. WeChat ha 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 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 lo 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 deve scansionare con la propria app WeChat. All'atto pratico, la maggior parte delle installazioni nelle strutture utilizza entrambi i sistemi. Un ospite connesso al WiFi di un hotel potrebbe aprire il portale in Chrome, visualizzare un codice QR, scansionarlo con WeChat e autenticarsi. Oppure potrebbe seguire un link all'interno di WeChat stesso, atterrare sul browser in-app e autenticarsi in modo invisibile con snsapi_base. Parliamo ora della selezione dello scope, perché si tratta di una decisione cruciale. 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. Questa soluzione è ideale per gli ospiti che ritornano e di cui hai già un profilo, o per le strutture in cui si desidera eliminare ogni attrito a costo di non raccogliere nuovi dati. snsapi_userinfo restituisce l'OpenID più il nickname WeChat dell'utente, l'immagine del profilo, il genere, la lingua impostata e la città. Richiede una schermata di consenso esplicito. L'utente visualizza un messaggio in cui si chiede se consente al tuo Official Account di accedere alle sue informazioni. La maggior parte degli utenti accetta, ma questo introduce un passaggio in più. 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 riautenticazione invisibile. 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 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 il successo di OAuth, e il controller sposta il dispositivo dalla VLAN non autenticata alla VLAN guest. 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, poiché gli indirizzi MAC possono essere contraffatti. La piattaforma Guest WiFi di Purple gestisce entrambi i meccanismi. Al termine di WeChat OAuth, 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 o Fortinet. L'operatore della sede non deve gestire questa traduzione manualmente. --- RACCOMANDAZIONI DI IMPLEMENTAZIONE E TRAPPOLE COMUNI (circa 2 minuti) Ecco i cinque motivi principali per cui le implementazioni del Captive Portal con WeChat OAuth 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 anziché HTTPS, il flusso OAuth fallisce con l'errore 40029 - codice non valido. Registra ogni variante di dominio che utilizzi, inclusi gli ambienti di staging. Secondo: l'AppSecret sul lato client. L'AppSecret non deve mai apparire nel JavaScript lato client o nel file binario di un'app mobile. Deve risiedere sul server. Se viene esposto, chiunque può impersonare la tua applicazione e chiamare le API di WeChat per tuo conto. Terzo: la mancanza di protezione CSRF. Il parametro di stato nella richiesta OAuth esiste specificamente per prevenire la falsificazione delle richieste tra siti (cross-site request forgery). Genera un valore di stato crittograficamente casuale, memorizzalo nella sessione dell'utente e convalidalo quando WeChat reindirizza l'utente. Se salti questo passaggio, crei una reale vulnerabilità. Quarto: il mancato 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 Open Platform per i browser standard), gli utenti visualizzeranno un'esperienza interrotta o un errore. Quinto: allineamento a GDPR e PIPL. Se offri servizi a visitatori europei, il GDPR si applica ai dati raccolti tramite WeChat OAuth. Se offri servizi a visitatori cinesi, la legge cinese sulla protezione delle informazioni personali (PIPL) si applica al modo in cui elabori i loro dati. Entrambe le normative 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 base giuridica e il periodo di conservazione. --- DOMANDE E RISPOSTE RAPIDE (circa 1 minuto) Question: Can I use WeChat login on a portal that also offers email and SMS login? Yes. Most enterprise portal platforms, including Purple, support multiple authentication methods on the same portal page. WeChat appears as one option alongside others. Question: Does WeChat OAuth work on iOS? Yes, but with a nuance. Apple's App Tracking Transparency framework does not affect server-side OAuth flows. WeChat login in Safari on iOS works via the QR code flow or redirect flow. The WeChat app itself handles the authentication. Question: What happens if WeChat's API is unavailable? Your portal should implement a fallback. If the WeChat API call times out or returns an error, redirect the user to an alternative login method. Do not leave them with a blank screen. Question: Can I use the OpenID as a persistent customer identifier? Within your Official Account, yes. The OpenID is stable for a given user and a given Official Account. If you have multiple Official Accounts, the same user will have different OpenIDs across them. For cross-account identity resolution, WeChat provides a UnionID, which requires your accounts to be linked on the Open Platform. --- SUMMARY AND NEXT STEPS (approximately 1 minute) To summarise. WeChat OAuth authentication for captive portals is a two-platform registration exercise, a scope decision, a network enforcement integration, and a compliance review. Get those four things right and you have a login method that serves over a billion potential visitors with zero password friction. The practical next steps are these. First, determine whether your visitors encounter the portal inside the WeChat in-app browser or in a standard mobile browser - that determines which platform registration you need. Second, decide on scope - snsapi_base for returning guests, snsapi_userinfo for first-time registration with consent. Third, confirm your network hardware supports RADIUS CoA or configure MAC bypass as an alternative. Fourth, review your privacy notice and consent flow against GDPR and PIPL requirements. Fifth, test the redirect URI, the state parameter validation, and the in-app browser detection before you go live. If you want to see how Purple handles WeChat OAuth as part of a broader Guest WiFi and analytics platform - across 80,000 venues and 440 million logins in 2024 - visit purple.ai or speak to your account team. Thanks for listening. --- END OF SCRIPT