跳至主要内容

集成微信 WiFi 认证:面向亚太地区客户的 Captive Portal 引导流程

微信拥有 14.1 亿月活跃用户,是全球中国消费者的主要数字身份。本指南介绍了如何将微信 OAuth 2.0 认证集成到亚太地区场所的企业级 Captive Portal 中,涵盖平台注册、范围选择、RADIUS 授权变更(CoA)强制执行,以及符合 GDPR 和中国《个人信息保护法》(PIPL)的双重框架合规性。本指南旨在为需要在本季度采取行动的 IT 经理、网络架构师和场所运营总监提供指导。

📖 9 分钟阅读📝 2,130 🔧 2 应用实例4 练习题📚 10 关键定义

收听本指南

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

header_image.png

执行摘要

对于在亚太地区运营或在全球范围内服务中国游客的企业场所而言,微信 WiFi 认证已不再是可选项。截至 2025 年,微信的月活跃用户数已达 14.1 亿(数据来源:腾讯),是中国消费者最主要的数字身份标识。如果访客连接到您的 SSID,却只看到电子邮件或 Facebook 登录选项,会立即产生体验阻碍。他们几乎肯定拥有微信,但几乎肯定没有在该设备上配置本地电子邮件地址。

本指南详细介绍了如何将微信 OAuth 2.0 集成到 Captive Portal 中。我们涵盖了腾讯要求的两种不同的平台注册、决定您收集哪些第一方数据的范围(scope)决策,以及将成功的 OAuth 交换转化为实际网络访问的 RADIUS 授权变更(CoA)机制。我们还探讨了 GDPR 与中国《个人信息保护法》(PIPL)重叠的合规性要求。

Purple 的 Guest WiFi 平台可在 Cisco Meraki、HPE Aruba、Ruckus、Juniper Mist、Ubiquiti UniFi、Cambium、Extreme 和 Fortinet 硬件上实现网络执行层的自动化。Purple 在全球 80,000 多个活跃场所运营,并在 2024 年记录了 4.4 亿次登录(Purple 内部数据)。

技术深度解析

OAuth 2.0 流程

Captive Portal(一种基于 Web 的认证网关,用于拦截来自未认证设备的 HTTP 流量)将访客重定向到托管在门户服务器(本地或云端)上的登录页面。加入微信 OAuth 会将腾讯的身份基础设施嵌入到该流程中。

具体步骤如下:访客关联到 SSID。无线控制器检测到不存在已认证的会话,并将所有 HTTP 流量重定向到 Captive Portal URL。门户页面加载并呈现登录选项(包括微信)。访客选择微信。门户服务器构建一个重定向到微信授权端点 open.weixin.qq.com 的请求,并传递四个参数:AppID、重定向 URI、设置为 code 的响应类型以及所请求的 scope。

WeChat 完全在其自身的基础设施上对用户进行身份验证。如果访客已经通过 WeChat 应用内浏览器登录,snsapi_base 作用域允许进行静默身份验证,而无需任何可见的提示。WeChat 会重定向回 Portal 注册的重定向 URI,并附带一个短期授权码。Portal 服务器通过使用 AppID、AppSecret、code 和 grant type 调用 api.weixin.qq.com/sns/oauth2/access_token 来用此代码交换访问令牌。WeChat 会返回一个访问令牌、一个刷新令牌、用户的 OpenID 以及授予的作用域。如果请求了 snsapi_userinfo,则对 api.weixin.qq.com/sns/userinfo 进行第二次 API 调用,以获取用户的昵称、头像、性别和城市。

architecture_overview.png

平台注册:导致大多数部署失败的决定

腾讯运营着两个独立的开发者平台,选择错误的平台是导致实施失败最常见的原因。

访问场景 所需注册 平台 URL 支持的作用域
WeChat 应用内浏览器 服务号 (公众平台) mp.weixin.qq.com snsapi_base, snsapi_userinfo
标准移动浏览器 (Chrome, Safari) 网站应用 (开放平台) open.weixin.qq.com snsapi_login (二维码流程)

