Intégration de l'authentification WeChat WiFi : Parcours d'inscription sur le Captive Portal pour les clients APAC

WeChat compte 1,41 milliard d'utilisateurs actifs mensuels, ce qui en fait l'identité numérique principale des consommateurs chinois dans le monde. Ce guide explique comment intégrer l'authentification WeChat OAuth 2.0 dans les portails captifs d'entreprise pour les sites de la région APAC, en couvrant l'enregistrement de la plateforme, la sélection de la portée, l'application du RADIUS Change of Authorisation, et la double conformité avec le GDPR et la PIPL chinoise. Il s'adresse aux responsables informatiques, aux architectes réseau et aux directeurs d'exploitation de sites qui doivent agir ce trimestre.

📖 9 min de lecture📝 2,051 mots🔧 2 exemples concrets❓ 4 questions d'entraînement📚 10 définitions clés

Écouter ce guide

Voir la transcription du podcast

COMMENT CONFIGURER L'AUTHENTIFICATION OAUTH WECHAT POUR LES CAPTIVE PORTALS
Une fiche technique Purple - Environ 10 minutes

INTRODUCTION ET CONTEXTE (environ 1 minute)

Bienvenue. Si vous êtes responsable du WiFi invités dans un hôtel, une chaîne de magasins, un stade ou un centre de conférences accueillant des visiteurs chinois, cette fiche technique vous est destinée.

WeChat compte 1,41 milliard d'utilisateurs actifs mensuels en 2025, selon les propres données de Tencent. La grande majorité se trouve en Chine, mais la plateforme possède également une empreinte internationale significative. La Malaisie compte 12 millions d'utilisateurs WeChat. Le Japon en compte 5,5 millions. La Corée du Sud, 5 millions. Et ces chiffres sont en croissance dans toute l'Asie du Sud-Est, au Moyen-Orient et en Europe.

Lorsqu'un visiteur chinois se connecte à votre WiFi et voit une page de connexion proposant uniquement l'e-mail, Facebook ou un code coupon, il fait face à une friction immédiate. Il se peut qu'il n'ait pas d'adresse e-mail locale configurée sur cet appareil. En revanche, il dispose presque certainement de WeChat. La question n'est donc pas de savoir si vous devez proposer la connexion WeChat, mais comment la configurer correctement, de manière sécurisée et afin de générer des données de première main que vous pouvez réellement exploiter.

C'est ce que nous allons aborder aujourd'hui. Nous allons détailler le flux OAuth 2.0, les deux enregistrements de plateforme requis, le choix du périmètre (scope) qui détermine les données collectées, le mécanisme d'application côté réseau et les considérations de conformité essentielles en 2026.

ANALYSE TECHNIQUE APPROFONDIE (environ 5 minutes)

Commençons par l'architecture. Un Captive Portal intercepte le trafic HTTP d'un appareil non authentifié et le redirige vers une page de connexion. Cette page de connexion est hébergée sur un serveur de portail, sur site ou dans le cloud. Lorsque vous ajoutez l'authentification OAuth WeChat, vous insérez un fournisseur d'identité tiers dans ce flux.

Voici la séquence. L'invité se connecte à votre SSID. Le point d'accès ou le contrôleur sans fil détecte que l'appareil n'a pas de session authentifiée et redirige tout le trafic HTTP vers l'URL de votre Captive Portal. La page du portail se charge et présente les options de connexion, y compris WeChat. L'invité appuie sur la connexion WeChat. Votre serveur de portail redirige le navigateur vers le point de terminaison d'autorisation de WeChat, en transmettant votre AppID, l'URI de redirection, le type de réponse (code) et le scope.

WeChat gère l'authentification entièrement sur ses propres serveurs. Si l'invité est déjà connecté à WeChat dans son navigateur, un écran de consentement s'affiche. S'il utilise le navigateur intégré à l'application WeChat, l'expérience peut être transparente avec le scope de base snsapi, ce qui signifie qu'aucune demande de consentement ne s'affiche. WeChat redirige ensuite vers l'URI de redirection de votre portail avec un code d'autorisation temporaire. Votre serveur de portail échange ce code contre un jeton d'accès en appelant l'API WeChat. WeChat renvoie un jeton d'accès, un jeton de rafraîchissement, l'OpenID de l'utilisateur et le scope accordé. Si vous avez demandé le scope snsapi userinfo, vous pouvez alors effectuer un second appel API pour récupérer le pseudo, l'avatar, le genre et la ville de l'utilisateur.

Passons maintenant aux deux enregistrements de plateforme. C'est ici que la plupart des implémentations échouent.

WeChat dispose de deux plateformes de développement distinctes. La plateforme WeChat Open gère les applications web et les applications mobiles. La plateforme WeChat Official Accounts gère les comptes publics, ce dont la plupart des établissements ont réellement besoin.

Pour un Captive Portal destiné aux clients utilisant le navigateur intégré à l'application WeChat, vous devez disposer d'un compte de service (Service Account) sur la plateforme Official Accounts. Un compte d'abonnement (Subscription Account) ne fonctionnera pas. Il ne dispose pas des autorisations d'authentification de page web OAuth. Un compte de service en dispose, et il prend en charge à la fois les portées (scopes) snsapi base et snsapi userinfo.

