Integrating WeChat WiFi Authentication: Captive Portal Onboarding for APAC Customers

WeChat has 1.41 billion monthly active users, making it the primary digital identity for Chinese consumers globally. This guide explains how to integrate WeChat OAuth 2.0 authentication into enterprise captive portals for APAC venues, covering platform registration, scope selection, RADIUS Change of Authorisation enforcement, and dual-framework compliance with GDPR and China's PIPL. It is aimed at IT managers, network architects, and venue operations directors who need to act this quarter.

📖 9 min read📝 2,130 words🔧 2 worked examples❓ 4 practice questions📚 10 key definitions

Listen to this guide

View podcast transcript

HOW TO CONFIGURE WECHAT OAUTH AUTHENTICATION FOR CAPTIVE PORTALS
A Purple Technical Briefing - Approximately 10 Minutes

INTRODUCTION AND CONTEXT (approximately 1 minute)

Welcome. If you are responsible for guest WiFi at a hotel, retail chain, stadium, or conference centre that serves Chinese visitors, this briefing is for you.

WeChat has 1.41 billion monthly active users as of 2025, according to Tencent's own data. The overwhelming majority are in China, but the platform has a meaningful international footprint too. Malaysia has 12 million WeChat users. Japan has 5.5 million. South Korea, 5 million. And the numbers are growing across Southeast Asia, the Middle East, and Europe.

When a Chinese guest connects to your WiFi and sees a login page with only email, Facebook, or a voucher code, they face immediate friction. They may not have a local email address set up on that device. They almost certainly have WeChat. So the question is not whether you should offer WeChat login. It is how you configure it correctly, securely, and in a way that generates first-party data you can actually use.

That is what we are going to cover today. We will walk through the OAuth 2.0 flow, the two platform registrations you need, the scope decision that determines what data you collect, the network-side enforcement mechanism, and the compliance considerations that matter in 2026.

TECHNICAL DEEP-DIVE (approximately 5 minutes)

Let us start with the architecture. A captive portal intercepts HTTP traffic from an unauthenticated device and redirects it to a login page. That login page is hosted on a portal server, either on-premises or in the cloud. When you add WeChat OAuth, you are inserting a third-party identity provider into that flow.

Here is the sequence. The guest connects to your SSID. The access point or wireless controller detects that the device has no authenticated session and redirects all HTTP traffic to your captive portal URL. The portal page loads and presents login options, including WeChat. The guest taps WeChat login. Your portal server redirects the browser to WeChat's authorisation endpoint, passing your AppID, the redirect URI, the response type of code, and the scope.

WeChat handles the authentication entirely on its own servers. If the guest is already logged into WeChat in their browser, they see a consent screen. If they are using the WeChat in-app browser, the experience can be silent with the snsapi base scope, meaning no consent prompt at all. WeChat then redirects back to your portal's redirect URI with a temporary authorisation code. Your portal server exchanges that code for an access token by calling the WeChat API. WeChat returns an access token, a refresh token, the user's OpenID, and the scope granted. If you requested the snsapi userinfo scope, you can then make a second API call to retrieve the user's nickname, avatar, gender, and city.

Now, the two platform registrations. This is where most implementations go wrong.

WeChat has two separate developer platforms. The WeChat Open Platform handles website applications and mobile apps. The WeChat Official Accounts Platform handles public accounts, which is what most venues actually need.

For a captive portal serving guests inside the WeChat in-app browser, you need a Service Account on the Official Accounts Platform. A Subscription Account will not work. It does not have OAuth web page authorisation permissions. A Service Account does, and it supports both the snsapi base and snsapi userinfo scopes.

For a captive portal accessed from a standard mobile browser outside WeChat, such as Chrome on Android or Safari on iOS, you need a Website Application registered on the Open Platform. This uses the snsapi login scope and presents a QR code that the user scans with their WeChat app.

In practice, most venue deployments use both. A guest at a hotel might open the portal in Chrome, see a QR code, scan it with WeChat, and authenticate. Or they might follow a link in WeChat itself, land in the in-app browser, and authenticate silently with snsapi base.

Let us talk about scope selection, because this is a genuine decision point.

The snsapi base scope returns only the OpenID. This is a unique identifier for that user within your Official Account. It requires no user consent prompt. The authentication is invisible to the user. This is ideal for returning guests you have already profiled, or for venues where you want zero friction at the cost of zero new data.

The snsapi userinfo scope returns the OpenID plus the user's WeChat nickname, profile picture, gender, language setting, and city. It requires an explicit consent screen. The user sees a prompt asking whether they allow your Official Account to access their information. Most users accept, but there is friction.

The right choice depends on your use case. For a first-time guest registration where you want to build a profile, use snsapi userinfo and pair it with a GDPR-compliant consent layer on your portal page. For a returning guest who has already consented and whose profile you already hold, use snsapi base for silent re-authentication.

