Exemplo de API e código para servidor de portal externo (Omada Controller 5.0.15 ou Superior)

Adequado para Omada Controller 5.0.15 ou superior.

Para Omada Controller 4.1.5 a 4.4.6, consulte a FAQ 2907

Para Omada Controller 2.6.0 a 3.2.17, consulte FAQ 2274

 

Comparado ao Omada SDN Controller v4, as principais mudanças são as seguintes:

1. Adiciona o ID do controlador à URL para login no ponto de acesso e envio de informações do cliente.

2. Adiciona o cabeçalho HTTP, que carrega o token CSRF.

 

Nota: As palavras-chave em negrito e itálico indicam parâmetros que são preenchidos automaticamente pelo EAP ou Gateway e devem ser corretamente identificados e entregues pelo seu Servidor de Portal Externo. Os significados dos parâmetros são declarados na primeira aparição.

 

Este documento descreve os requisitos para estabelecer um Servidor de Portal Externo (abreviadamente Portal). A imagem abaixo mostra o fluxo de dados entre os dispositivos de rede, o que pode ajudar a entender melhor o mecanismo de funcionamento.

Passos 1 e 2.

Quando um cliente está conectado à rede sem fio ou com fio vinculada a um Portal habilitado e tenta acessar a Internet, sua solicitação HTTP será interceptada por EAP ou Gateway, respectivamente, e então redirecionada para o Controlador Omada SDN (Controlador para abreviar) junto com as informações de conexão que são preenchidas automaticamente pelo EAP ou Gateway na URL.

Passos 3 e 4.

Depois disso, o cliente enviará uma solicitação HTTP GET com as informações de conexão ao Controlador e será redirecionado ao Portal pela resposta do Controlador com uma resposta HTTP com código de status 302. A resposta HTTP inclui a URL do Portal no campo de localização, bem como a conexão Informação.

URL para 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 para Gateway:

http(s):// PORTAL? clientMac= CLIENT_MAC &gatewayMac= GATEWAY_MAC &vid= VLAN_ID &t= TIME_SINCE_EPOCH &site= SITE_NAME &redirectUrl= LANDING_PAGE .

 

PORTAL		O endereço IP ou URL e o número da porta (se necessário) do Servidor de Portal Externo.
clienteMac	CLIENTE_MAC	Endereço MAC do cliente.
apMac	AP_MAC	Endereço MAC do EAP ao qual o cliente está conectado.
gatewayMac	GATEWAY_MAC	Endereço MAC do Gateway.
no	ID_VLAN	ID VLAN da rede com fio à qual o cliente está conectado.
NomeSSID	SSID_NOME	Nome do SSID ao qual o cliente está conectado
identificação de rádio	ID_DO_RÁDIO	ID de rádio da banda à qual o cliente está conectado, onde 0 representa 2,4G e 1 representa 5G.
site	NOME_DO_SITE	Nome do site.
redirecionarUrl	PÁGINA_DE_TERRENO	URL a ser visitada após autenticação bem-sucedida, que pode ser definida na Landing Page.
para	TEMPO_DE_SDE_ÉPOCA	A unidade aqui é microssegundo.

 

 

Passos 5 e 6.

O cliente enviará uma solicitação HTTP GET para o Portal com a URL acima. O Portal deve conseguir reconhecer e manter as informações de conexão na sequência de consulta da solicitação HTTP GET e retornar a página da web para autenticação.

 

Passos 7, 8 e 9.

O cliente enviará informações de autenticação para o Portal, que serão entregues ao servidor de autenticação e serão verificadas. Então, o servidor de autenticação retorna o resultado da autenticação para o Portal.

Você pode decidir como o Portal obtém as informações de autenticação do cliente e como o Portal se comunica com o servidor de autenticação, de acordo com suas próprias necessidades, o que está além do escopo deste artigo.

 

OBSERVAÇÃO: Na figura acima, o Portal e o servidor de autenticação são separados. Você pode instalá-los no mesmo servidor que desejar. O método de autenticação também fica a seu critério. Apenas se certifique de que o Portal saiba o resultado da autenticação do servidor de autenticação.

 

Passos 10 e 11.

Se a solicitação de autenticação for autorizada, o Portal deverá enviar as informações do cliente ao Controlador chamando sua API.

Primeiro, ele deve efetuar login no Controller enviando uma solicitação HTTP POST. A URL da solicitação deve ser https:// CONTROLLER : PORT / CONTROLLER_ID /api/v2/hotspot/login e deve conter as informações da conta do operador no formato JSON no corpo da mensagem HTTP: {"name": " OPERATOR_USERNAME ","password": " OPERATOR_PASSWORD "}.