公众平台上的订阅号将无法工作。它缺少 OAuth 网页授权权限。只有服务号才拥有这些权限。

酒店零售 行业的大多数企业部署都会同时实施这两种注册。酒店的访客可能会在 Chrome 中打开 Portal,用 WeChat 扫描二维码,然后通过开放平台流程进行身份验证。或者,他们可能会点击 WeChat 内部的链接,进入应用内浏览器,并通过公众平台流程进行静默身份验证。这两种路径都必须进行处理。

作用域选择与数据收集

OAuth 作用域是一个真正的架构决策,而不是一个配置细节。它决定了用户体验到的阻力以及您的 WiFi Analytics 平台接收的数据。

snsapi_base 仅返回 OpenID - 该用户在您的服务号内的唯一且稳定的标识符。它不需要用户授权提示。身份验证是无感的。对于您已拥有其个人资料的返店访客,或者对于体育场馆和交通枢纽等以连接速度为首要任务的高吞吐量环境,请使用此选项。

snsapi_userinfo 返回 OpenID 以及昵称、头像、性别、语言设置和城市。它会触发一个显式的授权同意屏幕。在首次访客注册时使用此选项以构建第一方数据画像,并在 Captive Portal 页面上配合符合 PIPL 和 GDPR 规范的同意层。

实际规则:追求速度使用 snsapi_base,追求数据使用 snsapi_userinfo。您可以通过检查用户的 OpenID 是否已存在于您的数据库中来同时实现这两者。如果已存在,则请求 snsapi_base;如果不存在,则请求 snsapi_userinfo

网络执行:RADIUS CoA 和 MAC 绕过

OAuth 令牌仅用于证明身份,并不能打开网络。必须通过一个独立的机制将成功的身份验证转化为网络策略的变更。

RADIUS 授权变更 (CoA)(在 RFC 3576 中定义)是标准方法。在 Captive Portal 服务器收到有效的 OAuth 令牌后,它会向无线控制器发送一个 CoA 请求。控制器随后更新会话,将设备从围墙花园 VLAN(仅允许 Captive Portal 流量的受限网络段)移动到完整的访客 VLAN。这适用于 Cisco Meraki、HPE Aruba、Ruckus、Juniper Mist、Ubiquiti UniFi、Cambium、Extreme 和 Fortinet。

MAC 地址绕过在 OAuth 成功后将设备的 MAC 地址注册为已授权客户端。随后,控制器允许来自该地址的流量,而无需进一步质询。这种方法实现起来更简单,但存在两个风险:MAC 地址可能会被伪造,且自 iOS 14 和 Android 10 起,默认使用随机 MAC 地址,这会在重新连接时破坏该机制。

对于任何注重安全性的部署,RADIUS CoA 都是正确的选择。有关保护访客网络的更多信息,请参阅 什么是安全 WiFi:2026 商业基本指南企业 WiFi 安全:2026 完整指南

实施指南

部署前清单

在编写任何配置代码之前,请完成以下五个步骤。

第一,确定访问场景。调查您的场所,确认访客是在微信内置浏览器内、在标准移动浏览器中,还是在两者中遇到 Captive Portal。答案将决定您的平台注册要求。

第二,在正确的平台上注册。对于内置浏览器访问,请在微信公众平台创建服务号。对于标准浏览器访问,请在微信开放平台注册网站应用。记录下各自的 AppID 和 AppSecret。

第三,配置您的重定向 URI。注册您的 Captive Portal 使用的每一个域名和子域名,包括测试环境。微信执行精确匹配验证,不匹配将返回错误 40029。

第四,实现服务端令牌交换。AppSecret 绝不能出现在客户端代码中。构建一个服务端接口,接收授权码,将其交换为令牌,并仅返回您的 Captive Portal 所需的数据。