Now, the network enforcement side. Getting an OAuth token proves identity, but it does not automatically open the network. You need a mechanism to translate a successful authentication into network access.

The two standard approaches are RADIUS Change of Authorisation, defined in RFC 3576, and MAC address bypass. With RADIUS CoA, your portal server sends a CoA request to the network controller after successful OAuth, and the controller moves the device from the unauthenticated VLAN to the guest VLAN. This works with Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme, and Fortinet.

With MAC bypass, the portal server registers the device's MAC address as an authorised client, and the controller allows it. MAC bypass is simpler to implement but less secure, because MAC addresses can be spoofed, and modern smartphones increasingly use MAC address randomisation, which breaks the mechanism on reconnection.

Purple's Guest WiFi platform handles both mechanisms. After WeChat OAuth completes, Purple's cloud overlay sends the appropriate signal to the underlying hardware. The venue operator does not need to manage that translation manually.

IMPLEMENTATION RECOMMENDATIONS AND PITFALLS (approximately 2 minutes)

Let me give you the five things that cause WeChat OAuth captive portal implementations to fail.

First: the redirect URI mismatch. WeChat validates the redirect URI against the authorised domain you registered on the platform. If your portal server uses a different subdomain, a different path, or HTTP instead of HTTPS, the OAuth flow fails with error 40029, which means invalid code. Register every domain variant you use, including staging environments.

Second: the AppSecret on the client side. Your AppSecret must never appear in client-side JavaScript or in a mobile app binary. It belongs on your server. If it is exposed, anyone can impersonate your application and call WeChat's APIs on your behalf.

Third: missing CSRF protection. The state parameter in the OAuth request exists specifically to prevent cross-site request forgery. Generate a cryptographically random state value, store it in the user's session, and validate it when WeChat redirects back. Skip this and you have a real vulnerability.

Fourth: the in-app browser detection gap. WeChat's in-app browser sets a specific user agent string containing MicroMessenger. If your portal does not detect this and serve the correct OAuth flow, users get a broken experience or an error.

Fifth: GDPR and PIPL alignment. If you serve European visitors, GDPR applies to the data you collect via WeChat OAuth. If you serve Chinese visitors, China's Personal Information Protection Law, known as PIPL, applies to how you process their data. Both require a lawful basis for processing, clear purpose limitation, and data minimisation. The snsapi base scope is easier to justify under data minimisation principles than snsapi userinfo. Whatever you collect, document your legal basis and your retention period.

RAPID-FIRE Q AND A (approximately 1 minute)

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. Use snsapi base for returning guests, and 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.

Key Takeaways

✓WeChat has 1.41 billion monthly active users (Tencent, 2025), making it the primary digital identity for Chinese consumers. Venues serving APAC guests cannot afford to omit it from their captive portal login options.
✓Two platform registrations are required: a Service Account on the Official Accounts Platform for in-app browser access, and a Website Application on the Open Platform for standard browser access. Using the wrong registration type is the most common implementation failure.
✓Scope selection is a genuine architectural decision. Use snsapi_base for silent, zero-friction authentication that returns only an OpenID. Use snsapi_userinfo to collect demographic data, accepting the friction of a consent screen.
✓OAuth proves identity but does not open the network. RADIUS Change of Authorisation (RFC 3576) is the mechanism that translates a successful token exchange into VLAN promotion. Without it, authenticated guests remain blocked.
✓The AppSecret must be stored server-side only. Exposure in client-side code allows impersonation of your application and unauthorised access to WeChat's API.
✓GDPR and PIPL both apply to data collected via WeChat OAuth. Document your legal basis, implement data minimisation, and ensure your consent layer is compliant before going live.
✓For multi-property deployments, implement WeChat's UnionID from the start. OpenIDs differ per Official Account; UnionID provides a consistent guest identity across all linked accounts.

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.

Key Definitions

Captive portal

A web-based authentication gateway that intercepts HTTP traffic from an unauthenticated device and redirects it to a login page before granting network access.

The mechanism through which guest WiFi authentication is presented to users. WeChat OAuth is one of several authentication methods a captive portal can offer.

OAuth 2.0

An industry-standard authorisation protocol that allows a third-party application (the captive portal) to obtain limited access to a web service (WeChat) on behalf of a user, without the user sharing their password with the third party.

The underlying framework that makes WeChat login possible. The portal never sees the user's WeChat credentials; it only receives a token confirming that WeChat has authenticated them.

RADIUS CoA

Change of Authorisation. A mechanism defined in RFC 3576 that allows a RADIUS server to dynamically modify the session authorisation attributes of an active network client, such as changing VLAN assignment.

The network enforcement mechanism that translates a successful WeChat OAuth exchange into actual network access. Without CoA, the guest authenticates but the controller does not know to open the network.

