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

Suitable for Omada Controller 5.0.15 or above.

For Omada Controller 4.1.5 to 4.4.6, please refer to FAQ 2907

For Omada Controller 2.6.0 to 3.2.17, please refer to FAQ 2274

Compared to Omada SDN Controller v4, the main changes are as follows:

1. Add Controller ID to the URL for hotspot login and client information submission.

2. Add the HTTP header, which carries the CSRF Token.

Note: The keywords in Bold Italics indicate parameters that are automatically filledpopulated by the EAP or Gateway and should be correctly identified and delivered by your External Portal Server. The meanings of the parameters are statedoutlined in the first appearancechart later in this article.

This document outlines the requirements to establish an External Portal Server (Portal for short). The picture below 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 with a Portal enabled and attempts to access the Internet, its HTTP request will be intercepted by the EAP or Gateway, respectively, and will then be redirected to the Omada SDN Controller (Controller for short) along with the connection information that is populated automatically by the EAP or Gateway in the URL.

Steps 3 and 4.

Next, the client will send an HTTP GET request with the connection information to the Controller and be redirected to the Portal by the Controller’s reply with an HTTP response using 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.

Steps 5 and 6.

The client will send an HTTP GET request to the Portal with the URL above. The 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 the Portal, which will be delivered to the authentication server, and be verified. Then, the authentication server returns the authentication result to the Portal.

You can decide how the Portal obtains the client's authentication information and how the Portal communicates with the authentication server, depending to your specific network 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 if desired. The authentication method is also up to you. Just make sure the Portal is able to receive the authentication result from the authentication server.

Steps 10 and 11.

If the authentication request is authorized, the Portal should send the client information to the Controller by calling its API.

First, it must log in to the Controller by sending an HTTP POST request. The request’s URL should be https://CONTROLLER:PORT/CONTROLLER_ID/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"}.

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.

PHP Code Template:

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;

}

If the login authentication is successful, the Controller will reply with the following JSON in the HTTP body. Note that the token inside result is the CSRF-Token, which should be added to the HTTP Header of the following steps.

{

"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/CONTROLLER_ID/api/v2/hotspot/extPortal/auth with HTTP POST method.

The client information should be encapsulated in JSON format in the HTTP message body, 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"}

PHP Code Template for EAP:

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;

}

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.

* For Controller v5.11 and above, the Cookie name is “TPOMADA_SESSIONID”.