第五,实现用于 CSRF 防护的 state 参数。生成一个加密随机值,将其存储在用户会话中,在 OAuth 请求中传递它,并在返回时进行验证。

Ruckus SmartZone 的配置步骤

对于运行 Ruckus SmartZone 的场所,WeChat 门户配置位于“服务和配置文件”(Services and Profiles),然后是“热点和门户”(Hotspots and Portals),最后是 WeChat 选项卡。您需要配置认证 URL(您的门户服务器的 WeChat 回调端点)、DNAT 目的地(处理未认证客户端重定向的服务器)以及宽限期(最近断开连接的用户在无需重新认证的情况下可以重新连接的时间窗口,默认为 60 分钟)。您还需要配置围墙花园(walled garden)白名单,以允许在认证阶段访问 WeChat 的 API 端点。另请参阅 逐步指南:为访客 WiFi Captive Portals 配置锐捷无线控制器 以了解类似的控制器配置模式。

应用内浏览器检测

WeChat 的应用内浏览器会设置包含 MicroMessenger 的用户代理(user agent)字符串。您的门户必须检测此字符串并提供相应的 OAuth 流程。如果存在 MicroMessenger,请使用公众号(Official Accounts)流程。如果不存在,请使用开放平台二维码流程。未能正确检测会导致体验中断或认证错误。

最佳实践

数据最小化与双重框架合规性

GDPR(适用于欧洲访客)和 PIPL(适用于中国公民)都要求处理个人数据具有合法依据、明确的目的限制和数据最小化。在数据最小化原则下,snsapi_base 范围比 snsapi_userinfo 更容易证明其合理性。当您确实通过 snsapi_userinfo 收集人口统计数据时,请记录您的法律依据、保留期限以及与腾讯的数据处理协议。

自 2021 年 11 月起实施的 PIPL 要求对敏感个人信息获得明确同意,并要求中国境外的个人信息处理者实施同等的保护标准。如果您的门户服务器位于中国大陆境外,您必须评估跨境数据传输规则是否适用于您接收的 WeChat OpenID 和个人资料数据。

适用于多物业部署的 UnionID

每个用户在每个公众号中的 OpenID 都是唯一的。如果您在不同的物业运营多个公众号,同一位访客在每个公众号中将拥有不同的 OpenID。WeChat 提供了一个 UnionID,该 ID 在链接到同一个开放平台注册的所有账号中保持一致。对于管理多个场所的连锁酒店、零售集团或机场运营商,请从一开始就实施基于 UnionID 的身份解析。

安全加固

将 AppSecret 存储在环境变量或机密管理器中,切勿写入源代码。如果怀疑泄露,请立即进行轮换。在您的令牌交换端点上实施速率限制以防止滥用。记录所有 OAuth 错误,特别是 40029(无效代码)和 40163(代码已过期),因为这些错误表明配置错误或存在主动探测。

有关访客网络安全架构的更广泛视图,请参阅 为什么消费级 WiFi 设备不属于您的访客网络

案例研究

新加坡豪华连锁酒店

新加坡一家拥有 350 间客房的豪华酒店,主要服务于中国商务旅行客群。该酒店在现有的电子邮件登录选项之外,实施了微信 WiFi 认证。在实施之前,前台员工报告平均每天有 15 起关于 WiFi 登录困难的访客投诉。中国游客当时正试图使用他们未在旅行设备上配置的电子邮件地址进行登录。

该酒店在微信公众平台注册了服务号,并在开放平台注册了网站应用。他们为首次连接的访客配置了 snsapi_userinfo,为通过 MAC 地址识别的再次光临访客配置了 snsapi_base。HPE Aruba 控制器配置了 RADIUS CoA 以处理会话提升。

在 30 天内,访客 WiFi 登录投诉降至每天两起以下。该酒店的 WiFi Analytics 数据库在第一个月增加了 4,200 个经过验证的第一方个人资料,城市级别的受众特征数据使针对性的离店后沟通成为可能。