OpenID

A unique identifier assigned by WeChat to a specific user for a specific Official Account or Website Application. It is stable across sessions but differs across accounts.

The primary key used to identify a guest in your WiFi analytics database. Use UnionID instead if you operate multiple Official Accounts and need cross-account identity resolution.

snsapi_base

A WeChat OAuth scope that enables silent authentication, returning only the user's OpenID without displaying a consent prompt.

Use for returning guests or high-throughput environments where connection speed is the priority. Returns no demographic data beyond the OpenID.

snsapi_userinfo

A WeChat OAuth scope that returns the user's OpenID, nickname, profile image, gender, language, and city, requiring an explicit user consent screen.

Use for first-time guest registration to build a first-party data profile. Must be paired with a GDPR and PIPL-compliant consent layer.

PIPL

Personal Information Protection Law. China's comprehensive data privacy legislation, in force since November 2021, governing how personal data of Chinese citizens must be collected, processed, and transferred.

Applies to any venue that collects data from Chinese citizens via WeChat OAuth, regardless of where the venue is located. Requires explicit consent, purpose limitation, and data minimisation.

AppSecret

A confidential cryptographic key issued by WeChat that authenticates your application when it calls WeChat's token exchange API.

Must be stored on the server side only. Exposure in client-side code allows any party to impersonate your application and make unauthorised API calls to WeChat.

VLAN

Virtual Local Area Network. A logical network segment that isolates traffic at the data link layer, allowing a single physical network to carry multiple isolated traffic streams.

Used in captive portal deployments to separate unauthenticated devices (walled garden VLAN) from authenticated guests (guest VLAN). RADIUS CoA moves a device between VLANs upon successful authentication.

UnionID

A WeChat identifier that remains consistent for a given user across all Official Accounts and Website Applications linked to the same Open Platform registration.

Essential for hotel chains, retail groups, and multi-venue operators who need to recognise the same guest across multiple properties, each with its own Official Account.

Worked Examples

A 200-room luxury hotel in Singapore uses HPE Aruba controllers and serves a high volume of Chinese business travellers. They want to collect demographic data from first-time guests and ensure returning guests connect automatically without seeing the portal again. How should they configure the WeChat OAuth integration?

Step 1: Register a Service Account on the WeChat Official Accounts Platform (mp.weixin.qq.com) to handle guests accessing the portal inside the WeChat in-app browser. Register a Website Application on the WeChat Open Platform (open.weixin.qq.com) for guests on standard mobile browsers.

Step 2: Configure the captive portal to detect the MicroMessenger user agent string. Serve the Official Accounts OAuth flow for in-app browser users and the Open Platform QR code flow for standard browser users.

Step 3: For first-time connections (no existing OpenID in the database), request snsapi_userinfo scope. Present a PIPL-compliant consent screen before the OAuth redirect. Store the returned OpenID, nickname, city, and gender in the guest profile database.

Step 4: For returning guests (OpenID exists in the database), request snsapi_base scope. This authenticates silently with no user-visible prompt.

Step 5: Configure the HPE Aruba controller for RADIUS CoA on UDP port 3799. After successful OAuth, the portal server sends a CoA request to promote the device from the walled garden VLAN to the guest VLAN.

Step 6: Implement MAC address logging alongside OpenID to handle the returning guest detection. Note that MAC randomisation requires OpenID as the primary identifier, not MAC address alone.

Examiner's Commentary: This approach correctly separates the two platform registrations by access context, uses scope selection to balance friction against data collection, and implements RADIUS CoA for secure network enforcement. The use of OpenID as the primary returning-guest identifier is the correct response to MAC randomisation. The PIPL consent layer is non-negotiable for Chinese citizen data.

A retail chain's IT team reports a high failure rate for WeChat WiFi logins across three mall locations. Users authenticate in WeChat but are returned to the portal page with an error. The portal logs show error 40029. What is the likely cause and how do you resolve it?

Error 40029 means WeChat rejected the authorisation code during the token exchange. The two most common causes are a redirect URI mismatch and code reuse.

Step 1: Log into the WeChat developer console for both the Official Accounts Platform and the Open Platform. Navigate to the OAuth settings and list all registered redirect URIs.

Step 2: Compare these against the actual redirect URIs your portal server uses in production across all three locations. Check for subdomain differences (portal.brand.com vs brand.com), protocol differences (HTTP vs HTTPS), and path differences (/callback vs /wechat/callback).

Step 3: Register every variant in the WeChat console. WeChat performs exact-match validation, not prefix matching.

Step 4: If the URIs match, investigate whether your portal server is attempting to reuse authorisation codes. WeChat codes are single-use and expire after five minutes. If your server retries the token exchange with the same code, it will receive 40029 on the second attempt.

Step 5: Implement idempotency in the token exchange endpoint to prevent duplicate requests.

