How to Configure WeChat OAuth Authentication for Captive Portals

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.38 billion monthly active users, according to Tencent's 2024 data. The overwhelming majority are in China, but the platform has a meaningful international footprint too - four million users in the United States, 12 million in Malaysia, and growing numbers across Southeast Asia, Europe, and the Middle East. 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 at open.weixin.qq.com, 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 snsapi_base scope - 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 api.weixin.qq.com/sns/oauth2/access_token, passing your AppID, AppSecret, the code, and grant type of authorization_code. WeChat returns an access token, a refresh token, the user's OpenID, and the scope granted. If you requested 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 at open.weixin.qq.com handles website applications and mobile apps. The WeChat Official Accounts Platform at mp.weixin.qq.com handles public accounts - 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 snsapi_base and snsapi_userinfo scopes. For a captive portal accessed from a standard mobile browser outside WeChat - Chrome on Android, Safari on iOS - you need a Website Application registered on the Open Platform. This uses 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 on a hotel's WiFi 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. snsapi_base returns only the OpenID - 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. snsapi_userinfo 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, and most enterprise-grade controllers. 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. Purple's Guest WiFi platform handles both mechanisms. After WeChat OAuth completes, Purple's cloud overlay sends the appropriate signal to the underlying hardware - whether that is Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme, or Fortinet. 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 - 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 - Official Account flow for in-app browser, Open Platform QR flow for standard browsers - 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 - PIPL - applies to how you process their data. Both require a lawful basis for processing, clear purpose limitation, and data minimisation. snsapi_base 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 - 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