API и примеры кода для внешнего портального сервера - External Portal Server (контроллер Omada v6.2.10 или выше)

Содержание

Введение

Требования

Настройка

Заключение

Введение

API контроллера Omada обеспечивает бесшовную интеграцию между контроллером TP-Link Omada и сторонними приложениями, позволяя разработчикам автоматизировать аутентификацию, контроль доступа клиентов, мониторинг сети и задачи управления.

В этом руководстве представлены спецификации API и примеры кода для интеграции внешнего портального сервера с контроллером Omada версии 6.2.10.

Что нового в версии 6.2.10

По сравнению с контроллером Omada SDN версии 5.x, API внешнего портала содержит следующие изменения:

• Удаление устаревших параметров.
• Добавление новых необязательных параметров для повышения гибкости и настройки.

Примечание: Параметры, выделенные жирным курсивом, автоматически заполняются точкой доступа EAP или шлюзом. Ваш внешний портальный сервер должен сохранять и возвращать эти параметры при взаимодействии с контроллером Omada. Определения параметров приведены при их первом упоминании в этом руководстве.

Для контроллера Omada версий от 5.0.15 до 6.2.0 обратитесь к FAQ3231

Для контроллера Omada версий от 4.1.5 до 4.4.6 обратитесь к FAQ2907

Для контроллера Omada версий от 2.6.0 до 3.2.17 обратитесь к FAQ2274

Требования

• Контроллер Omada (программный или аппаратный контроллер, версия 6.2.10 или выше)

Настройка

В этом разделе описывается, как настроить внешний портальный сервер и интегрировать его с контроллером Omada версии 6.2.10. Перед реализацией API важно понять, как обмениваются запросы аутентификации между клиентом, контроллером Omada, сетевыми устройствами (EAP или шлюзами) и внешним портальным сервером.

Следующая схема иллюстрирует поток данных в процессе аутентификации через внешний портал.

Шаги 1 и 2. Доступ клиента и начальное перенаправление

Когда клиент подключается к проводной или беспроводной сети с включённой портальной аутентификацией и пытается получить доступ к интернету, HTTP-запрос клиента перехватывается сетевым устройством:

• Для беспроводных клиентов запрос перехватывается точкой доступа EAP.
• Для проводных клиентов запрос перехватывается шлюзом.

Затем EAP или шлюз перенаправляет клиента на контроллер, добавляя информацию о подключении клиента в виде параметров запроса в URL.

Шаги 3 и 4. Контроллер перенаправляет клиента на портал

Клиент отправляет HTTP GET-запрос, содержащий информацию о подключении, на контроллер.

Контроллер отвечает HTTP-перенаправлением 302, направляя клиента на настроенный внешний портальный сервер. URL перенаправления содержит как адрес портала, так и информацию о подключении клиента.

Формат URL для EAP

http(s)://ПОРТАЛ?clientMac=MAC_КЛИЕНТА&clientIp=IP_КЛИЕНТА&apMac=MAC_AP&ssidName=ИМЯ_SSID&t=ВРЕМЯ_С_ЭПОХИ&radioId=ID_РАДИО&site=ID_ОБЪЕКТА&redirectUrl=ЦЕЛЕВАЯ_СТРАНИЦА.

Формат URL для шлюза

http(s)://ПОРТАЛ?clientMac=MAC_КЛИЕНТА&gatewayMac=MAC_ШЛЮЗА&vid=ID_VLAN&t=ВРЕМЯ_С_ЭПОХИ&site=ID_ОБЪЕКТА&redirectUrl=ЦЕЛЕВАЯ_СТРАНИЦА.

Справочник параметров URL

В следующем примере показана страница конфигурации целевой страницы в контроллере Omada версии 6.2.10.

Шаги 5 и 6. Портал получает запрос клиента

Клиент отправляет HTTP GET-запрос на портал с указанным выше URL. Портал должен уметь распознавать и сохранять информацию о подключении в строке запроса HTTP GET-запроса и возвращать веб-страницу для аутентификации.

Шаги 7, 8 и 9. Аутентификация клиента

Клиент отправляет свои учётные данные для аутентификации на портал.

Портал передаёт учётные данные на сервер аутентификации для проверки. После завершения аутентификации сервер аутентификации возвращает результат аутентификации на портал.

Механизм аутентификации и взаимодействие между порталом и сервером аутентификации зависят от реализации и выходят за рамки данного документа.

ПРИМЕЧАНИЕ: Портал и сервер аутентификации могут быть развёрнуты на отдельных серверах или на одном сервере. Независимо от модели развертывания, портал должен иметь возможность получать результат аутентификации клиента.

Шаги 10 и 11. Портал выполняет вход в контроллер

Если аутентификация успешна, портал должен сначала войти в контроллер, прежде чем авторизовать клиента.

Отправьте HTTP POST-запрос по адресу:

Для локальных контроллеров: https://КОНТРОЛЛЕР:ПОРТ/ID_КОНТРОЛЛЕРА/api/v2/hotspot/login

Для облачных контроллеров: https://КОНТРОЛЛЕР/ID_КОНТРОЛЛЕРА/api/v2/hotspot/login

Тело запроса должно содержать учётные данные оператора хотспота в формате JSON:

{"name": "ИМЯ_ОПЕРАТОРА","password": "ПАРОЛЬ_ОПЕРАТОРА"}.