Pour un Captive Portal accessible depuis un navigateur mobile standard en dehors de WeChat, tel que Chrome sur Android ou Safari sur iOS, vous devez enregistrer une application de site web (Website Application) sur la plateforme Open. Celle-ci utilise la portée snsapi login et présente un code QR que l'utilisateur scanne avec son application WeChat.

En pratique, la plupart des déploiements sur site utilisent les deux. Un client d'un hôtel peut ouvrir le portail dans Chrome, voir un code QR, le scanner avec WeChat et s'authentifier. Ou il peut suivre un lien dans WeChat même, arriver sur le navigateur intégré à l'application et s'authentifier de manière transparente avec snsapi base.

Parlons du choix de la portée (scope), car il s'agit d'une véritable décision stratégique.

La portée snsapi base renvoie uniquement l'OpenID. Il s'agit d'un identifiant unique pour cet utilisateur au sein de votre compte officiel (Official Account). Elle ne nécessite aucune invite de consentement de l'utilisateur. L'authentification est invisible pour l'utilisateur. C'est idéal pour les clients récurrents dont vous avez déjà établi le profil, ou pour les établissements où vous souhaitez zéro friction au prix d'aucune nouvelle donnée.

La portée snsapi userinfo renvoie l'OpenID ainsi que le pseudo WeChat de l'utilisateur, sa photo de profil, son genre, ses paramètres de langue et sa ville. Elle nécessite un écran de consentement explicite. L'utilisateur voit une invite lui demandant s'il autorise votre compte officiel à accéder à ses informations. La plupart des utilisateurs acceptent, mais cela crée une friction.

Le bon choix dépend de votre cas d'usage. Pour l'enregistrement d'un nouveau client dont vous souhaitez créer le profil, utilisez snsapi userinfo et associez-le à une couche de consentement conforme au GDPR sur votre page de portail. Pour un client récurrent qui a déjà donné son consentement et dont vous possédez déjà le profil, utilisez snsapi base pour une réauthentification transparente.

Passons maintenant à l'application au niveau du réseau. L'obtention d'un jeton OAuth prouve l'identité, mais elle n'ouvre pas automatiquement le réseau. Vous avez besoin d'un mécanisme pour traduire une authentification réussie en accès réseau.

Les deux approches standards sont le changement d'autorisation RADIUS (RADIUS Change of Authorisation), défini dans la RFC 3576, et le contournement par adresse MAC (MAC address bypass). Avec le RADIUS CoA, votre serveur de portail envoie une requête CoA au contrôleur réseau après un OAuth réussi, et le contrôleur déplace l'appareil du VLAN non authentifié vers le VLAN invité. Cela fonctionne avec Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme et Fortinet.

Avec le contournement MAC, le serveur du portail enregistre l'adresse MAC de l'appareil en tant que client autorisé, et le contrôleur l'autorise. Le contournement MAC est plus simple à mettre en œuvre mais moins sécurisé, car les adresses MAC peuvent être usurpées, et les smartphones modernes utilisent de plus en plus la randomisation des adresses MAC, ce qui rompt le mécanisme lors de la reconconnexion.

La plateforme de Guest WiFi de Purple gère ces deux mécanismes. Une fois l'OAuth WeChat terminé, l'overlay cloud de Purple envoie le signal approprié au matériel sous-jacent. L'opérateur du site n'a pas besoin de gérer cette traduction manuellement.

RECOMMANDATIONS DE MISE EN ŒUVRE ET PIÈGES À ÉVITER (environ 2 minutes)

Laissez-moi vous présenter les cinq facteurs qui provoquent l'échec des intégrations de Captive Portal avec l'OAuth WeChat.

Premièrement : l'incohérence de l'URI de redirection. WeChat valide l'URI de redirection par rapport au domaine autorisé que vous avez enregistré sur la plateforme. Si votre serveur de portail utilise un sous-domaine différent, un chemin différent ou du HTTP au lieu du HTTPS, le flux OAuth échoue avec l'erreur 40029, ce qui signifie un code invalide. Enregistrez chaque variante de domaine que vous utilisez, y compris les environnements de staging.

Deuxièmement : l'AppSecret côté client. Votre AppSecret ne doit jamais apparaître dans le JavaScript côté client ni dans le binaire d'une application mobile. Sa place est sur votre serveur. S'il est exposé, n'importe qui peut usurper l'identité de votre application et appeler les API de WeChat en votre nom.

Troisièmement : l'absence de protection CSRF. Le paramètre d'état (state) dans la requête OAuth existe spécifiquement pour empêcher la falsification de requêtes intersites. Générez une valeur d'état cryptographiquement aléatoire, stockez-la dans la session de l'utilisateur et validez-la lorsque WeChat redirige l'utilisateur. Si vous ignorez cette étape, vous vous exposez à une réelle vulnérabilité.

Quatrièmement : le manque de détection du navigateur intégré à l'application. Le navigateur intégré de WeChat définit une chaîne d'agent utilisateur spécifique contenant MicroMessenger. Si votre portail ne détecte pas cela et ne propose pas le flux OAuth correct, les utilisateurs bénéficieront d'une expérience dégradée ou d'une erreur.

Cinquièmement : l'alignement avec le GDPR et la PIPL. Si vous accueillez des visiteurs européens, le GDPR s'applique aux données que vous collectez via l'OAuth WeChat. Si vous accueillez des visiteurs chinois, la loi chinoise sur la protection des informations personnelles, connue sous le nom de PIPL, s'applique à la manière dont vous traitez leurs données. Les deux réglementations exigent une base légale pour le traitement, une limitation claire des finalités et la minimisation des données. La portée de base snsapi base est plus facile à justifier au regard des principes de minimisation des données que snsapi userinfo. Quel que soit ce que vous collectez, documentez votre base légale et votre période de conservation.

