API和程式碼範例（Omada控制器 5.0.15或更高版本）
69104 適用於Omada控制器 5.0.15或更高版本
Omada控制器4.1.5至4.4.6，請參考以下： FAQ 2907
Omada控制器2.6.0至3.2.17，請參考以下： FAQ 2274
與Omada SDN Controller v4相比，主要的更改如下：
1、在熱點登入和用戶端資訊提交的URL新增控制器ID
2、HTTP表頭新增CSRF token
注意：粗斜體字中的關鍵字表示這些參數是由EAP或閘道器自動填入的，應由您的外部門戶伺服器正確識別並傳遞。參數的含義在首次出現時已說明。
本文概述了建立外部門戶伺服器（簡稱Portal）所需的要求。下面的圖示描述網路設備之間的數據flow，這有助於更加理解工作機制。
步驟1、2
當用戶連接到啟用了Portal的無線或有線網路並嘗試存取網路時， HTTP請求將分別由EAP或Gateway攔截，重新導向至Omada SDN Controller（簡稱Controller），然後連同由EAP或Gateway在URL中自動填入連接的資訊。
步驟3、4
之後，用戶將使用連接資訊發送HTTP GET請求給Controller，然後根據Controller的HTTP回覆，將被重新導向到Portal，該回覆包含HTTP狀態碼302、Portal的URL所在字段以及連接資訊。
EAP的URL：
http(s)://PORTAL?clientMac=CLIENT_MAC&apMac=AP_MAC&ssidName=SSID_NAME&t=TIME_SINCE_EPOCH&radioId=RADIO_ID&site=SITE_NAME&redirectUrl=LANDING_PAGE.
閘道器的URL：
http(s)://PORTAL?clientMac=CLIENT_MAC&gatewayMac=GATEWAY_MAC&vid=VLAN_ID&t=TIME_SINCE_EPOCH&site=SITE_NAME&redirectUrl=LANDING_PAGE.
|
PORTAL |
外部門戶伺服器的IP地址或URL，以及埠號（如果需要）。 | |
|
clientMac |
CLIENT_MAC |
用戶的MAC |
|
apMac |
AP_MAC |
用戶連接的EAP MAC |
|
gatewayMac |
GATEWAY_MAC |
閘道器的MAC |
|
vid |
VLAN_ID |
用戶連接有線網路的VLAN ID |
|
ssidName |
SSID_NAME |
用戶連接的SSID名稱 |
|
radioId |
RADIO_ID |
用戶連接頻段的Radio ID，0代表2.4G、1代表5G。 |
|
site |
SITE_NAME |
站點名稱 |
|
redirectUrl |
LANDING_PAGE |
成功驗證後要訪問的URL，可以在登入頁面中設定。 |
|
t |
TIME_SINCE_EPOCH |
這裡的單位為microsecond |
步驟5、6
客戶端將向上述的URL發送HTTP GET請求至Portal，Portal必須能夠識別並保留HTTP GET請求的查詢字符串中的連接資訊，並返回用於身份驗證的網頁。
步驟7、8、9
用戶將向Portal提交身份驗證資訊，這些資訊將被傳遞到身份驗證伺服器進行驗證。接著身份驗證伺服器將驗證結果回傳給Portal。
根據您的需求，您可以決定Portal如何取得用戶的身份驗證資訊，以及Portal如何與身份驗證伺服器溝通。
注意：上圖中，Portal和身份驗證伺服器是分開的，您可以依照您的需求將它們安裝在同一台伺服器上，身份驗證方法也由您決定。只需確保Portal能夠從身份驗證伺服器取得驗證結果。
步驟10、11
若身份驗證請求取得授權，Portal應透過自身API 將用戶的資訊傳送到控制器。
首先，它必須透過發送HTTP POST請求登入Controller，請求的URL應為： https://CONTROLLER:PORT/CONTROLLER_ID/api/v2/hotspot/login API應該要以JSON格式攜帶操作者帳戶資訊並將其放置於HTTP訊息請求體內： {"name": "OPERATOR_USERNAME","password": "OPERATOR_PASSWORD"}.
留意此處帳號和密碼是在熱點管理界面中新增的操作員帳號，而不是控制器帳號的帳號和密碼。
|
CONTROLLER |
Omada SDN控制器的IP或URL |
|
PORT |
Omada SDN控制器的管理HTTPS通訊埠(預設情況下，軟體使用8043、OC使用433。您可以前往“設定 --- 控制器 --- 存取設定”進行修改。 |
|
CONTROLLER_ID |
Omada SDN Controller的識別符號，當您存取控制器時，識別符號將自動新增到URL中，從中您可以獲取識別符號。 例如，您的控制器URL是https://localhost:8043/abcdefghijklmnopqrstuvwxyzabcdef/, 那麼CONTROLLER_ID 就會是 abcdefghijklmnopqrstuvwxyzabcdef. |
|
OPERATOR_USERNAME |
熱點操作員的用戶名 |
|
OPERATOR_PASSWORD |
熱點操作員的密碼 |
PHP Code範例：
public static function login()
{
$loginInfo = array(
"name" => OPERATOR_USER,
"password" => OPERATOR_PASSWORD
);
$headers = array(
"Content-Type: application/json",
"Accept: application/json"
);
$ch = curl_init();
// post
curl_setopt($ch, CURLOPT_POST, TRUE);
// Set return to a value, not return to page
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Set up cookies. COOKIE_FILE_PATH defines where to save Cookie.
curl_setopt($ch, CURLOPT_COOKIEJAR, COOKIE_FILE_PATH);
curl_setopt($ch, CURLOPT_COOKIEFILE, COOKIE_FILE_PATH);
// Allow Self Signed Certs
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
// API Call
curl_setopt($ch, CURLOPT_URL, "https://" . CONTROLLER . ":" . PORT . "/" . CONTROLLER_ID . "/api/v2/hotspot/login");
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($loginInfo));
$res = curl_exec($ch);
$resObj = json_decode($res);
//Prevent CSRF. TOKEN_FILE_PATH defines where to save Token.
if ($resObj->errorCode == 0) {
// login successfully
self::setCSRFToken($resObj->result->token);
}
curl_close($ch);
}
private static function setCSRFToken($token)
{
$myfile = fopen(TOKEN_FILE_PATH, "w") or die("Unable to open file!");
fwrite($myfile, $token);
fclose($myfile);
return $token;
}
如果登入驗證成功，控制器將在HTTP正文中回覆以下JSON。請注意，result內的token是CSRF-Token，應新增到以下步驟的HTTP表頭中。
{
"errorCode": 0,
"msg": "Hotspot log in successfully.",
"result": {
"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
步驟12、13
成功登入後，Portal可以將用戶的身份驗證結果發送給： https://CONTROLLER:PORT/CONTROLLER_ID/api/v2/hotspot/extPortal/auth 使用HTTP POST的方式。
存在HTTP請求體的用戶訊息應被封裝成JSON格式，並且包含以下參數。
EAP： {"clientMac":"CLIENT_MAC","apMac":"AP_MAC","ssidName":"SSID_NAME","radioId":"RADIO_ID","site":"SITE_NAME","time":"EXPIRE_TIME","authType":"4"}
閘道器：
{"clientMac":"CLIENT_MAC","gatewayMac":"GATEWAY_MAC","vid":"VLAN_ID ","site":"SITE_NAME","time":"EXPIRE_TIME","authType":"4"}
|
time |
EXPIRE_TIME |
身份驗證過期時間，這裡的單位是microsecond。 |
EAP的PHP程式範本：
public static function authorize($clientMac, $apMac, $ssidName, $radioId, $milliseconds)
{
// Send user to authorize and the time allowed
$authInfo = array(
'clientMac' => $clientMac,
'apMac' => $apMac,
'ssidName' => $ssidName,
'radioId' => $radioId,
'time' => $milliseconds,
'authType' => 4
);
$csrfToken = self::getCSRFToken();
$headers = array(
'Content-Type: application/json',
'Accept: application/json',
'Csrf-Token: ' . $csrfToken
);
$ch = curl_init();
// post
curl_setopt($ch, CURLOPT_POST, TRUE);
// Set return to a value, not return to page
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Set up cookies.
curl_setopt($ch, CURLOPT_COOKIEJAR, COOKIE_FILE_PATH);
curl_setopt($ch, CURLOPT_COOKIEFILE, COOKIE_FILE_PATH);
// Allow Self Signed Certs
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
// API Call
curl_setopt($ch, CURLOPT_URL, "https://" . CONTROLLER . ":" . PORT . "/" . CONTROLLER_ID . "/api/v2/hotspot/login");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($authInfo));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo $res;
$resObj = json_decode($res);
if ($resObj->errorCode == 0) {
// authorized successfully
}
curl_close($ch);
}
public static function getCSRFToken()
{
$myfile = fopen(TOKEN_FILE_PATH, "r") or die("Unable to open file!");
$token = fgets($myfile);
fclose($myfile);
return $token;
}
如果身份驗證請求被接受，控制器將回覆以下JSON：
{
"errorCode": 0
}
注意：Portal應該能夠滿足以下兩個要求：
1、允許self-signed certificate，或者您將自己的HTTPS certificate上傳至控制器。
2、讀取並保存Cookie中的“TPEAP_SESSIONID” in Cookie，然後使用該Cookie發送身份驗證請求。
這篇faq是否有用?
您的反饋將幫助我們改善網站