Примечание: Учётные данные должны принадлежать учётной записи оператора хотспота, созданной в контроллере, а не учётной записи администратора контроллера.

Параметры описаны ниже.

Шаблон кода PHP:

public static function login()

{

$loginInfo = array(

"name" => ИМЯ_ОПЕРАТОРА,

"password" => ПАРОЛЬ_ОПЕРАТОРА

);

$headers = array(

"Content-Type: application/json",

"Accept: application/json"

);

$ch = curl_init();

// post

curl_setopt($ch, CURLOPT_POST, TRUE);

// Установить возврат значения, не выводить на страницу

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Настроить куки. COOKIE_FILE_PATH определяет, где сохранять Cookie.

curl_setopt($ch, CURLOPT_COOKIEJAR, COOKIE_FILE_PATH);

curl_setopt($ch, CURLOPT_COOKIEFILE, COOKIE_FILE_PATH);

// Разрешить самоподписанные сертификаты

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);

// Вызов API

curl_setopt($ch, CURLOPT_URL, "https://" . КОНТРОЛЛЕР . ":" . ПОРТ . "/" . ID_КОНТРОЛЛЕРА . "/api/v2/hotspot/extPortal/auth");

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($loginInfo));

$res = curl_exec($ch);

$resObj = json_decode($res);

//Предотвращение CSRF. TOKEN_FILE_PATH определяет, где сохранять токен.

if ($resObj->errorCode == 0) {

// вход выполнен успешно

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;

}

Если аутентификация входа выполнена успешно, контроллер ответит следующим JSON в теле HTTP-ответа. Обратите внимание, что токен внутри result — это CSRF-токен, который должен быть добавлен в HTTP-заголовок следующих шагов.

{

"errorCode": 0,

"msg": "Hotspot log in successfully.",

"result": {

"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

}

}

Шаги 12 и 13. Авторизация клиента

После успешного входа портал может отправить результат аутентификации клиента по адресу https://КОНТРОЛЛЕР:ПОРТ/ID_КОНТРОЛЛЕРА/api/v2/hotspot/extPortal/auth с помощью метода HTTP POST.

Информация о клиенте должна быть инкапсулирована в формате JSON в теле HTTP-сообщения и должна содержать следующие параметры.

Для EAP: {"clientMac":"MAC_КЛИЕНТА","clientIp":"IP_КЛИЕНТА","apMac":"MAC_AP","ssidName":"ИМЯ_SSID","radioId":"ID_РАДИО","time":"ВРЕМЯ_ИСТЕЧЕНИЯ","authType":"4","originUrl":"",
"totalTrafficLimitBytes":"ОГРАНИЧЕНИЕ_ТРАФИКА_БАЙТ","downloadRateLimitKbps":"ОГРАНИЧЕНИЕ_СКОРОСТИ_ЗАГРУЗКИ_КБИТ_С","uploadRateLimitKbps":"ОГРАНИЧЕНИЕ_СКОРОСТИ_ОТДАЧИ_КБИТ_С"}

Для шлюза: {"clientMac":"MAC_КЛИЕНТА","clientIp":"IP_КЛИЕНТА","gatewayMac":"MAC_ШЛЮЗА","vid":"ID_VLAN","time":"ВРЕМЯ_ИСТЕЧЕНИЯ","authType":"4",
"totalTrafficLimitBytes":"ОГРАНИЧЕНИЕ_ТРАФИКА_БАЙТ","downloadRateLimitKbps":"ОГРАНИЧЕНИЕ_СКОРОСТИ_ЗАГРУЗКИ_КБИТ_С","uploadRateLimitKbps":"ОГРАНИЧЕНИЕ_СКОРОСТИ_ОТДАЧИ_КБИТ_С"}

Шаблон кода PHP для EAP:

public static function authorize($clientMac, $apMac, $ssidName, $radioId, $milliseconds)

{

// Отправить пользователя на авторизацию и разрешённое время

$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);

// Установить возврат значения, не выводить на страницу

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Настроить куки.

curl_setopt($ch, CURLOPT_COOKIEJAR, COOKIE_FILE_PATH);

curl_setopt($ch, CURLOPT_COOKIEFILE, COOKIE_FILE_PATH);

// Разрешить самоподписанные сертификаты

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);

// Вызов API

curl_setopt($ch, CURLOPT_URL, "https://" . КОНТРОЛЛЕР . ":" . ПОРТ . "/" . 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) {

// авторизация выполнена успешно

}

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

}

Требования к порталу

Реализация портала должна соответствовать следующим требованиям:

1. Поддерживать самоподписанные HTTPS-сертификаты или установить доверенный HTTPS-сертификат на контроллере.
2. Сохранять сессионный cookie, возвращаемый контроллером, и включать его в последующие запросы аутентификации.
   • Для версий контроллера ранее 5.11 имя cookie — TPEAP_SESSIONID.
   • Для версий 5.11 и новее имя cookie — TPOMADA_SESSIONID.

Заключение

Это руководство содержит API и примеры кода для внешнего портального сервера (контроллер Omada 6.2.10). Если вам нужна дополнительная информация об OpenAPI контроллера Omada, обратитесь в службу технической поддержки TP-Link для получения дальнейшей помощи.

Чтобы узнать больше о каждой функции и настройке, посетите Домашнюю страницу поддержки и скачайте или ознакомьтесь с руководством для вашего продукта.