Observe que a conta e a senha aqui são da operadora adicionada na interface do gerenciador de hotspot, e não da conta e senha da conta do controlador.

 

CONTROLADOR	Endereço IP ou URL do controlador Omada SDN.
PORTA	Porta HTTPS para gerenciamento do controlador Omada SDN Controller (8043 para software e 433 para OC por padrão, vá para Configurações --- Controlador --- Acesse Configuração para modificação).
ID_DO_CONTROLADOR	Identificador do Omada SDN Controller. Quando você acessa o controlador, o identificador será automaticamente adicionado à URL, da qual você obterá o identificador. Por exemplo, se a URL do seu controlador for https://localhost:8043/abcdefghijklmnopqrstuvwxyzabcdef/, então o CONTROLLER_ID será abcdefghijklmnopqrstuvwxyzabcdef.
OPERADOR_NOME_DE_USUÁRIO	Nome de usuário do operador do hotspot.
SENHA_DO_OPERADOR	Senha do operador do hotspot.

 

Modelo de código PHP:

 

public static function login()

{

$loginInfo = array(

"name" => OPERATOR_USER,

"password" => OPERATOR_PASSWORD

);

$headers = array(

"Content-Type: application/json",

"Accept: application/json"

);

$ch = curl_init();

// publicar

curl_setopt($ch, CURLOPT_POST, TRUE);

 

// Defina o retorno para um valor, não para a página

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

 

// Configurar cookies. COOKIE_FILE_PATH define onde salvar o cookie.

curl_setopt($ch, CURLOPT_COOKIEJAR, COOKIE_FILE_PATH);

curl_setopt($ch, CURLOPT_COOKIEFILE, COOKIE_FILE_PATH);

 

// Permitir certificados autoassinados

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);

 

// Chamada de API

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

//Evita CSRF. TOKEN_FILE_PATH define onde salvar o Token.

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

// login com sucesso

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;

}

Se a autenticação de login for aprovada, o Controller responderá com o seguinte JSON no corpo HTTP. Observe que o token dentro do resultado é o CSRF-Token, que deve ser adicionado ao HTTP Header das etapas seguintes.

{

"código de erro": 0,

"msg": "Login no hotspot com sucesso.",

"resultado": {

"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

}

}

Passos 12 e 13.

Após o login bem-sucedido, o Portal pode enviar o resultado da autenticação do cliente para https:// CONTROLLER : PORT / CONTROLLER_ID /api/v2/hotspot/extPortal/auth com o método HTTP POST .

As informações do cliente devem ser encapsuladas no formato JSON no corpo da mensagem HTTP e devem conter os seguintes parâmetros.

Para EAP: {" clientMac ":" CLIENT_MAC "," apMac ":" AP_MAC "," ssidName ":" SSID_NAME "," radioId ":" RADIO_ID "," site ":" SITE_NAME "," time ":" EXPIRE_TIME "," authType ":" 4 "}

Para Gateway:

{" clientMac ":" MAC_DO_CLIENTE "," gatewayMac ":" MAC_DO_GATEWAY "," vid ":" ID_DA_VLAN "," site ":" NOME_DO_SITE "," time ":" TEMPO_DE_EXPIRA "," authType ":" 4 "}

 

tempo

TEMPO_DE_VALIDADE

Tempo de expiração da autenticação. A unidade aqui é microssegundo.

 

Modelo de código PHP para EAP:

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

{

// Enviar usuário para autorizar e o tempo permitido

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

// publicar

curl_setopt($ch, CURLOPT_POST, TRUE);

 

// Defina o retorno para um valor, não para a página

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

 

// Configurar cookies.

curl_setopt($ch, CURLOPT_COOKIEJAR, COOKIE_FILE_PATH);

curl_setopt($ch, CURLOPT_COOKIEFILE, COOKIE_FILE_PATH);

 

// Permitir certificados autoassinados

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);

 

// Chamada de API

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) {

 

// autorizado com sucesso

}

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;

}

Se a solicitação de autenticação for aceita, o Controlador responderá com o seguinte JSON:

{

"errorCode": 0

}

 

Observação : o portal deve atender aos dois requisitos a seguir:

1. Permitir certificado autoassinado. Ou você fará upload do seu próprio certificado HTTPS para o Controller.

2. Leia e salve o “ TPEAP_SESSIONID ” no Cookie e envie a solicitação de autenticação com o Cookie.

* Para o Controller v5.11 e superior, o nome do Cookie é “ TPOMADA_SESSIONID ” .