QUESTIONS-RÉPONSES RAPIDES (environ 1 minute)

Question : Puis-je utiliser la connexion WeChat sur un portail qui propose également la connexion par e-mail et par SMS ?
Oui. La plupart des plateformes de portail d'entreprise, y compris Purple, prennent en charge plusieurs méthodes d'authentification sur la même page de portail. WeChat apparaît comme une option parmi d'autres.

Question : L'OAuth WeChat fonctionne-t-il sur iOS ?
Oui, mais avec une nuance. Le framework App Tracking Transparency d'Apple n'affecte pas les flux OAuth côté serveur. La connexion WeChat dans Safari sur iOS fonctionne via le flux de code QR ou le flux de redirection. L'application WeChat elle-même gère l'authentification.
Question : Que se passe-t-il si l'API de WeChat est indisponible ?
Votre portail doit implémenter une solution de repli. Si l'appel à l'API WeChat expire ou renvoie une erreur, redirigez l'utilisateur vers une autre méthode de connexion. Ne le laissez pas devant un écran vide.

Question : Puis-je utiliser l'OpenID comme identifiant client persistant ?
Au sein de votre compte officiel, oui. L'OpenID est stable pour un utilisateur donné et un compte officiel donné. Si vous possédez plusieurs comptes officiels, le même utilisateur aura des OpenID différents pour chacun d'eux. Pour la résolution d'identité multi-comptes, WeChat fournit un UnionID, ce qui nécessite que vos comptes soient liés sur l'Open Platform.

RÉSUMÉ ET PROCHAINES ÉTAPES (environ 1 minute)

En résumé, l'authentification OAuth WeChat pour les portails captifs est un exercice d'enregistrement sur deux plateformes, une décision de portée (scope), une intégration de l'application des règles réseau et un examen de conformité. Maîtrisez ces quatre aspects et vous disposerez d'une méthode de connexion qui dessert plus d'un milliard de visiteurs potentiels sans aucune friction liée aux mots de passe.

Voici les prochaines étapes pratiques. Tout d'abord, déterminez si vos visiteurs accèdent au portail depuis le navigateur intégré de WeChat ou depuis un navigateur mobile standard. Cela détermine l'enregistrement de plateforme dont vous avez besoin. Deuxièmement, décidez de la portée (scope). Utilisez snsapi base pour les clients récurrents, et snsapi userinfo pour un premier enregistrement avec consentement. Troisièmement, confirmez que votre matériel réseau prend en charge RADIUS CoA ou configurez le contournement MAC comme alternative. Quatrièmement, examinez votre avis de confidentialité et votre flux de consentement par rapport aux exigences du GDPR et de la PIPL. Cinquièmement, testez l'URI de redirection, la validation du paramètre d'état (state) et la détection du navigateur intégré avant de lancer le service.

Si vous souhaitez découvrir comment Purple gère l'authentification OAuth WeChat dans le cadre d'une plateforme plus large de Guest WiFi et d'analyse, sur 80 000 sites et 440 millions de connexions en 2024, visitez purple.ai ou contactez votre équipe de compte.

Merci pour votre écoute.

Points clés à retenir

✓WeChat compte 1,41 milliard d'utilisateurs actifs mensuels (Tencent, 2025), ce qui en fait l'identité numérique principale des consommateurs chinois. Les établissements accueillant des clients de la région APAC ne peuvent pas se permettre de l'exclure des options de connexion de leur Captive Portal.
✓Deux enregistrements de plateforme sont requis : un Service Account sur l'Official Accounts Platform pour l'accès via le navigateur intégré à l'application, et une Website Application sur l'Open Platform pour l'accès via un navigateur standard. L'utilisation d'un mauvais type d'enregistrement est l'erreur d'implémentation la plus courante.
✓La sélection du Scope est une véritable décision d'architecture. Utilisez snsapi_base pour une authentification silencieuse et sans friction qui ne renvoie qu'un OpenID. Utilisez snsapi_userinfo pour collecter des données démographiques, en acceptant la friction d'un écran de consentement.
✓L'OAuth prouve l'identité mais n'ouvre pas le réseau. Le RADIUS Change of Authorisation (RFC 3576) est le mécanisme qui traduit un échange de jeton réussi en une promotion VLAN. Sans cela, les clients authentifiés restent bloqués.
✓L'AppSecret doit être stocké uniquement côté serveur. Une exposition dans le code côté client permet l'usurpation d'identité de votre application et un accès non autorisé à l'API de WeChat.
✓Le GDPR et la PIPL s'appliquent tous deux aux données collectées via l'OAuth WeChat. Documentez votre base légale, appliquez la minimisation des données et assurez-vous que votre couche de consentement est conforme avant la mise en service.
✓Pour les déploiements multi-établissements, implémentez l'UnionID de WeChat dès le départ. Les OpenID diffèrent selon l'Official Account ; l'UnionID fournit une identité client cohérente sur l'ensemble des comptes associés.

📚 Fait partie de notre série principale : Captive Portal Guide →

Executive summary

