API and Code Sample for External Portal Server (Omada Controller 5.0.15 or above)

適用於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.

步驟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"}.

留意此處帳號和密碼是在熱點管理界面中新增的操作員帳號，而不是控制器帳號的帳號和密碼。

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"}

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發送身份驗證請求。