Examiner's Commentary: Error 40029 is the most common error in WeChat OAuth deployments and is almost always caused by a redirect URI mismatch. Multi-location deployments are particularly vulnerable because each location may use a different subdomain or load balancer address. The secondary cause, code reuse, is less common but worth checking if URI registration is confirmed correct.

Practice Questions

Q1. You are deploying a captive portal for a 60,000-capacity stadium hosting international events with a significant Chinese fan base. The priority is getting all attendees online within the first 15 minutes of doors opening to reduce cellular congestion. Marketing data collection is a secondary objective. Which WeChat OAuth scope should you configure, and why?

Hint: Consider the impact of a consent screen displayed to 15,000 simultaneous users on a portal server.

View model answer

Configure snsapi_base scope. This enables silent authentication with no user consent prompt, providing the fastest possible onboarding experience. At stadium scale, a consent screen adds friction that multiplies across thousands of simultaneous connections and can cause portal server load spikes. snsapi_base returns only the OpenID, which is sufficient to log the session and identify returning fans. For first-time fans where you want demographic data, you can prompt for profile completion via a post-connection survey rather than at the authentication gate.

Q2. A network architect on your team proposes storing the WeChat AppSecret in the captive portal's client-side JavaScript to reduce server round-trips by making the token exchange call directly from the browser. Explain why this approach is a critical security failure and what the correct architecture is.

Hint: Consider who can view client-side code and what the AppSecret allows them to do.

View model answer

Storing the AppSecret in client-side JavaScript exposes it to any person who views the page source or intercepts network traffic. The AppSecret authenticates your application to WeChat's API. With it, a malicious actor can impersonate your application, call WeChat's token exchange endpoint with any valid authorisation code, retrieve user OpenIDs and profile data, and potentially exhaust your API rate limits. The correct architecture is a server-side token exchange endpoint. The browser receives the authorisation code from WeChat and passes it to your server. Your server, using the AppSecret stored in an environment variable or secrets manager, exchanges the code for a token and returns only the data the portal needs. The AppSecret never leaves your server.

Q3. Your venue operates three hotel properties in different cities, each with its own WeChat Official Account. A loyalty programme member who has authenticated at all three properties has three different OpenIDs in your database. How do you resolve this into a single guest identity?

Hint: WeChat provides a mechanism for cross-account identity resolution that requires a specific platform configuration.

View model answer

Implement WeChat's UnionID mechanism. Link all three Official Accounts to the same Open Platform registration at open.weixin.qq.com. Once linked, WeChat returns a UnionID alongside the OpenID in the snsapi_userinfo response. The UnionID is consistent for a given user across all accounts linked to the same Open Platform registration. Migrate your database to use UnionID as the primary guest identifier for cross-property records, retaining the per-account OpenID for account-specific API calls. For guests who authenticated before UnionID was implemented, trigger a re-authentication with snsapi_userinfo at their next visit to capture the UnionID.

Q4. After deploying WeChat WiFi authentication at a retail venue running Cisco Meraki access points, guests report that they complete the WeChat login successfully but are returned to the portal page and cannot browse the internet. The portal server logs show successful token retrieval. What is the most likely cause and how do you diagnose it?

Hint: The portal has verified identity. What has not happened yet?

View model answer

The RADIUS Change of Authorisation (CoA) is not completing. The portal server has verified the guest's identity via WeChat OAuth but has not successfully instructed the Cisco Meraki controller to move the device from the walled garden VLAN to the guest VLAN. Diagnose by checking: (1) whether the Meraki controller has RADIUS CoA enabled and the portal server's IP is listed as an authorised CoA client; (2) whether UDP port 3799 is open between the portal server and the controller; (3) the portal server logs for CoA request errors or timeouts; and (4) whether the shared secret configured on both sides matches. If CoA is not supported in your Meraki licence tier, MAC address bypass is the fallback, though it carries the MAC randomisation risk noted in the guide.

Continue reading in this series

Configurando Redireccionamiento de Portal Cautivo en Controladores de Red Enterprise

This authoritative guide details the technical architecture and vendor-specific configuration steps required to implement captive portal redirection on enterprise network controllers. It provides actionable guidance for IT teams on configuring walled gardens, integrating RADIUS authentication, and ensuring compliance with GDPR and PCI DSS.

Configuring Captive Portal Redirection on Enterprise Network Controllers

Step-by-Step Guide: Configuring Ruijie Wireless Controllers for Guest WiFi Captive Portals

This guide provides a complete technical walkthrough for configuring Ruijie wireless controllers and gateways to deploy enterprise-grade guest WiFi captive portals. It covers VLAN segmentation, external RADIUS authentication via WISPr protocol, walled garden configuration, and seamless integration with Purple's Identity-Based Networks platform to capture first-party data and drive measurable business value across hospitality, retail, and public-sector environments.