UniFi captive portal 設定指南

Captive Portal for Ubiquiti UniFi - A Purple 技術簡報 [引言與背景資訊 - 約 1 分鐘] 歡迎收看 Purple 技術簡報系列。我是你們的主持人，今天我們要深入探討在 Ubiquiti UniFi 基礎架構上部署外部 Captive Portal 的細節 - 這是全球旅宿業、零售業和企業環境中部署最廣泛的網路平台之一。 如果您是使用 UniFi Cloud Gateways、Dream Machines 或 UniFi Network Application 的 IT 經理、網路架構師或系統整合商，這一集就是為您準備的。我們將逐步說明外部 Portal 機制在底層到底是如何運作的、如何正確配置它、常見的陷阱在哪裡，以及為什麼對於需要基本 Splash 頁面以外功能的場所來說，在 UniFi 部署之上疊加 Purple 是正確的架構決策。 讓我們開始吧。 [技術深挖 - 約 5 分鐘] 首先，讓我們瞭解當訪客連接到已啟用 Captive Portal 的 UniFi SSID 時，實際上發生了什麼事。 當訪客裝置與您的訪客 SSID 關聯時，UniFi 存取點（AP）會像往常一樣透過 DHCP 為其分配一個 IP 地址。但該裝置會立即被置於 UniFi 所謂的「待處理」（pending）狀態。在此狀態下，AP 內建的 DNSmasq 程序會攔截裝置發出的每一次 DNS 查詢，而不管裝置認為自己正在使用什麼 DNS 伺服器。AP 會將所有 DNS 流量重導向到自身。 同時，AP 會在連接埠 80 上運作一個輕量級的 HTTP 重導向器。當訪客的瀏覽器發出任何 HTTP 請求（請注意，這是關鍵字，是 HTTP，而非 HTTPS）時，重導向器就會立即回傳一個 302 重導向，將瀏覽器傳送到 Captive Portal Splash 頁面。這就是觸發 iOS 和 Android 裝置上「登入 WiFi」通知的機制。 現在，這就是內建 Portal 與外部 Portal 的區別變得至關重要的關鍵所在。使用內建的 UniFi Hotspot Portal，Splash 頁面直接由 UniFi Network Application 提供。它功能尚可、設定快速，但限制非常多。您只能獲得基本的密碼驗證、憑證和 Stripe 付款。沒有電子郵件擷取、沒有社群登入、沒有 GDPR 同意管理、沒有 CRM 整合，也沒有工作階段計數以外的實質分析。 當您配置外部 Portal 伺服器（External Portal Server）時 - 這正是我們今天關注的設定 - 您是在告訴 UniFi 控制器將訪客重導向到一個完全獨立的 Web 應用程式。在我們的案例中，那就是 Purple。您在「External Portal Server」欄位中輸入的 URL，就會成為所有那些 302 重導向的目的地。 以下是關於該重新導向 URL 的重要技術細節。當 UniFi 將訪客重新導向到您的外部入口網站時，它會在 URL 中附加幾個查詢參數。這些參數包括：AP MAC 位址、用戶端裝置 MAC 位址、Unix 時間戳記、用戶端原先嘗試造訪的原始 URL 以及 SSID 名稱。您的外部入口網站 - 在此情境中為 Purple - 會擷取這些參數，並使用它們來識別連線的裝置、呈現適當的歡迎頁面、處理驗證，然後向 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 帳戶中將 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 分鐘] 總結來說：將 Purple 部署為 UniFi 上的外部 Captive Portal 是一個得到良好支援且架構健全的整合。關鍵步驟為：將您的訪客 SSID 配置為指向 Purple 入口網站 URL 的 External Portal Server 選項、建立涵蓋 Purple 基礎架構和您所使用的任何 OAuth 供應商的完整 Walled Garden、確保您的 UniFi 控制器擁有有效的 SSL 憑證且可從 Purple 的 API 伺服器存取，並為您的場域類型配置適當的工作階段持續時間。 商業效益顯而易見。內建的 UniFi 入口網站只提供您一個歡迎頁面。而 Purple 則為您提供一個符合法規、數據分析驅動的訪客體驗平台，該平台可與您的 CRM 整合、在符合 GDPR 同意的情況下收集第一方數據，並提供場域營運商和行銷團隊真正需要的客流量與停留時間分析。 如果您是進行大規模 UniFi 部署的 MSP 或系統整合商，Purple 的多站點管理和白牌功能使其成為您客戶的理想解決方案。 如需詳細的配置說明文件、Walled Garden IP 清單和 API 整合指南，請造訪 purple.ai。感謝您的聆聽。