For enterprise venues operating across the APAC region, or serving Chinese tourists globally, WeChat WiFi authentication is no longer optional. With 1.41 billion monthly active users as of 2025 (source: Tencent), WeChat is the primary digital identity for Chinese consumers. A guest who connects to your SSID and sees only email or Facebook login options faces immediate friction. They almost certainly have WeChat. They almost certainly do not have a local email address configured on that device.

This guide details how to integrate WeChat OAuth 2.0 into a captive portal. We cover the two distinct platform registrations Tencent requires, the scope decision that determines what first-party data you collect, and the RADIUS Change of Authorisation (CoA) mechanism that translates a successful OAuth exchange into actual network access. We also address the overlapping compliance requirements of GDPR and China's Personal Information Protection Law (PIPL).

Purple's Guest WiFi platform automates the network enforcement layer across Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme, and Fortinet hardware. Purple operates across 80,000+ live venues and recorded 440 million logins in 2024 (Purple internal data).

Technical deep-dive

The OAuth 2.0 flow

A captive portal (a web-based authentication gateway that intercepts HTTP traffic from unauthenticated devices) redirects guests to a login page hosted on a portal server, either on-premises or in the cloud. Adding WeChat OAuth inserts Tencent's identity infrastructure into that flow.

The sequence runs as follows. The guest associates with the SSID. The wireless controller detects the absence of an authenticated session and redirects all HTTP traffic to the captive portal URL. The portal page loads and presents login options, including WeChat. The guest selects WeChat. The portal server constructs a redirect to WeChat's authorisation endpoint at open.weixin.qq.com, passing four parameters: the AppID, the redirect URI, the response type set to code, and the requested scope.

WeChat authenticates the user entirely on its own infrastructure. If the guest is already signed in via the WeChat in-app browser, the snsapi_base scope allows silent authentication with no visible prompt. WeChat redirects back to the portal's registered redirect URI with a short-lived authorisation code. The portal server exchanges this code for an access token by calling api.weixin.qq.com/sns/oauth2/access_token with the AppID, AppSecret, code, and grant type. WeChat returns an access token, a refresh token, the user's OpenID, and the granted scope. If snsapi_userinfo was requested, a second API call to api.weixin.qq.com/sns/userinfo retrieves the user's nickname, profile image, gender, and city.

Platform registration: the decision that trips most deployments

Tencent operates two separate developer platforms, and selecting the wrong one is the most common cause of failed implementations.

Access context	Required registration	Platform URL	Supported scopes
WeChat in-app browser	Service Account (Official Accounts Platform)	mp.weixin.qq.com	snsapi_base, snsapi_userinfo
Standard mobile browser (Chrome, Safari)	Website Application (Open Platform)	open.weixin.qq.com	snsapi_login (QR code flow)

A Subscription Account on the Official Accounts Platform will not work. It lacks OAuth web page authorisation permissions. Only a Service Account carries those permissions.

Most enterprise deployments in Hospitality and Retail implement both registrations. A guest at a hotel might open the portal in Chrome, scan a QR code with WeChat, and authenticate via the Open Platform flow. Or they might follow a link inside WeChat itself, land in the in-app browser, and authenticate silently via the Official Accounts flow. Both paths must be handled.

Scope selection and data collection

The OAuth scope is a genuine architectural decision, not a configuration detail. It determines the friction the user experiences and the data your WiFi Analytics platform receives.

snsapi_base returns only the OpenID - a stable, unique identifier for that user within your Official Account. It requires no user consent prompt. Authentication is invisible. Use this for returning guests whose profiles you already hold, or for high-throughput environments such as stadiums and transport hubs where connection speed is the priority.

snsapi_userinfo returns the OpenID plus nickname, profile image, gender, language setting, and city. It triggers an explicit consent screen. Use this for first-time guest registration to build a first-party data profile, paired with a PIPL-compliant and GDPR-compliant consent layer on the portal page.

The practical rule: use snsapi_base for speed, snsapi_userinfo for data. You can implement both by checking whether the user's OpenID already exists in your database. If it does, request snsapi_base. If it does not, request snsapi_userinfo.

Network enforcement: RADIUS CoA and MAC bypass

An OAuth token proves identity. It does not open the network. A separate mechanism must translate the successful authentication into a network policy change.

RADIUS Change of Authorisation (CoA), defined in RFC 3576, is the standard approach. After the portal server receives a valid OAuth token, it sends a CoA request to the wireless controller. The controller updates the session, moving the device from the walled garden VLAN (a restricted network segment that allows only portal traffic) to the full guest VLAN. This works with Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme, and Fortinet.

MAC address bypass registers the device's MAC address as an authorised client after successful OAuth. The controller then permits traffic from that address without further challenge. It is simpler to implement but carries two risks: MAC addresses can be spoofed, and iOS 14 and Android 10 onwards use MAC address randomisation by default, which breaks the mechanism on reconnection.

For any deployment where security matters, RADIUS CoA is the correct choice. For more on securing guest networks, see What Is Secure WiFi: Essential Guide for Business 2026 and Enterprise WiFi Security: A Complete Guide for 2026 .

Implementation guide

Pre-deployment checklist

Before writing a line of configuration, complete these five steps.

First, determine the access context. Survey your venue and identify whether guests will encounter the portal inside the WeChat in-app browser, in a standard mobile browser, or both. The answer determines your platform registration requirements.

Second, register on the correct platform. For in-app browser access, create a Service Account on the WeChat Official Accounts Platform. For standard browser access, register a Website Application on the WeChat Open Platform. Note your AppID and AppSecret for each.

