如何为 Captive Portal 配置微信 OAuth 认证

如何为 CAPTIVE PORTAL 配置微信 OAUTH 认证 Purple 技术简报 - 约 10 分钟 --- 引言与背景（约 1 分钟） 欢迎。如果您负责为服务中国游客的酒店、零售连锁店、体育场馆或会议中心提供访客 WiFi，那么本简报正适合您。 根据腾讯 2024 年的数据，微信拥有 13.8 亿月活跃用户。绝大多数用户在中国，但该平台在国际上也拥有不容忽视的影响力——在美国有 400 万用户，在马来西亚有 1200 万用户，并且在东南亚、欧洲和中东地区的用户数量也在不断增长。 当中国访客连接到您的 WiFi 并看到一个仅支持邮箱、Facebook 或凭证码的登录页面时，他们会立即面临阻碍。他们可能没有在该设备上设置本地邮箱地址。但他们几乎肯定拥有微信。因此，问题不在于您是否应该提供微信登录，而在于您如何正确、安全地配置它，并以一种能够生成您实际可用的第一方数据的方式进行配置。 这就是我们今天将要讨论的内容。我们将逐步介绍 OAuth 2.0 流程、您需要的两个平台注册、决定您收集哪些数据的范围（scope）决策、网络端执行机制，以及在 2026 年至关重要的合规性考量。 --- 技术深度解析（约 5 分钟） 让我们从架构开始。Captive Portal 会拦截来自未认证设备的 HTTP 流量，并将其重定向到登录页面。该登录页面托管在 Portal 服务器上（本地部署或云端）。当您添加微信 OAuth 时，您是在该流程中插入了一个第三方身份提供商。 以下是具体步骤。访客连接到您的 SSID。接入点（AP）或无线控制器检测到该设备没有已认证的会话，并将所有 HTTP 流量重定向到您的 Captive Portal URL。Portal 页面加载并呈现登录选项——包括微信。访客点击微信登录。您的 Portal 服务器将浏览器重定向到微信位于 open.weixin.qq.com 的授权端点，并传递您的 AppID、重定向 URI、code 的响应类型以及 scope。 微信完全在其自己的服务器上处理身份验证。如果访客已在浏览器中登录微信，他们会看到一个授权同意屏幕。如果他们使用的是微信内置浏览器，则可以通过 snsapi_base 范围实现无感体验——完全不需要授权同意提示。然后，微信会携带一个临时授权码（code）重定向回您 Portal 的重定向 URI。您的 Portal 服务器通过调用 api.weixin.qq.com/sns/oauth2/access_token，并传递您的 AppID、AppSecret、该 code 以及 authorization_code 的授权类型，来用该 code 交换访问令牌（access token）。微信会返回一个访问令牌、一个刷新令牌、用户的 OpenID 以及授予的 scope。如果您请求了 snsapi_userinfo 范围，则可以进行第二次 API 调用，以获取用户的昵称、头像、性别和城市。 现在，我们来谈谈这两个平台的注册。这也是大多数部署出错的地方。 微信有两个独立的开发者平台。微信开放平台（open.weixin.qq.com）负责网站应用和移动应用。微信公众平台（mp.weixin.qq.com）则负责公众号——这也是大多数场所实际需要的。 对于在微信内置浏览器中为访客提供服务的 Captive Portal，您需要在公众平台上注册一个服务号。订阅号是无法工作的——它没有 OAuth 网页授权权限。而服务号拥有该权限，且同时支持 snsapi_base 和 snsapi_userinfo 作用域。 对于从微信外部的标准移动浏览器（Android 上的 Chrome、iOS 上的 Safari）访问的 Captive Portal，您需要在开放平台上注册一个网站应用。这会使用 snsapi_login 作用域，并向用户展示一个二维码，用户需要使用其微信 App 进行扫码。 在实际应用中，大多数场所部署会同时使用这两者。酒店 WiFi 上的访客可能会在 Chrome 中打开门户，看到二维码，用微信扫码并完成认证。或者，他们可能会直接点击微信内部的链接，进入内置浏览器，并通过 snsapi_base 进行无感认证。 让我们来谈谈作用域的选择，因为这是一个真正的决策点。 snsapi_base 仅返回 OpenID——即该用户在您公众号内的唯一标识符。它不需要用户授权同意。认证过程对用户是完全无感的。这非常适合您已经建立画像的常客，或者您希望以零新数据为代价换取零摩擦体验的场所。 snsapi_userinfo 则会返回 OpenID 以及用户的微信昵称、头像、性别、语言设置和城市。它需要一个明确的授权同意页面。用户会看到一个弹窗，询问是否允许您的公众号访问其信息。大多数用户都会接受，但这也带来了一定的操作摩擦。 正确的选择取决于您的应用场景。对于希望建立用户画像的首次访客注册，请使用 snsapi_userinfo，并在您的门户页面上配合符合 GDPR 规范的同意层。对于已经表示同意且您已拥有其画像的常客，请使用 snsapi_base 进行无感二次认证。 现在，我们来看看网络执行端。获取 OAuth 令牌可以证明身份，但它不会自动打开网络。您需要一种机制来将成功的认证转化为网络访问权限。两种标准方法是 RFC 3576 中定义的 RADIUS 授权变更（CoA）以及 MAC 地址绕过。使用 RADIUS CoA，您的 Captive Portal 服务器在成功进行 OAuth 后向网络控制器发送 CoA 请求，控制器将设备从非受信任 VLAN 移动到访客 VLAN。这适用于 Cisco Meraki、HPE Aruba、Ruckus、Juniper Mist 以及大多数企业级控制器。使用 MAC 绕过，Portal 服务器将设备的 MAC 地址注册为已授权客户端，控制器予以放行。MAC 绕过实现起来更简单，但安全性较低，因为 MAC 地址可以被伪造。 Purple 的 Guest WiFi 平台同时支持这两种机制。在微信 OAuth 完成后，Purple 的云端覆盖层会向底层硬件（无论是 Cisco Meraki、HPE Aruba、Ruckus、Juniper Mist、Ubiquiti UniFi、Cambium、Extreme 还是 Fortinet）发送相应的信号。场所运营商无需手动管理该转换过程。 --- 实施建议与常见陷阱（约 2 分钟） 以下是导致微信 OAuth Captive Portal 实施失败的五个主要原因。 第一：重定向 URI 不匹配。微信会根据您在平台上注册的授权域名来验证重定向 URI。如果您的 Portal 服务器使用不同的子域名、不同的路径或使用 HTTP 而非 HTTPS，OAuth 流程将失败并报错 40029（无效的 code）。请注册您使用的每一个域名变体，包括测试环境。 第二：客户端泄露 AppSecret。您的 AppSecret 绝不能出现在客户端 JavaScript 或移动端 App 二进制文件中。它属于您的服务器。如果泄露，任何人都可以冒充您的应用程序并代表您调用微信的 API。 第三：缺少 CSRF 保护。OAuth 请求中的 state 参数专门用于防止跨站请求伪造。生成一个加密随机的 state 值，将其存储在用户会话中，并在微信重定向回来时进行验证。跳过这一步，您将面临真正的安全漏洞。 第四：应用内浏览器检测缺失。微信的应用内浏览器会设置一个包含 “MicroMessenger” 的特定 User Agent 字符串。如果您的 Portal 未检测到此字符串并提供正确的 OAuth 流程（应用内浏览器使用公众号流程，标准浏览器使用开放平台二维码流程），用户将遇到体验中断或报错。 第五：GDPR 与 PIPL 合规对齐。如果您服务于欧洲访客，GDPR 适用于您通过微信 OAuth 收集的数据。如果您服务于中国访客，中国《个人信息保护法》（PIPL）适用于您处理其数据的方式。两者都要求具备合法的处理依据、明确的目的限制和数据最小化原则。在数据最小化原则下，snsapi_base 比 snsapi_userinfo 更容易证明其合理性。无论您收集什么数据，请记录您的合法依据和保留期限。 --- 快速问答（约 1 分钟） 问题：我可以在同时提供电子邮件和短信登录的门户上使用微信登录吗？ 可以。大多数企业级门户平台（包括 Purple）都支持在同一个门户页面上使用多种身份验证方法。微信将作为与其他选项并列的一个选项出现。 问题：微信 OAuth 在 iOS 上能正常工作吗？ 可以，但有一些细微差别。Apple 的 App Tracking Transparency（应用程序跟踪透明度）框架不会影响服务器端的 OAuth 流程。iOS 上 Safari 浏览器中的微信登录通过二维码流程或重定向流程进行。微信 App 本身会处理该身份验证。 问题：如果微信的 API 不可用会发生什么？ 您的门户应该实施备用方案。如果微信 API 调用超时或返回错误，请将用户重定向到其他登录方法。不要让他们面对空白屏幕。 问题：我可以使用 OpenID 作为持久的客户标识符吗？ 在您的公众号内，可以。对于给定的用户和给定的公众号，OpenID 是稳定的。如果您有多个公众号，同一个用户在这些公众号中将拥有不同的 OpenID。为了进行跨账号的身份识别，微信提供了 UnionID，这需要您在开放平台上绑定您的账号。 --- 总结与后续步骤（约 1 分钟） 总结一下。针对 Captive Portal 的微信 OAuth 身份验证是一个涉及双平台注册、范围决策、网络强制执行集成以及合规性审查的过程。做好这四件事，您就拥有了一种能够为超过十亿潜在访客提供服务且无需输入密码的登录方式。 实际的后续步骤如下。首先，确定您的访客是在微信内置浏览器中还是在标准移动浏览器中打开门户——这决定了您需要进行哪种平台注册。其次，决定范围——snsapi_base 适用于回访宾客，snsapi_userinfo 适用于需要授权的首次注册。第三，确认您的网络硬件支持 RADIUS CoA，或者配置 MAC 绕过作为替代方案。第四，根据 GDPR 和《个人信息保护法》（PIPL）的要求，审查您的隐私声明和同意流程。第五，在上线前测试重定向 URI、state 参数验证以及内置浏览器检测。 如果您想了解 Purple 如何将微信 OAuth 作为更广泛的 Guest WiFi 和分析平台的一部分进行处理（在 2024 年覆盖了 80,000 个场所和 4.4 亿次登录），请访问 purple.ai 或联系您的客户团队。 感谢收听。 --- 脚本结束