吉隆坡国际购物中心

吉隆坡的一家高端购物中心,仅在马来西亚就拥有 1200 万微信用户,需要一种与其购物者群体的数字化期望相匹配的 WiFi 接入体验。该商场在 180,000 平方米的零售区域内运营着 Cisco Meraki 接入点。

该部署使用 Purple 的 Guest WiFi 平台作为云端覆盖,以微信 OAuth 作为主要认证方式,并以短信 OTP 作为备用方案。Purple 的硬件无关架构处理了与 Cisco Meraki 的 RADIUS CoA 集成,无需进行定制开发。

该商场在部署后的第一季度记录了 WiFi 会话启动次数增长了 34%,这归功于微信用户接入摩擦的减少。通过 snsapi_userinfo 同意流程收集的第一方数据使商场的营销团队能够按常住城市对购物者进行细分,以进行精准的营销活动推送。

retail_venue_wechat_wifi.png

故障排除与风险缓解

错误 原因 解决方案
40029 invalid code 重定向 URI 不匹配或代码重复使用 验证注册的 URI 是否完全匹配;代码为一次性使用
40163 code expired Token交换延迟超过5分钟 缩短服务器端处理时间;实现重试逻辑
认证后出现白屏 RADIUS CoA未配置或失败 检查控制器CoA设置以及UDP端口3799上的防火墙规则
MAC随机化破坏了回访访客流程 iOS/Android MAC随机化 迁移至基于OpenID的会话跟踪;避免仅使用MAC进行识别
snsapi_userinfo返回空字段 用户设置了微信隐私限制 妥善处理空字段;不要强制要求获取个人资料数据才能访问

ROI与业务影响

微信WiFi认证的商业案例建立在三个可衡量的成果之上。

第一方数据获取。每次snsapi_userinfo认证都会生成一个包含人口统计数据的已验证访客档案。对于一家拥有200间客房、入住率为70%且其中40%为中国客人的酒店而言,这意味着每年可新增约20,000个已验证的档案,每个档案都与支持持续重新互动的微信身份绑定。

减轻支持负担。登录摩擦是导致访客WiFi支持电话的主要原因。在现有选项之外增加微信认证的场所,其与WiFi相关的服务台咨询量持续减少,从而为员工腾出时间进行更高价值的互动。

营销触达。微信公众号允许场所向粉丝推送通知。通过您的公众号进行认证的访客可以被引导关注该账号,从而在微信生态系统内建立直接的沟通渠道,而中国消费者平均每天在微信上花费82分钟(来源:Walk the Chat)。

Purple的Engage计划进一步扩展了这一功能,能够基于在WiFi认证时收集的第一方数据,实现自动化的访问后消息推送、会员触发机制以及细分营销活动。

关键定义

Captive Portal

一种基于 Web 的身份验证网关,它拦截来自未身份验证设备的 HTTP 流量,并在授予网络访问权限之前将其重定向到登录页面。

向用户展示访客 WiFi 身份验证的机制。微信 OAuth 是 Captive Portal 可以提供的几种身份验证方法之一。

OAuth 2.0

一种行业标准的授权协议,允许第三方应用程序(Captive Portal)代表用户获得对 Web 服务(微信)的有限访问权限,而无需用户与第三方共享其密码。

使微信登录成为可能的基础框架。Portal 永远不会看到用户的微信凭据;它只接收一个确认微信已对其进行身份验证的令牌。

RADIUS CoA

授权变更(Change of Authorisation)。RFC 3576 中定义的一种机制,允许 RADIUS 服务器动态修改活动网络客户端的会话授权属性,例如更改 VLAN 分配。

将成功的微信 OAuth 交换转化为实际网络访问的网络执行机制。如果没有 CoA,访客虽然通过了身份验证,但控制器不知道要开放网络。

OpenID

