RADIUS 伺服器搭配 External Web Portal 的 API 與程式碼範例（Omada 控制器 4.1.5 或更新版本）

適用於 Omada 控制器 4.1.5 以上版本。

Omada 控制器 3.1.4 至 3.2.17 請參考 FAQ2390

關於 Omada 控制器 3.0.5 或以下版本，請參閱 FAQ916

本 FAQ 概述了建立 External Web Portal 伺服器時的要求。在 Omada 控制器中，僅當 Portal （門戶）認證類型為 External Radius Server 時，才能使用 External Web Portal。

下圖描述了無線用戶端、EAP、Omada 控制器、External Web Portal 和 Radius 伺服器之間的運作流程。它將幫助您更好地了解建立 External Web Portal 伺服器的要求。

1. 對於連接到無線網路的無線用戶端和有線區域網路的有線用戶端，當它們嘗試存取網際網路時， EAP 或閘道將攔截用戶端的 HTTP 請求，然後將其重新導向至 Omada 控制器。 （步驟 1 和步驟 2）

2. 然後，Omada 控制器透過向用戶端回覆狀態碼 302 Found 的 HTTP 回應，將用戶端的請求重新導向到 External Portal 頁面。（步驟 3 和步驟 4）

3. 用戶端發送 HTTP / HTTPS GET 使用參數向 External Web Portal 請求 “ ?target=target_controller_ip&targetPort=target_controller_port&clientMac=client_mac&clientIp=client_ip&raidusServerIp=radius_server_ip&apMac=ap_mac&gatewayMac=gateway_mac&scheme=scheme&ssidName==ssid_name&radioId=radio_id（0 表示 2.4G 廣播，1 表示 5G 廣播）&vid=vid&originUrl=redirecturl（如果您在無線/有線用戶端通過入口網站認證後未設定重新導向 URL，預設的重新導向 URL 則將取決於無線用戶端）”。
例如：“https://www.externalportal.com/?target=172.30.30.113&targetPort=8088&clientMac=F8-1E-DF-AA-AA-AA&clientIP=172.30.30.103&raidusServerIp=172.30.30.120&apMac=AC-84-C6-BB-BB-BB&GatewayMac=172.30.0.1&scheme=https&ssidName=eap_test&radioId=1&originalUrl=https%3A%2F%2Fwww.tp-link.com” （步驟 5）

4. External Web Portal 伺服器應該可以取得 clientMac、clientIp、apMac、gatewayMac、ssidName、radioId、vid、scheme、originUrl 參數的值。然後External Web Portal 伺服器應將用戶端重新導向至控制器，並提供 username、password、clientMac、clientIp、apMac、gatewayMac、ssidName、scheme、vid、radioId、originUrl 等資訊。（步驟 6）

5. 用戶端發送 HTTP / HTTPS POST 封包到 (http) https://target_controller_ip:targetport/portal/radius/auth (或 radius / browserauth) JSON 格式（或 HTML 形式） 在提交後的 HTTP 訊息主體中。Portal 的預設「目標連接埠」是 8843（步驟 7）。 radius / auth 和 radius / browserauth 的差異請參考 Demo 和 API 部分。

說明：從 Controller 5.0 開始，如果使用 radius/auth API，則需要在 HTTP 標頭中提交「Access-Control-Allow-Origin:URL」欄位，以增強跨來源資源共享（CORS）過程中的安全性。例如，如果您的 External Web Portal 的網域是「www.tplinkportal.com」您需要新增 「Access-Control-Allow-Origin:https://www.tplinkportal.com」。請在文章末端下載範例以供參考。

6. Omada 控制器與 Radius 伺服器通訊，以驗證使用者名稱和密碼。（步驟 8 和步驟 9）

7. 如果驗證通過，即從 Radius 伺服器收到 Access-Accept，Omada 控制器將根據用戶端的設定重新導向內建的成功頁面或預先定義的網頁。（步驟 10）

Demo 和 API：

從 4.1.5 到 5.1.0，我們提供了API： target_controller_ip:targetport/portal/radius/auth 並以 JSON 格式提交，

以下的 HTML 範本是一個簡單的示範，供您開發符合 JSON 格式的 External Web Portal 來與 Omada 控制器一起使用：

External Web Server Demo (JSON)

當 Web Portal Side 端使用 HTTPS 且 Omada 控制器端使用 HTTP 時，使用 AJAX 存取將造成跨來源資源共享 (CORS) 的跨域存取問題，可能會被瀏覽器攔截。所以我們從 Omada Controller 5.3.1 開始提供 HTML 表單提交 API：target_controller_ip:targetport/portal/radius/browserauth ，並在後端實現頁面跳轉。

以下的 HTML 範本是另一個使用 HTML 表單的示範：

External Web Server Demo (HTML form)

說明：

1. 如果您使用 Omada 雲端控制器（CBC），基於安全原因僅支援透過 HTML 表單進行的 HTTPS POST 到「browserauth」API。對於 CBC，請在指向 「browserauth」API 的 URL 中使用您的 CBC 的域名，而不是「target_controller_ip:targetport」。

例如，對於這個圖中的 CBC，API 將為「https://aps1-omada-controller.tplinkcloud.com/portal/radius/browserauth」

2. 如果您的控制器（4.1.5 或更高版本）是從控制器 3.x.x 升級的，請注意我們更改了一些參數的「名稱」。

請注意，在相同的請求中，apMac 和 gatewayMac 不能同時存在。當有線用戶端進行認證時，請將 apMac 留空。

3. 在第 7 步驟中，如果您的表單有非 ASCII 字元（例如 SSID 名稱是中文或其他語言），將 HTTP / HTTPS POST 傳送至控制器時必須使用 UTF-8 編碼。

4. 如果您選擇 ajax 存取，請注意控制器 5.0 以上版本的「Access-Control-Allow-Origin:URL」欄位。

5. 建議使用 HTML 表單示範和 radius / browserauth API。

附錄：auth和 browserauth 的 API 文檔