Ubiquiti UniFi 的 Captive Portal：搭配 Purple 訪客 WiFi 進行設定

Captive Portal for Ubiquiti UniFi — A Purple Technical Briefing [INTRODUCTION & CONTEXT — 預計 1 分鐘] 歡迎收看 Purple 技術簡報系列。我是你們的主持人，今天我們要深入探討在 Ubiquiti UniFi 基礎架構上部署外部 captive portal 的細節 - 這是全球餐旅業、零售業和企業環境中部署最廣泛的網路平台之一。 如果您是使用 UniFi Cloud Gateways、Dream Machines 或 UniFi Network Application 的 IT 經理、網路架構師或系統整合商，這一集就是專為您準備的。我們將逐步介紹外部 portal 機制在幕後是如何運作的、如何正確配置它、常見的陷阱在哪裡，以及為什麼在 UniFi 部署之上疊加 Purple，對於需要比基本 splash page 更多功能的場域來說，是正確的架構決策。 讓我們開始吧。 [TECHNICAL DEEP-DIVE — 預計 5 分鐘] 首先，讓我們瞭解當訪客裝置連線到已啟用 captive portal 的 UniFi SSID 時，實際上發生了什麼事。 當訪客裝置與您的訪客 SSID 關聯時，UniFi Access Point 會照常透過 DHCP 為其分配一個 IP 地址。但該裝置會立即被置於 UniFi 所稱的「待處理」狀態。在此狀態下，AP 內建的 DNSmasq 程序會攔截該裝置進行的每一次 DNS 查詢，無論該裝置認為自己使用的是什麼 DNS 伺服器。AP 會將所有 DNS 流量重新導向到其自身。 同時，AP 在連接埠 80 上運作一個輕量級的 HTTP 重新導向器。當訪客的瀏覽器發出任何 HTTP 請求（請注意，關鍵字是 HTTP，而不是 HTTPS）時，重新導向器會立即回傳 302 重新導向，將瀏覽器傳送到 captive portal splash page。這就是觸發 iOS 和 Android 裝置上「登入 WiFi」通知的機制。 現在，這就是內建 portal 與外部 portal 的區別變得至關重要的關鍵所在。使用內建的 UniFi Hotspot Portal，splash page 是由 UniFi Network Application 直接提供的。它功能實用、設定快速，但限制非常多。您只能獲得基本的密碼驗證、憑證和 Stripe 付款。沒有電子郵件擷取、沒有社群媒體登入、沒有 GDPR 同意管理、沒有 CRM 整合，也沒有除了工作階段計數之外的有意義的分析。 當您配置 External Portal Server（這也是我們今天關注的設定）時，您是在告訴 UniFi 控制器將訪客重新導向到一個完全獨立的網頁應用程式。在我們的案例中，那就是 Purple。您在 External Portal Server 欄位中輸入的 URL 就會成為所有這些 302 重新導向的目的地。 以下是關於該重新導向 URL 的重要技術細節。當 UniFi 將訪客重新導向至您的外部入口網站時，它會在 URL 中附加多個查詢參數。這些包括：AP MAC 位址、用戶端裝置 MAC 位址、Unix 時間戳記、用戶端原先嘗試造訪的原始 URL 以及 SSID 名稱。在這種情況下，您的外部入口網站（即 Purple）會擷取這些參數，並使用它們來識別連線的裝置、呈現適當的 splash page、處理驗證，然後向 UniFi Network Application 進行 API 呼叫，以授權該 MAC 位址。 該 API 呼叫是至關重要的交握程序。自 UniFi Network Application 9.1 及更新版本起，已提供具有適當金鑰驗證的官方 REST API。授權端點是對第一版 sites API 發送的 POST 請求，針對特定的用戶端 ID，並帶有 JSON 本文，可指定以分鐘為單位的時間限制、以 MB 為單位的資料使用量限制以及以 kbps 為單位的速率限制。一旦控制器收到該授權，它就會將指令推送到 AP，訪客便會從待處理狀態轉變為已授權。網際網路存取權隨即被授予。 現在我們來談談 Walled Garden，UniFi 稱之為 Pre-Authorization Access。這是訪客在驗證之前可以造訪的網域和 IP 位址白名單。這是必不可少的，也是最常見的設定錯誤來源之一。 您的 walled garden 至少需要包含 Purple 入口網站的完整網域名稱（FQDN），以及 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 入口網站可透過具有有效、受信任 SSL 憑證的 HTTPS 進行存取。自我簽署憑證會導致瀏覽器安全性警告，進而阻止入口網站載入。對於實際生產部署而言，這是不可妥協的要求。 另一個 UniFi 特定的考量點是控制器可存取性。無論 UniFi Network Application 是在 Cloud Gateway、Cloud Key 還是自託管伺服器上執行，都必須能夠從 Purple 的基礎設施存取，API 授權呼叫才能成功。如果您的控制器位於 NAT 後方的私有網路中，您需要確保相關的 API 連接埠可供存取。對於自託管控制器，舊版 API 通常是連接埠 8443，而 9.1 版本中引入的新版 API 則是標準的 HTTPS 連接埠 443。Purple 的支援文件指定了需要輸入權限存取您控制器的確切 IP 範圍。 對於基於 RADIUS 的驗證 - 這適用於您將 Purple 與 WPA2-Enterprise 或 WPA3-Enterprise SSID 搭配部署，而不是採用開放式訪客 SSID 模式 - UniFi 內建的 RADIUS 伺服器支援標準的 802.1X EAP 方法。您可以在 Settings、Networks、RADIUS Servers 下設定 RADIUS 設定檔，然後在您的 SSID 設定中引用該設定檔。UniFi 還自 8.4 版本起支援透過 TLS 進行的 RADIUS（即 RADSEC），這會加密 AP 與驗證伺服器之間的 RADIUS 流量。對於 RADIUS 流量需經過公開網際網路的多站點部署，強烈建議使用 RADSEC。 [實作建議與常見陷阱 - 大約 2 分鐘] 讓我為您提供實作清單，這是我在向任何於 UniFi 上部署 Purple 的客戶進行引導時會逐一確認的實戰要點。 第一，網路分段。您的訪客 SSID 必須位於專用的 VLAN 上，並與您的企業和 IoT 網路隔離。UniFi 讓這項操作變得簡單 - 在 Settings、Networks 中建立一個專用網路，指派一個 VLAN ID，並將您的訪客 SSID 與該網路建立關聯。在訪客網路上啟用用戶端隔離，以防止訪客與訪客之間的流量傳輸。 第二，控制器必須擁有有效的 FQDN 和受信任的 SSL 憑證。請勿依賴 IP 地址。請使用適當的網域名稱，為其取得 Let's Encrypt 或商業憑證，並將 UniFi 設定為使用該憑證。這可以解決絕大多數的 HTTPS 重新導向問題。 第三，仔細建立您的 Walled Garden（圍牆花園）並進行測試。最少應包含的項目為：您的 Purple 入口網站網域及其 IP 範圍、用於 iOS、Android 和 Windows 的 Captive Portal 偵測網域，以及您正在使用的任何 OAuth 提供者網域。請使用從未連線到該網路的裝置進行測試 - 快取的 DNS 和網路狀態可能會在測試期間掩蓋 Walled Garden 的漏洞。 第四，針對 API 整合，請在 UniFi Network Application 中使用具有最低必要權限的專用本機管理員帳戶。請勿使用您的主要管理員憑證。如果您使用的是 Network Application 9.1 或更新版本，請使用 Control Plane、Integrations 下的新 API 金鑰機制 - 這樣更安全，且不需要基於憑證的驗證。 第五，請仔細考慮工作階段持續時間。UniFi 的預設訪客工作階段過期時間可能短至八小時。對於訪客可能會入住多個晚上的旅宿業部署，請在 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 設定為 External Portal Server 選項，並指向您的 Purple 傳送門 URL；建立一個涵蓋 Purple 基礎架構和您所使用的任何 OAuth 供應商的完整 Walled Garden；確保您的 UniFi 控制器具有有效的 SSL 憑證，且可從 Purple 的 API 伺服器存取；並為您的場域類型設定適當的工作階段持續時間。 商業案例非常簡單。內建的 UniFi 傳送門僅為您提供一個歡迎頁面。Purple 則為您提供一個符合法規、由分析驅動的訪客體驗平台，該平台可與您的 CRM 整合，在 GDPR 同意下收集第一方數據，並提供場域營運商和行銷團隊實際需要的客流量和停留時間分析。 如果您是大規模部署 UniFi 的 MSP 或系統整合商，Purple 的多站點管理和白牌功能使其成為您客戶的最佳重疊網路方案。 如需詳細的設定說明文件、Walled Garden IP 清單以及 API 整合指南，請造訪 purple.ai。感謝您的聆聽。