Ubiquiti UniFi 的 Captive Portal：使用 Purple 顧客 WiFi 進行設定

Captive Portal for Ubiquiti UniFi - A Purple Technical Briefing [INTRODUCTION & CONTEXT - approximately 1 minute] 歡迎收看 Purple Technical Briefing 系列。我是您的主持人，今天我們要深入探討在 Ubiquiti UniFi 基礎架構上部署外部 Captive Portal 的細節 - 這是全球餐飲旅宿、零售和企業環境中部署最廣泛的網路平台之一。 如果您是使用 UniFi Cloud Gateways、Dream Machines 或 UniFi Network Application 的 IT 經理、網路架構師或系統整合商，本集節目正是為您準備的。我們將逐步說明外部 Portal 機制在後台是如何運作的、如何正確配置、常見的陷阱有哪些，以及為什麼對於需要的不僅僅是基本登入頁面的場域來說，在 UniFi 部署之上疊加 Purple 是正確的架構決策。 讓我們開始吧。 [TECHNICAL DEEP-DIVE - approximately 5 minutes] 首先，讓我們瞭解當訪客連接到已啟用 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 登入頁面。這就是在 iOS 和 Android 裝置上觸發「登入 WiFi」通知的機制。 現在，內建 Portal 與外部 Portal 的區別在此變得至關重要。使用內建的 UniFi Hotspot Portal，登入頁面是由 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 伺服器）下配置 RADIUS 設定檔，然後在您的 SSID 配置中引用該設定檔。自 8.4 版本起，UniFi 還支援透過 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 帳戶中將 Purple 用於多個 UniFi 站點嗎？是的。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 入口網站只提供您一個登入頁面（splash page）。而 Purple 則為您提供一個符合法規遵循、由數據分析驅動的訪客體驗平台，該平台可與您的 CRM 整合、在符合 GDPR 同意的情況下收集第一方數據，並提供場域營運商和行銷團隊實際需要的客流量與停留時間分析。 如果您是負責大規模部署 UniFi 的 MSP 或系統整合商，Purple 的多站點管理和白牌功能使其成為您客戶的理想疊加方案。 如需詳細的配置說明文件、Walled Garden IP 清單和 API 整合指南，請造訪 purple.ai。感謝您的聆聽。