UniFi captive portal设置指南

Captive Portal for Ubiquiti UniFi - A Purple Technical Briefing [INTRODUCTION & CONTEXT - approximately 1 minute] 欢迎收看 Purple 技术简报系列。我是主持。今天我们将深入探讨在 Ubiquiti UniFi 基础设施上部署外部 Captive Portal 的技术细节，这是全球酒店餐饮、零售和企业环境中部署最广泛的网络平台之一。 如果您是使用 UniFi Cloud Gateways、Dream Machines 或 UniFi Network Application 的 IT 经理、网络架构师或系统集成商，这一期内容非常适合您。我们将详细剖析外部门户机制在底层的实际工作原理、如何正确配置、常见的陷阱在哪里，以及为什么对于需要更高级 Splash 页面（而不仅仅是基础页面）的场所来说，在 UniFi 部署之上叠加 Purple 是正确的架构决策。 让我们开始吧。 [TECHNICAL DEEP-DIVE - approximately 5 minutes] 首先，让我们了解当访客连接到启用了 Captive Portal 的 UniFi SSID 时，实际发生了什么。 当访客设备与您的访客 SSID 关联时，UniFi 接入点（AP）会像往常一样通过 DHCP 为其分配一个 IP 地址。但该设备会立即被置于 UniFi 所称的“挂起”状态。在此状态下，AP 内置的 DNSmasq 进程会拦截设备发起的每一个 DNS 查询，无论该设备认为自己正在使用什么 DNS 服务器。AP 会将所有 DNS 流量重定向到自身。 同时，AP 在 80 端口上运行一个轻量级的 HTTP 重定向器。一旦访客的浏览器发起任何 HTTP 请求 - 请注意，这里是 HTTP，而不是 HTTPS - 重定向器就会触发一个 302 重定向，将浏览器发送到 Captive Portal 的 Splash 页面。正是这种机制触发了 iOS 和 Android 设备上的“登录 WiFi”通知。 现在，内置门户与外部门户之间的区别就变得至关重要了。使用内置的 UniFi Hotspot Portal，Splash 页面由 UniFi Network Application 直接提供。它功能尚可，设置也很快，但局限性非常明显。您只能获得基础的密码认证、凭证（vouchers）和 Stripe 支付。没有电子邮件捕获、没有社交媒体登录、没有 GDPR 合规同意管理、没有 CRM 集成，除了会话计数之外，也没有任何有意义的数据分析。 当您配置“外部门户服务器”（External Portal Server） - 也就是我们今天关注的设置 - 时，您是在告知 UniFi 控制器将访客重定向到一个完全独立的 Web 应用程序。在我们的案例中，该程序就是 Purple。您在“外部门户服务器”字段中输入的 URL 将成为所有这些 302 重定向的目的地。 以下是关于该重定向 URL 的重要技术细节。当 UniFi 将访客重定向到您的外部门户时，它会在 URL 中附加多个查询参数。这些参数包括：AP MAC 地址、客户端设备 MAC 地址、Unix 时间戳、客户端原本尝试访问的原始 URL 以及 SSID 名称。您的外部门户 - 在此场景中为 Purple - 会捕获这些参数，利用它们来识别连接设备，展示相应的 splash 页面，处理身份验证，然后向 UniFi 网络应用发起 API 回调以授权该 MAC 地址。 该 API 调用是至关重要的握手过程。自 UniFi 网络应用 9.1 及更高版本起，提供了一个具有标准基于密钥身份验证的官方 REST API。授权端点是对站点 API 第一版本的 POST 请求，指向特定的客户端 ID，其 JSON 主体可以指定以分钟为单位的时间限制、以兆字节为单位的数据使用限制以及以千字节每秒为单位的速率限制。一旦控制器收到该授权，它就会将指令推送给 AP，访客状态随即从待处理变为已授权。互联网访问权限正式授予。 现在我们来谈谈 Walled Garden（围墙花园），UniFi 将其称为“预授权访问”。这是访客在进行身份验证之前可以访问的域名和 IP 地址白名单。这至关重要，也是最常见的配置错误来源之一。 您的 walled garden 至少需要包含 Purple 门户的完全限定域名，以及 Purple 基础设施解析到的 IP 地址或 CIDR 范围。如果您正在使用社交登录 - 比如 Facebook、Google、Microsoft - 您还需要添加这些提供商的 OAuth 端点域名。Google 的登录端点跨越多个 IP 范围和多个域名，包括 accounts.google.com 和 oauth2.googleapis.com。Facebook 的登录基础设施同样需要多个条目。Purple 的文档提供了一个持续维护的所需确切条目列表，并且随着这些提供商更新其基础设施，该列表也会保持最新。 UniFi 还有一个特定的关键怪癖，常常会让许多部署工作陷入困境。AP 上的 HTTP 重定向器仅拦截 80 端口上的普通 HTTP 流量。现代设备 - 比如 iOS、Android、Windows 和 macOS - 都会执行基于 HTTPS 的 Captive Portal 检测。Apple 设备通过 HTTPS 访问 captive.apple.com。Android 设备访问 connectivitycheck.gstatic.com。如果这些 HTTPS 请求没有收到特定的响应，设备可能会判定不存在 Captive Portal，从而根本无法显示登录提示。 解决方案是确保您的 walled garden 包含了主流操作系统的 Captive Portal 检测域名，并且您的 Purple 门户可通过 HTTPS 访问，且配有有效的、受信任的 SSL 证书。自签名证书会导致浏览器安全警告，从而阻止门户加载。对于生产环境部署而言，这是不可妥协的要求。 另一个需要特别考虑的 UniFi 相关因素是控制器的可访问性。无论 UniFi Network Application 是运行在 Cloud Gateway、Cloud Key 还是自托管服务器上，都必须能够从 Purple 的基础架构进行访问，以便 API 授权调用能够成功。如果您的控制器位于 NAT 之后的私有网络中，您需要确保相关的 API 端口是可访问的。对于自托管控制器，旧版 API 的端口通常是 8443，而 9.1 版本中引入的新版 API 则是标准 HTTPS 端口 443。Purple 的支持文档指定了需要入站访问您控制器的确切 IP 范围。 对于基于 RADIUS 的身份验证 - 这适用于您在开放式访客 SSID 模式之外部署 Purple 搭配 WPA2-Enterprise 或 WPA3-Enterprise SSID 的场景 - UniFi 内置的 RADIUS 服务器支持标准的 802.1X EAP 方法。您可以在“设置”、“网络”、“RADIUS 服务器”下配置 RADIUS 配置文件，然后在 SSID 配置中引用该配置文件。从 8.4 版本开始，UniFi 还支持基于 TLS 的 RADIUS（即 RADSEC），它加密了 AP 与身份验证服务器之间的 RADIUS 流量。对于 RADIUS 流量需要跨越公共互联网的多站点部署，强烈推荐使用 RADSEC。 [实施建议与陷阱 - 约2分钟] 让我为您提供一份实用的实施清单，这是我在向任何在 UniFi 上部署 Purple 的客户推荐时都会详细说明的。 首先，网络隔离。您的访客 SSID 必须处于专用的 VLAN 上，与您的企业网络和物联网（IoT）网络隔离。UniFi 让这一切变得非常简单 - 在“设置”、“网络”中创建一个专用网络，为其分配一个 VLAN ID，并将您的访客 SSID 与该网络关联。在访客网络上启用客户端隔离，以阻止访客之间的流量互通。 其次，控制器必须具有合法的 FQDN 和可信的 SSL 证书。不要依赖 IP 地址。使用一个规范的域名，为其获取 Let's Encrypt 或商业证书，并配置 UniFi 使用该证书。这可以解决绝大多数 HTTPS 重定向问题。 第三，仔细构建您的围墙花园（Walled Garden）并进行测试。最少包含的条目有：您的 Purple 门户域名及其 IP 范围，用于 iOS、Android 和 Windows 的 Captive Portal 检测域名，以及您正在使用的任何 OAuth 提供商域名。请使用从未连接过该网络的设备进行测试 - 缓存的 DNS 和网络状态可能会在测试期间掩盖围墙花园的配置漏洞。 第四，对于 API 集成，请在 UniFi Network Application 中使用专用的本地管理员账户，并赋予其所需的最小权限。不要使用您的主管理员凭据。如果您使用的是 Network Application 9.1 或更高版本，请使用“控制面板”、“集成”下的全新 API 密钥机制 - 它更安全，且不需要基于凭据的身份验证。 第五，请仔细考虑会话时长。UniFi 的默认访客会话过期时间可能短至8小时。对于访客可能会入住多晚的酒店部署，请在 Purple 门户设置中配置适当的会话时长，并确保在 API 授权调用中正确传递这些时长。 我见过的最常见问题是部署在无法公开访问的自托管控制器上。如果 Purple 无法连接到您的控制器来授权访客，门户页面将会加载，但身份验证会静默失败。在上线前，请务必验证从 Purple 基础设施到您的控制器的 API 连接性。 [快速问答 - 约1分钟] 这在 UniFi Dream Machine Pro 上适用吗？是的。所有 UniFi OS 控制台 - UDM、UDM Pro、UDM SE、UCG Ultra、UCG-Max - 都支持 External Portal Server 配置。Network Application 直接在设备上运行。 我可以在单个 Purple 账户中对多个 UniFi 站点使用 Purple 吗？是的。Purple 的多站点架构正是为此而设计的。每个场所都配置为 Purple 中的独立站点，并映射到相应的 UniFi 站点。 我需要在 UniFi 网关上开放防火墙端口吗？您需要确保访客 VLAN 流量可以通过端口 443 访问 Purple 门户域名。控制器 API 端口也必须可以从 Purple 的服务器访问。Purple 的文档中提供了具体的 IP 范围。 WPA3 呢？UniFi 支持 WPA3 Personal 和 WPA3 Enterprise。Captive Portal 机制可在访客网络上与 WPA3 Personal 配合工作。WPA3 Enterprise 使用 802.1X 和 RADIUS，这是另一种身份验证流程。 [总结与后续步骤 - 约1分钟] 总结一下：在 UniFi 上将 Purple 部署为外部 Captive Portal 是一种得到良好支持、架构合理的集成方案。关键步骤包括：将您的访客 SSID 配置为指向您的 Purple 门户 URL 的 External Portal Server 选项，构建一个涵盖 Purple 基础设施和您正在使用的任何 OAuth 提供商的完整 Walled Garden（围墙花园），确保您的 UniFi 控制器拥有有效的 SSL 证书且可从 Purple 的 API 服务器访问，并根据您的场所类型配置适当的会话时长。 其商业价值显而易见。内置的 UniFi 门户只能为您提供一个 Welcome 页面。而 Purple 则为您提供了一个符合合规要求、数据驱动的访客体验平台，它可以与您的 CRM 集成，在满足 GDPR 同意的前提下收集第一手数据，并提供场所运营商和营销团队真正需要的客流量和停留时间分析。 如果您是需要大规模部署 UniFi 的 MSP 或系统集成商，Purple 的多站点管理和白标功能使其成为您客户的理想选择。 有关详细的配置文档、Walled Garden IP 列表以及 API 集成指南，请访问 purple.ai。感谢收听。