微信分配给特定公众号或网站应用的特定用户的唯一标识符。它在不同会话之间保持稳定,但在不同账号之间有所不同。

用于在您的 WiFi 分析数据库中识别访客的主键。如果您运营多个公众号并需要跨账号身份解析,请改用 UnionID。

snsapi_base

一种微信 OAuth 作用域,可实现静默身份验证,仅返回用户的 OpenID,而不显示同意提示。

适用于回头客或以连接速度为首要任务的高吞吐量环境。除了 OpenID 之外,不返回任何人口统计数据。

snsapi_userinfo

一种微信 OAuth 作用域,返回用户的 OpenID、昵称、头像、性别、语言和城市,需要显式的用户同意界面。

用于首次访客注册以构建第一方数据画像。必须与符合 GDPR 和 PIPL 要求的同意层配合使用。

PIPL

《个人信息保护法》。中国自 2021 年 11 月起实施的全面数据隐私立法,旨在规范中国公民个人信息的收集、处理和传输方式。

适用于通过微信 OAuth 收集中国公民数据的任何场所,无论该场所位于何处。需要明确的同意、目的限制和数据最小化。

AppSecret

微信颁发的机密加密密钥,用于在您的应用程序调用微信的令牌交换 API 时对其进行身份验证。

必须仅存储在服务器端。在客户端代码中泄露会导致任何第三方都可以冒充您的应用程序,并向微信发起未经授权的 API 调用。

VLAN

虚拟局域网(Virtual Local Area Network)。在数据链路层隔离流量的逻辑网络段,允许单个物理网络承载多个隔离的流量流。

在 Captive Portal 部署中用于将未身份验证的设备(围墙花园 VLAN)与已身份验证的访客(访客 VLAN)隔离开来。身份验证成功后,RADIUS CoA 会在 VLAN 之间移动设备。

UnionID

一个微信标识符,对于绑定到同一个开放平台账号下的所有公众号和网站应用,同一用户的 UnionID 保持一致。

对于需要在多个场所(每个场所都有自己的公众号)识别同一访客的连锁酒店、零售集团和多场所运营商至关重要。

应用实例

新加坡一家拥有 200 间客房的豪华酒店使用 HPE Aruba 控制器,并接待大量中国商务旅客。他们希望收集首次入住客人的受众特征数据,并确保再次光临的客人能够自动连接,而无需再次看到 Captive Portal。他们应该如何配置微信 OAuth 集成?

步骤 1:在微信公众平台 (mp.weixin.qq.com) 注册服务号,以处理客人在微信内置浏览器中访问 Captive Portal 的情况。在微信开放平台 (open.weixin.qq.com) 注册网站应用,以处理使用标准移动浏览器的客人。

步骤 2:配置 Captive Portal 以检测 MicroMessenger 用户代理 (user agent) 字符串。为内置浏览器用户提供公众平台 OAuth 流程,为标准浏览器用户提供开放平台二维码流程。

步骤 3:对于首次连接(数据库中不存在 OpenID),请求 snsapi_userinfo 权限范围。在 OAuth 重定向之前展示符合《个人信息保护法》(PIPL) 的同意屏幕。将返回的 OpenID、昵称、城市和性别存储在客人档案数据库中。

步骤 4:对于再次光临的客人(数据库中已存在 OpenID),请求 snsapi_base 权限范围。这会进行静默身份验证,无需用户可见的提示。

步骤 5:配置 HPE Aruba 控制器以在 UDP 端口 3799 上进行 RADIUS CoA。OAuth 成功后,Portal 服务器发送 CoA 请求,将设备从围墙花园 (walled garden) VLAN 提升到访客 VLAN。

步骤 6:实施 MAC 地址与 OpenID 关联记录,以处理再次光临客人的检测。请注意,由于 MAC 地址随机化,需要将 OpenID 作为主要标识符,而不能仅靠 MAC 地址。