Third, configure your redirect URIs. Register every domain and subdomain your portal uses, including staging environments. WeChat enforces exact-match validation. A mismatch returns error 40029.

Fourth, implement server-side token exchange. The AppSecret must never appear in client-side code. Build a server-side endpoint that accepts the authorisation code, exchanges it for a token, and returns only the data your portal needs.

Fifth, implement the state parameter for CSRF protection. Generate a cryptographically random value, store it in the user's session, pass it in the OAuth request, and validate it on return.

Configuration steps for Ruckus SmartZone

For venues running Ruckus SmartZone, the WeChat portal configuration sits under Services and Profiles, then Hotspots and Portals, then the WeChat tab. You configure the Authentication URL (your portal server's WeChat callback endpoint), the DNAT Destination (the server that handles unauthenticated client redirects), and the Grace Period (the window during which a recently disconnected user can reconnect without re-authenticating, defaulting to 60 minutes). You also configure the walled garden whitelist to permit traffic to WeChat's API endpoints during the authentication phase. See also the Step-by-Step Guide: Configuring Ruijie Wireless Controllers for Guest WiFi Captive Portals for comparable controller configuration patterns.

In-app browser detection

WeChat's in-app browser sets a user agent string containing MicroMessenger. Your portal must detect this string and serve the appropriate OAuth flow. If MicroMessenger is present, use the Official Accounts flow. If absent, use the Open Platform QR code flow. Failure to detect this correctly produces broken experiences or authentication errors.

Best practices

Data minimisation and dual-framework compliance

GDPR (applicable to European visitors) and PIPL (applicable to Chinese citizens) both require a lawful basis for processing personal data, clear purpose limitation, and data minimisation. The snsapi_base scope is easier to justify under data minimisation principles than snsapi_userinfo. When you do collect demographic data via snsapi_userinfo, document your legal basis, your retention period, and your data processing agreement with Tencent.

PILP, in force since November 2021, requires explicit consent for sensitive personal information and mandates that data processors outside China implement equivalent protection standards. If your portal server sits outside mainland China, you must assess whether cross-border data transfer rules apply to the WeChat OpenID and profile data you receive.

UnionID for multi-property deployments

The OpenID is unique per user per Official Account. If you operate multiple Official Accounts across properties, the same guest will have different OpenIDs in each. WeChat provides a UnionID that remains consistent across all accounts linked to the same Open Platform registration. For hotel chains, retail groups, or airport operators managing multiple venues, implement UnionID-based identity resolution from the start.

Security hardening

Store the AppSecret in an environment variable or secrets manager, never in source code. Rotate it immediately if you suspect exposure. Implement rate limiting on your token exchange endpoint to prevent abuse. Log all OAuth errors, particularly 40029 (invalid code) and 40163 (code expired), as these indicate either misconfiguration or active probing.

For a broader view of guest network security architecture, see Why Consumer WiFi Gear Doesn't Belong on Your Guest Network .

Case studies

Luxury hotel chain, Singapore

A 350-room luxury hotel in Singapore serving a predominantly Chinese business travel segment implemented WeChat WiFi authentication alongside their existing email login option. Prior to implementation, front-desk staff reported an average of 15 guest complaints per day about WiFi login difficulties. Chinese guests were attempting to use email addresses they had not configured on their travel devices.

The hotel registered a Service Account on the WeChat Official Accounts Platform and a Website Application on the Open Platform. They configured snsapi_userinfo for first-time connections and snsapi_base for returning guests identified by MAC address. The HPE Aruba controller was configured for RADIUS CoA to handle session promotion.

Within 30 days, guest WiFi login complaints dropped to under two per day. The hotel's WiFi Analytics database grew by 4,200 verified first-party profiles in the first month, with city-level demographic data enabling targeted post-stay communications.

International retail mall, Kuala Lumpur

A premium retail mall in Kuala Lumpur with 12 million WeChat users in Malaysia alone needed a WiFi onboarding experience that matched the digital expectations of its shopper base. The mall operated Cisco Meraki access points across 180,000 square metres of retail floor.

The deployment used Purple's Guest WiFi platform as the cloud overlay, with WeChat OAuth as the primary authentication method and SMS OTP as the fallback. Purple's hardware-agnostic architecture handled the RADIUS CoA integration with Cisco Meraki without requiring custom development.

The mall recorded a 34% increase in WiFi session starts in the first quarter post-deployment, attributed to reduced onboarding friction for WeChat users. The first-party data collected via snsapi_userinfo consent flows enabled the mall's marketing team to segment shoppers by home city for targeted campaign delivery.

Troubleshooting and risk mitigation

Error	Cause	Resolution
40029 invalid code	Redirect URI mismatch or code reuse	Verify registered URIs match exactly; codes are single-use
40163 code expired	Token exchange delayed beyond 5 minutes	Reduce server-side processing time; implement retry logic
Blank screen after authentication	RADIUS CoA not configured or failing	Check controller CoA settings and firewall rules on UDP port 3799
MAC randomisation breaks returning guest flow	iOS/Android MAC randomisation	Migrate to OpenID-based session tracking; avoid MAC-only identification
snsapi_userinfo returns empty fields	User has set WeChat privacy restrictions	Handle null fields gracefully; do not require profile data for access

ROI and business impact

The business case for WeChat WiFi authentication rests on three measurable outcomes.

First-party data acquisition. Each snsapi_userinfo authentication generates a verified guest profile with demographic data. For a 200-room hotel running at 70% occupancy with 40% Chinese guests, that represents approximately 20,000 new verified profiles per year, each tied to a WeChat identity that supports ongoing re-engagement.

Reduced support burden. Login friction is the primary driver of guest WiFi support calls. Venues that add WeChat authentication alongside existing options consistently report a reduction in WiFi-related front-desk queries, freeing staff time for higher-value interactions.

Marketing reach. WeChat Official Accounts allow venues to push notifications to followers. A guest who authenticates via your Official Account can be prompted to follow it, creating a direct communication channel that operates within WeChat's ecosystem, where Chinese consumers spend an average of 82 minutes per day (source: Walk the Chat).

Purple's Engage plan extends this further, enabling automated post-visit messaging, loyalty triggers, and segmented campaigns built on the first-party data collected at the point of WiFi authentication.

Définitions clés

Captive Portal

Une passerelle d'authentification web qui intercepte le trafic HTTP d'un appareil non authentifié et le redirige vers une page de connexion avant d'accorder l'accès au réseau.

Le mécanisme par lequel l'authentification au WiFi invité est présentée aux utilisateurs. WeChat OAuth est l'une des nombreuses méthodes d'authentification qu'un Captive Portal peut proposer.

OAuth 2.0

Un protocole d'autorisation standard de l'industrie qui permet à une application tierce (le Captive Portal) d'obtenir un accès limité à un service web (WeChat) au nom d'un utilisateur, sans que celui-ci ne partage son mot de passe avec le tiers.

Le framework sous-jacent qui permet la connexion WeChat. Le portail ne voit jamais les identifiants WeChat de l'utilisateur ; il reçoit uniquement un jeton confirmant que WeChat l'a authentifié.

RADIUS CoA

Change of Authorisation. Un mécanisme défini dans la RFC 3576 qui permet à un serveur RADIUS de modifier dynamiquement les attributs d'autorisation de session d'un client réseau actif, comme le changement d'attribution de VLAN.

Le mécanisme d'application réseau qui traduit un échange WeChat OAuth réussi en un accès réseau réel. Sans CoA, l'invité s'authentifie mais le contrôleur ne sait pas qu'il doit ouvrir le réseau.

OpenID

Un identifiant unique attribué par WeChat à un utilisateur spécifique pour un compte officiel ou une application web spécifique. Il est stable d'une session à l'autre mais diffère d'un compte à l'autre.

La clé principale utilisée pour identifier un invité dans votre base de données d'analyses WiFi. Utilisez plutôt UnionID si vous gérez plusieurs comptes officiels et avez besoin d'une résolution d'identité multi-comptes.

snsapi_base

Un scope WeChat OAuth qui permet une authentification silencieuse, renvoyant uniquement l'OpenID de l'utilisateur sans afficher de demande de consentement.

À utiliser pour les invités récurrents ou les environnements à haut débit où la vitesse de connexion est la priorité. Ne renvoie aucune donnée démographique au-delà de l'OpenID.

snsapi_userinfo

Un scope WeChat OAuth qui renvoie l'OpenID de l'utilisateur, son pseudo, sa photo de profil, son genre, sa langue et sa ville, nécessitant un écran de consentement explicite de l'utilisateur.

À utiliser pour l'enregistrement initial des invités afin de créer un profil de données de première partie. Doit être associé à une couche de consentement conforme au GDPR et à la PIPL.

PIPL

Personal Information Protection Law. La législation complète de la Chine sur la confidentialité des données, en vigueur depuis novembre 2021, régissant la manière dont les données personnelles des citoyens chinois doivent être collectées, traitées et transférées.

S'applique à tout établissement qui collecte des données auprès de citoyens chinois via WeChat OAuth, quel que soit l'endroit où se trouve l'établissement. Nécessite un consentement explicite, une limitation des finalités et une minimisation des données.

AppSecret

Une clé cryptographique confidentielle émise par WeChat qui authentifie votre application lorsqu'elle appelle l'API d'échange de jetons de WeChat.

Doit être stocké uniquement côté serveur. Une exposition dans le code côté client permet à n'importe qui d'usurper l'identité de votre application et de passer des appels API non autorisés à WeChat.

VLAN

Virtual Local Area Network. Un segment de réseau logique qui isole le trafic au niveau de la couche de liaison de données, permettant à un seul réseau physique de transporter plusieurs flux de trafic isolés.

Utilisé dans les déploiements de Captive Portal pour séparer les appareils non authentifiés (VLAN walled garden) des invités authentifiés (VLAN invité). RADIUS CoA déplace un appareil entre les VLAN lors d'une authentification réussie.

UnionID

Un identifiant WeChat qui reste cohérent pour un utilisateur donné sur tous les comptes officiels et applications web liés au même enregistrement Open Platform.

Indispensable pour les chaînes hôtelières, les groupes de vente au détail et les exploitants multi-sites qui doivent reconnaître le même invité sur plusieurs établissements, chacun ayant son propre compte officiel.

Exemples concrets

Un hôtel de luxe de 200 chambres à Singapour utilise des contrôleurs HPE Aruba et accueille un volume important de voyageurs d'affaires chinois. Ils souhaitent collecter des données démographiques auprès des nouveaux clients et s'assurer que les clients de retour se connectent automatiquement sans voir à nouveau le Captive Portal. Comment doivent-ils configurer l'intégration WeChat OAuth ?

Étape 1 : Enregistrez un compte de service sur la plateforme de comptes officiels WeChat (mp.weixin.qq.com) pour gérer les clients accédant au portail via le navigateur intégré de WeChat. Enregistrez une application de site Web sur la plateforme ouverte WeChat (open.weixin.qq.com) pour les clients utilisant des navigateurs mobiles standard.

Étape 2 : Configurez le Captive Portal pour détecter la chaîne d'agent utilisateur MicroMessenger. Proposez le flux OAuth des comptes officiels pour les utilisateurs du navigateur intégré et le flux de code QR de la plateforme ouverte pour les utilisateurs de navigateurs standard.

Étape 3 : Pour les premières connexions (aucun OpenID existant dans la base de données), demandez le périmètre snsapi_userinfo. Présentez un écran de consentement conforme à la PIPL avant la redirection OAuth. Enregistrez l'OpenID, le pseudo, la ville et le genre renvoyés dans la base de données des profils clients.

Étape 4 : Pour les clients de retour (l'OpenID existe dans la base de données), demandez le périmètre snsapi_base. Cela permet une authentification silencieuse sans invite visible par l'utilisateur.

Étape 5 : Configurez le contrôleur HPE Aruba pour le RADIUS CoA sur le port UDP 3799. Après un OAuth réussi, le serveur du portail envoie une requête CoA pour faire passer l'appareil du VLAN walled garden au VLAN invité.

Étape 6 : Implémentez la journalisation des adresses MAC aux côtés de l'OpenID pour gérer la détection des clients de retour. Notez que la randomisation MAC nécessite l'OpenID comme identifiant principal, et non l'adresse MAC seule.

Commentaire de l'examinateur : Cette approche sépare correctement les deux enregistrements de plateforme selon le contexte d'accès, utilise la sélection de périmètre pour équilibrer la friction et la collecte de données, et implémente RADIUS CoA pour une application réseau sécurisée. L'utilisation de l'OpenID comme identifiant principal pour les clients de retour est la bonne réponse face à la randomisation MAC. La couche de consentement PIPL est non négociable pour les données des citoyens chinois.

L'équipe informatique d'une chaîne de magasins signale un taux d'échec élevé pour les connexions WiFi WeChat dans trois centres commerciaux. Les utilisateurs s'authentifient dans WeChat mais sont redirigés vers la page du portail avec une erreur. Les journaux du portail affichent l'erreur 40029. Quelle est la cause probable et comment la résoudre ?

L'erreur 40029 signifie que WeChat a rejeté le code d'autorisation lors de l'échange de jetons. Les deux causes les plus courantes sont une incompatibilité de l'URI de redirection et la réutilisation du code.

Étape 1 : Connectez-vous à la console développeur WeChat pour la plateforme de comptes officiels et la plateforme ouverte. Accédez aux paramètres OAuth et listez tous les URI de redirection enregistrés.

Étape 2 : Comparez-les avec les URI de redirection réels que votre serveur de portail utilise en production sur les trois sites. Recherchez les différences de sous-domaine (portal.brand.com vs brand.com), de protocole (HTTP vs HTTPS) et de chemin (/callback vs /wechat/callback).

Étape 3 : Enregistrez chaque variante dans la console WeChat. WeChat effectue une validation par correspondance exacte, et non par correspondance de préfixe.

Étape 4 : Si les URI correspondent, vérifiez si votre serveur de portail tente de réutiliser les codes d'autorisation. Les codes WeChat sont à usage unique et expirent après cinq minutes. Si votre serveur réessaie l'échange de jetons avec le même code, il recevra l'erreur 40029 lors de la deuxième tentative.

Étape 5 : Implémentez l'idempotence dans le point de terminaison d'échange de jetons pour éviter les requêtes en double.

Commentaire de l'examinateur : L'erreur 40029 est l'erreur la plus courante dans les déploiements WeChat OAuth et est presque toujours causée par une incompatibilité d'URI de redirection. Les déploiements multi-sites sont particulièrement vulnérables car chaque site peut utiliser un sous-domaine ou une adresse d'équilibreur de charge différents. La cause secondaire, la réutilisation du code, est moins fréquente mais mérite d'être vérifiée si la configuration de l'URI est confirmée comme correcte.

Questions d'entraînement

Q1. Vous déployez un Captive Portal pour un stade d'une capacité de 60 000 personnes accueillant des événements internationaux avec une importante base de fans chinois. La priorité est de connecter tous les participants dans les 15 premières minutes suivant l'ouverture des portes afin de réduire la congestion du réseau cellulaire. La collecte de données marketing est un objectif secondaire. Quel scope WeChat OAuth devez-vous configurer, et pourquoi ?

Conseil : Considérez l'impact d'un écran de consentement affiché à 15 000 utilisateurs simultanés sur un serveur de Captive Portal.

Voir la réponse type

Configurez le scope snsapi_base. Cela permet une authentification silencieuse sans invite de consentement de l'utilisateur, offrant ainsi l'expérience de connexion la plus rapide possible. À l'échelle d'un stade, un écran de consentement ajoute une friction qui se multiplie sur des milliers de connexions simultanées et peut provoquer des pics de charge sur le serveur du Captive Portal. Le scope snsapi_base ne renvoie que l'OpenID, ce qui est suffisant pour enregistrer la session et identifier les fans qui reviennent. Pour les nouveaux fans dont vous souhaitez obtenir des données démographiques, vous pouvez les inviter à remplir leur profil via une enquête post-connexion plutôt qu'au niveau de la barrière d'authentification.

Q2. Un architecte réseau de votre équipe propose de stocker l'AppSecret WeChat dans le JavaScript côté client du Captive Portal afin de réduire les allers-retours avec le serveur en effectuant l'appel d'échange de jetons directement depuis le navigateur. Expliquez pourquoi cette approche constitue une faille de sécurité critique et quelle est l'architecture correcte.

Conseil : Considérez qui peut voir le code côté client et ce que l'AppSecret lui permet de faire.

Voir la réponse type

Le stockage de l'AppSecret dans le JavaScript côté client l'expose à toute personne qui consulte le code source de la page ou intercepte le trafic réseau. L'AppSecret authentifie votre application auprès de l'API de WeChat. Avec celui-ci, un acteur malveillant peut usurper l'identité de votre application, appeler le point de terminaison d'échange de jetons de WeChat avec n'importe quel code d'autorisation valide, récupérer les OpenID et les données de profil des utilisateurs, et potentiellement épuiser vos limites de débit d'API. L'architecture correcte est un point de terminaison d'échange de jetons côté serveur. Le navigateur reçoit le code d'autorisation de WeChat et le transmet à votre serveur. Votre serveur, en utilisant l'AppSecret stocké dans une variable d'environnement ou un gestionnaire de secrets, échange le code contre un jeton et ne renvoie que les données dont le portail a besoin. L'AppSecret ne quitte jamais votre serveur.

Q3. Votre établissement gère trois hôtels dans différentes villes, chacun disposant de son propre compte officiel WeChat. Un membre du programme de fidélité qui s'est authentifié dans les trois établissements possède trois OpenID différents dans votre base de données. Comment résolvez-vous cela en une seule identité de client ?

Conseil : WeChat fournit un mécanisme de résolution d'identité multi-comptes qui nécessite une configuration spécifique de la plateforme.

Voir la réponse type

Implémentez le mécanisme UnionID de WeChat. Associez les trois comptes officiels au même enregistrement Open Platform sur open.weixin.qq.com. Une fois associés, WeChat renvoie un UnionID aux côtés de l'OpenID dans la réponse snsapi_userinfo. L'UnionID est cohérent pour un utilisateur donné sur tous les comptes associés au même enregistrement Open Platform. Migrez votre base de données pour utiliser l'UnionID comme identifiant principal du client pour les enregistrements multi-établissements, tout en conservant l'OpenID par compte pour les appels d'API spécifiques à chaque compte. Pour les clients qui se sont authentifiés avant la mise en œuvre de l'UnionID, déclenchez une réauthentification avec snsapi_userinfo lors de leur prochaine visite pour capturer l'UnionID.

Q4. Après avoir déployé l'authentification WeChat WiFi sur un site de vente au détail équipé de points d'accès Cisco Meraki, les clients signalent qu'ils réussissent la connexion WeChat mais sont renvoyés vers la page du portail et ne peuvent pas naviguer sur Internet. Les journaux du serveur du portail indiquent une récupération réussie du jeton. Quelle est la cause la plus probable et comment la diagnostiquer ?

Conseil : Le portail a vérifié l'identité. Qu'est-ce qui ne s'est pas encore produit ?

Voir la réponse type

Le RADIUS Change of Authorisation (CoA) ne se finalise pas. Le serveur du portail a vérifié l'identité du client via WeChat OAuth mais n'a pas réussi à donner l'instruction au contrôleur Cisco Meraki de déplacer l'appareil du VLAN walled garden vers le VLAN invité. Diagnostiquez en vérifiant : (1) si le contrôleur Meraki a activé le RADIUS CoA et si l'IP du serveur du portail est répertoriée comme un client CoA autorisé ; (2) si le port UDP 3799 est ouvert entre le serveur du portail et le contrôleur ; (3) les journaux du serveur du portail pour détecter des erreurs ou des expirations de requêtes CoA ; et (4) si le secret partagé configuré des deux côtés correspond. Si le CoA n'est pas pris en charge dans votre niveau de licence Meraki, le contournement par adresse MAC est la solution de repli, bien qu'il comporte le risque de randomisation MAC mentionné dans le guide.

Continuer la lecture de cette série

Captive Portal pour Ruijie : configurez-le avec le WiFi invité Purple

Découvrez comment le WiFi invité cloud de Purple se superpose aux points d'accès Ruijie RG Series en utilisant l'authentification web et RADIUS, configuré en ligne de commande, et où trouver les étapes exactes de configuration.

Conception de Captive Portals B2B : Collecter le Nom Enregistré et les Données de l'Entreprise

Ce guide fournit aux responsables informatiques et aux exploitants de sites un cadre technique indépendant des fournisseurs pour concevoir des Captive Portals B2B. Il détaille comment structurer les champs d'inscription pour capturer le nom enregistré et les données de l'entreprise, garantissant des taux de complétion élevés tout en maintenant la conformité GDPR et en développant une intelligence au niveau des comptes.

Architecture de Captive Portal : Sécurité, redirection et bonnes pratiques

Une référence technique définitive sur l'architecture de captive portal d'entreprise. Ce guide détaille l'isolation réseau, la redirection DNS, l'authentification RADIUS et la conformité en matière de sécurité pour les responsables informatiques déployant des réseaux WiFi invités sécurisés et riches en données.