API and Code Sample for External Portal Server (Omada Controller 4.1.5 to 4.4.6)

EAP225-Wall( V2 ) , EAP660 HD( V1 ) , AP9665 , EAP225-Outdoor( V1 ) , EAP245( V3 ) , EAP265 HD( V1 ) , EAP110( V4 ) , EAP230-Wall( V1 ) , EAP235-Wall( V1 ) , EAP620 HD( V1 ) , EAP225( V3 ) , EAP115( V4 ) , EAP110-Outdoor( V3 ) , Omada Software Controller( V4 V5 ) , EAP115-Wall( V1 )
Recent updates may have expanded access to feature(s) discussed in this FAQ. Visit your product's support page, select the correct hardware version for your device, and check either the Datasheet or the firmware section for the latest improvements added to your product. Please note that product availability varies by region, and certain models may not be available in your region.
Suitable for Omada Controller 4.1.5 to 4.4.6.
For Omada Controller 5.0.15 or above, please refer to FAQ 3231
For Omada Controller 2.6.0 to 3.2.17, please refer to FAQ 2274
For Omada Controller 2.5.4 or below, please refer to FAQ 928
Note: The keywords in Bold Italics indicate parameters that are automatically filled by EAP or Gateway, and should be correctly identified and delivered by your External Portal Server. The meanings of the parameters are stated in the first appearance.
This document outlines the requirements to establish an External Portal Server (Portal for short). The below picture depicts the data flow among the network devices, which may help better understand the working mechanism.
Steps 1 and 2.
When a client is connected to the wireless or wired network bound with a Portal enabled and attempts to access the Internet, its HTTP request will be intercepted by EAP or Gateway, respectively, and then redirected to the Omada SDN Controller (Controller for short) along with the connection information that is filled automatically by EAP or Gateway in the URL.
Steps 3 and 4.
After that, the client will send HTTP GET request with the connection information to Controller and be redirected to the Portal by Controller’s reply with an HTTP response with status code 302. The HTTP response includes the Portal’s URL in the location field as well as the connection information.
URL for EAP: 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 for Gateway: http(s)://PORTAL?clientMac=CLIENT_MAC&gatewayMac=GATEWAY_MAC&vid=VLAN_ID&t=TIME_SINCE_EPOCH&site=SITE_NAME&redirectUrl=LANDING_PAGE.
PORTAL |
The IP address or URL, and Port number (if necessary) of the External Portal Server. |
|
clientMac |
CLIENT_MAC |
MAC address of the client. |
apMac |
AP_MAC |
MAC address of the EAP to which the client is connected. |
gatewayMac |
GATEWAY_MAC |
MAC address of the Gateway. |
vid |
VLAN_ID |
VLAN ID of the wired network to which the client is connected. |
ssidName |
SSID_NAME |
Name of the SSID to which the client is connected |
radioId |
RADIO_ID |
Radio ID of the band to which the client is connected, where 0 represents 2.4G and 1 represents 5G. |
site |
SITE_NAME |
Site name. |
redirectUrl |
LANDING_PAGE |
URL to visit after successful authentication, which can be set in the Landing Page. |
t |
TIME_SINCE_EPOCH |
Unit here is microsecond. |
Steps 5 and 6.
The client will send HTTP GET request to Portal with the URL above. Portal must be able to recognize and keep the connection information in the query string of the HTTP GET request and return the web page for authentication.
Steps 7, 8 and 9.
The client will submit authentication information to Portal, which will be delivered to the authentication server, and be verified. Then the authentication server returns the authentication result to Portal.
You can decide how Portal obtains the client's authentication information and how Portal communicates with the authentication server, according to your own requirements, which is beyond the scope of this article.
NOTE: In the figure above, the Portal and authentication server are separated. You can install them on the same server as you wish. The authentication method is also up to you. Just make sure Portal can know the authentication result from the authentication server.
Steps 10 and 11.
If the authentication request is authorized, Portal should send the client information to the Controller by calling its API.
First, it must log in Controller by sending an HTTP POST request. The request’s URL should be https://CONTROLLER:PORT/api/v2/hotspot/login and it should carry the operator account information in JSON format in the HTTP message body: “name=OPERATOR_USERNAME&password=OPERATOR_PASSWORD”.
The calling interface is POST /api/v2/hotspot/login. The passing parameter is JSON: {“name”:”xxx”, “password”:”xxx”}. Note that the account and password here are the operator added in the hotspot manager interface, rather than the account and password for the controller account.
CONTROLLER |
IP address or URL of Omada SDN Controller. |
PORT |
HTTPS Port for Controller Management of Omada SDN Controller (8043 for software, and 433 for OC by default, go to Settings --- Controller --- Access Config for modification). |
OPERATOR_USERNAME |
Username of the hotspot operator. |
OPERATOR_PASSWORD |
Password of the hotspot operator. |
PHP Code Template:
private static function login()
{
$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, CONTROLLER.":".PORT."/api/v2/hotspot/login” );
curl_setopt($ch, CURLOPT_POSTFIELDS, "name=" . OPERATOR_USER ."&password=" . OPERATOR_PASSWORD);
$res = curl_exec($ch);
$resObj = json_decode($res);
//Prevent CSRF. TOKEN_FILE_PATH defines where to save Token.
if($resObj->success == true){
self::setCSRFToken($resObj->value);
}
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;
}
If the login authentication passes, the Controller will reply with the following JSON in the HTTP body.
{
"errorCode": 0,
"msg": "Hotspot log in successfully.",
"result": {
"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
Steps 12 and 13.
After successful login, Portal can send the client authentication result to https://CONTROLLER:PORT/api/v2/hotspot/extPortal/auth?token=CSRFToken with HTTP POST method. The client information should be encapsulated in JSON format and must contain the following parameters.
For EAP: “clientMac=CLIENT_MAC&apMac=AP_MAC&ssidName=SSID_NAME &radioId=RADIO_ID&site=SITE_NAME&time=EXPIRE_TIME&authType =4”
For Gateway: “clientMac=CLIENT_MAC&gatewayMac=GATEWAY_MAC&vid=VLAN_ID&site=SITE_NAME&time=EXPIRE_TIME&authType =4”
time |
EXPIRE_TIME |
Authentication Expiration time. Unit here is microsecond. |
PHP Code Template for EAP:
private static function authorize($clientMac,$apMac,$ssidName,$radioId,$ milliseconds,$site)
{
// Send user to authorize and the time allowed
$authInfo = array(
'clientMac' => $clientMac,
'apMac' => $apMac,
''ssidName => $ssidName,
'radioId ' => $radioId,
'time' => $milliseconds,
‘authType’ => 4
);
$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
$csrfToken = self::getCSRFToken();
curl_setopt($ch, CURLOPT_URL, CONTROLLER.":". PORT."/api/v2/hotspot/extPortal/auth/”.”?token=".$csrfToken);
$data = json_encode($authInfo);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($authInfo));
$res = curl_exec($ch);
$resObj = self::resultConvert($res);
if($resObj['success'] == false){
echo $res;
}
curl_close($ch);
}
private static function resultConvert($json)
{
$json = str_replace(array('{','}',':',','),array('[{" ',' }]','":',',"'),$json);
function cb_quote($v)
{
return '"'.trim($v[1]).'"';
}
$newJSON=preg_replace_callback("~\"(.*?)\"~","cb_quote", $json);
$res = json_decode($newJSON, true)[0];
return $res;
}
private static function getCSRFToken(){
$myfile = fopen(TOKEN_FILE_PATH, "r") or die("Unable to open file!");
$token = fgets($myfile);
fclose($myfile);
return $token;
}
If the authentication request is accepted, the Controller will reply with the following JSON:
{ "errorCode": 0 }
Note: Portal should be able to meet the following two requirements:
1. Allow self-signed certificate. Or you will upload your own HTTPS certificate to Controller.
2. Read and save the “TPEAP_SESSIONID” in Cookie, and send authentication request with the Cookie.
Câu hỏi thường gặp này có hữu ích không?
Phản hồi của bạn giúp cải thiện trang web này.
Mối quan tâm của bạn với bài viết này là gì?
- Không hài lòng với sản phẩm
- Quá phức tạp
- Tiêu đề khó hiểu
- Không áp dụng cho tôi
- Quá mơ hồ
- Khác
Cảm ơn
Chúng tôi đánh giá cao phản hồi của bạn.
Nhấp vàođây để liên hệ với bộ phận hỗ trợ kỹ thuật của TP-Link.
This website uses cookies to improve website navigation, analyze online activities and have the best possible user experience on our website. You can object to the use of cookies at any time. You can find more information in our privacy policy . Don’t show again
This website uses cookies to improve website navigation, analyze online activities and have the best possible user experience on our website. You can object to the use of cookies at any time. You can find more information in our privacy policy . Don’t show again
Basic Cookies
Những cookie này cần thiết để trang web hoạt động và không thể tắt trong hệ thống của bạn.
TP-Link
accepted_local_switcher, tp_privacy_base, tp_privacy_marketing, tp_smb-select-product_scence, tp_smb-select-product_scenceSimple, tp_smb-select-product_userChoice, tp_smb-select-product_userChoiceSimple, tp_smb-select-product_userInfo, tp_smb-select-product_userInfoSimple, tp_top-banner, tp_popup-bottom, tp_popup-center, tp_popup-right-middle, tp_popup-right-bottom, tp_productCategoryType
Livechat
__livechat, __lc2_cid, __lc2_cst, __lc_cid, __lc_cst, CASID
Youtube
id, VISITOR_INFO1_LIVE, LOGIN_INFO, SIDCC, SAPISID, APISID, SSID, SID, YSC, __Secure-1PSID, __Secure-1PAPISID, __Secure-1PSIDCC, __Secure-3PSID, __Secure-3PAPISID, __Secure-3PSIDCC, 1P_JAR, AEC, NID, OTZ
Analysis and Marketing Cookies
Cookie phân tích cho phép chúng tôi phân tích các hoạt động của bạn trên trang web của chúng tôi nhằm cải thiện và điều chỉnh chức năng trang web của chúng tôi.
Các cookie tiếp thị có thể được các đối tác quảng cáo của chúng tôi thiết lập thông qua trang web của chúng tôi để tạo hồ sơ về sở thích của bạn và hiển thị cho bạn các quảng cáo có liên quan trên các trang web khác.
Google Analytics & Google Tag Manager
_gid, _ga_<container-id>, _ga, _gat_gtag_<container-id>
Google Ads & DoubleClick
test_cookie, _gcl_au
Meta Pixel
_fbp
Crazy Egg
cebsp_, _ce.s, _ce.clock_data, _ce.clock_event, cebs
lidc, AnalyticsSyncHistory, UserMatchHistory, bcookie, li_sugr, ln_or