考官评语: 该方法根据访问上下文正确区分了两个平台的注册,利用权限范围选择来平衡用户体验摩擦与数据收集,并实施了 RADIUS CoA 以进行安全网络强制执行。将 OpenID 作为主要的回访客人标识符是对 MAC 地址随机化的正确应对。对于中国公民的数据,符合 PIPL 的同意层是不可逾越的合规底线。

某零售连锁店的 IT 团队报告称,三个商场网点的微信 WiFi 登录失败率很高。用户在微信中完成了身份验证,但返回到 Portal 页面并显示错误。Portal 日志显示错误码 40029。可能的原因是什么,如何解决?

错误码 40029 意味着微信在令牌 (token) 交换期间拒绝了授权码 (authorisation code)。最常见的两个原因是重定向 URI 不匹配和授权码重复使用。

步骤 1:登录微信公众平台和微信开放平台的开发者控制台。导航至 OAuth 设置并列出所有已注册的重定向 URI。

步骤 2:将这些内容与您的 Portal 服务器在所有三个网点的生产环境中实际使用的重定向 URI 进行对比。检查子域名差异(如 portal.brand.com 与 brand.com)、协议差异(HTTP 与 HTTPS)以及路径差异(/callback 与 /wechat/callback)。

步骤 3:在微信控制台中注册每一个变体。微信执行的是精确匹配验证,而非前缀匹配。

步骤 4:如果 URI 匹配,请调查您的 Portal 服务器是否在尝试重复使用授权码。微信授权码为一次性使用,且在五分钟后失效。如果您的服务器使用相同的授权码重试令牌交换,则在第二次尝试时会收到 40029 错误。

步骤 5:在令牌交换端点中实现幂等性,以防止重复请求。

考官评语: 错误码 40029 是微信 OAuth 部署中最常见的错误,几乎总是由重定向 URI 不匹配引起的。多网点部署尤其容易出现此问题,因为每个网点可能使用不同的子域名或负载均衡器地址。第二个原因(授权码重复使用)较少见,但如果已确认 URI 注册无误,则值得排查。

练习题

Q1. 您正在为一个可容纳 60,000 人的体育场部署 Captive Portal,该体育场举办国际赛事,且拥有庞大的中国球迷群体。首要任务是在开门后的前 15 分钟内让所有观众联网,以缓解蜂窝网络拥堵。营销数据收集是次要目标。您应该配置哪种微信 OAuth 作用域(scope),为什么?

提示:考虑在门户服务器上向 15,000 名并发用户显示授权同意页面所带来的影响。

查看标准答案

配置 snsapi_base 作用域。这可以实现静默授权,无需用户确认同意,从而提供最快的联网体验。在体育场级别的规模下,授权同意页面会增加操作摩擦,这种摩擦在数千个并发连接中会成倍放大,并可能导致门户服务器负载激增。snsapi_base 仅返回 OpenID,这足以记录会话并识别回访球迷。对于您希望获取人口统计数据的首次到访球迷,您可以在联网后的调查问卷中提示其完善个人资料,而不是在身份验证关口进行拦截。

Q2. 您团队中的一名网络架构师建议将微信 AppSecret 存储在 Captive Portal 的客户端 JavaScript 中,通过直接从浏览器发起令牌交换调用来减少服务器往返次数。请解释为什么这种方法是严重的安全漏洞,以及正确的架构是什么。

提示:考虑谁可以查看客户端代码,以及 AppSecret 允许他们执行什么操作。

查看标准答案

将 AppSecret 存储在客户端 JavaScript 中会将其暴露给任何查看页面源代码或拦截网络流量的人。AppSecret 用于向微信 API 验证您的应用程序身份。利用它,恶意攻击者可以冒充您的应用程序,使用任何有效的授权码调用微信的令牌交换接口,获取用户的 OpenID 和个人资料数据,并可能耗尽您的 API 速率限制。正确的架构是采用服务端令牌交换接口。浏览器从微信接收授权码并将其传递给您的服务器。您的服务器使用存储在环境变量或密钥管理器中的 AppSecret,将该授权码交换为令牌,并仅返回门户所需的数据。AppSecret 绝不能离开您的服务器。

Q3. 您的场所在不同城市运营着三家酒店,每家酒店都有自己的微信公众号。一位在所有三家酒店都进行过身份验证的会员在您的数据库中拥有三个不同的 OpenID。您如何将其整合为单一的宾客身份?

提示:微信提供了一种跨账号身份关联机制,这需要特定的平台配置。

查看标准答案

实现微信的 UnionID 机制。将所有三个公众号绑定到同一个微信开放平台账号(open.weixin.qq.com)。绑定后,微信将在 snsapi_userinfo 响应中同时返回 UnionID 和 OpenID。对于绑定到同一个开放平台账号的所有应用,同一用户的 UnionID 是唯一且一致的。迁移您的数据库,使用 UnionID 作为跨酒店记录的唯一宾客标识符,同时保留每个账号的 OpenID 用于特定账号的 API 调用。对于在启用 UnionID 之前已通过验证的宾客,在其下次到访时触发 snsapi_userinfo 重新验证以获取 UnionID。

Q4. 在运行 Cisco Meraki 接入点的零售场所部署微信 WiFi 认证后,宾客反馈他们成功完成了微信登录,但被重定向回门户页面且无法访问互联网。门户服务器日志显示成功获取了令牌。最可能的原因是什么,您如何进行诊断?

提示:门户已验证身份。但还有什么步骤尚未发生?

查看标准答案

RADIUS 授权变更(CoA)未完成。门户服务器已通过微信 OAuth 验证了宾客的身份,但未能成功指示 Cisco Meraki 控制器将设备从围墙花园(walled garden)VLAN 移动到宾客 VLAN。诊断方法包括检查:(1)Meraki 控制器是否启用了 RADIUS CoA,且门户服务器的 IP 是否已被列为授权的 CoA 客户端;(2)门户服务器与控制器之间的 UDP 端口 3799 是否已开放;(3)门户服务器日志中是否有 CoA 请求错误或超时记录;(4)双方配置的共享密钥(shared secret)是否匹配。如果您的 Meraki 许可级别不支持 CoA,则 MAC 地址免认证(MAC address bypass)是备用方案,尽管这会带来指南中提到的 MAC 随机化风险。

继续阅读本系列

如何在 Starlink 上设置 Captive Portal:远程与海洋场所指南

本指南详细介绍了如何绕过原生 Starlink 硬件,并使用企业级路由设备集成云端托管的 Captive Portal。您将学习如何克服 CGNAT 限制、强制执行 VLAN 隔离、管理卫星带宽限制并确保合规性。

阅读指南 →

Captive Portal 最佳实践:兼顾高转化率与合规性设计

本技术指南为 IT 经理、网络架构师和场所运营总监提供了部署 Captive Portal 的完整蓝图,旨在平衡网络安全与高用户转化率。内容涵盖了从 VLAN 划分和 RADIUS 认证到符合 GDPR 的同意书设计以及认证方式选择的完整架构。结合 Purple 在 2024 年跨越 80,000 多个场所、4.4 亿次登录的实际运营经验,每一项建议均基于真实的部署数据。

阅读指南 →

如何优化 Captive Portals 以实现最大化网络安全与用户转化

本指南为企业级场所优化 Captive Portals 提供了完整的技术蓝图,涵盖网络分段架构、身份验证方式选择、符合 GDPR 的合规同意设计以及转化率优化。本书专为酒店、连锁零售、体育场馆和公共部门机构的 IT 经理、网络架构师及 CTO 撰写,旨在帮助他们在网络安全与第一方数据采集之间取得平衡。Purple 在全球 80,000 多个场所运营 Captive Portal 基础设施,2024 年登录量达 4.4 亿次,本指南中的框架均源自这些丰富的运营经验。

阅读指南 →