API e exemplo de código para servidor de portal externo (Omada Controller 2.5.4 ou inferior)

Adequado para Omada Controller 2.5.4 ou inferior.

Para versões do Omada Controller entre 2.6.0 e 3.2.17, consulte o FAQ2274

Para versões do Omada Controller entre 4.1.5 e 4.4.6, consulte o FAQ2907

Para versões do Omada Controller 5.0.15 ou superior, consulte o FAQ3231

Este documento descreve os requisitos para estabelecer um servidor de portal externo. Para saber como configurar o External Portal Server, consulte o FAQ-896 (etapa 2 da seção 5).

A imagem abaixo descreve o fluxo de dados entre o cliente sem fio, o dispositivo EAP, o controlador EAP, o servidor de portal e o servidor de autenticação, o que pode ajudá-lo a entender melhor os requisitos para estabelecer um servidor de portal externo.

1. O cliente sem fio é conectado ao SSID no qual a autenticação do portal está habilitada e tenta acessar a Internet. O dispositivo EAP interceptará a requisição HTTP do cliente e a redirecionará para o controlador EAP. O cliente enviará então uma requisição GET ao controlador EAP com a query string “cid=client_mac&ap=ap_mac&ssid=ssid_name&t=time_since_epoch&rid=Radio_id” na URL, de acordo com a resposta HTTP recebida do EAP. (Passo 1 e Passo 2)
2. O controlador EAP redireciona o cliente para o servidor de portal externo enviando uma resposta HTTP com o código de status 302 Found. A resposta HTTP com este código fornecerá adicionalmente a URL do servidor de portal externo no campo "location". A URL também contém a query string. Para o controlador EAP 2.2.3 ou superior, a URL é http://portal_server_ip?cid=client_mac&ap=ap_mac&ssid=ssid_name&t=time_since_epoch&rid=Radio_id&site=site_name. (Passo 3 e Passo 4)

O significado dos parâmetros está listado na Tabela 1: Explicação dos Parâmetros.

3. O cliente enviará uma requisição GET ao servidor de portal externo usando a URL mencionada acima. (Passo 5)
4. O servidor de portal externo deve ser capaz de interceptar e manter um registro dos parâmetros na query string da requisição GET e retornar uma página web com o formulário de autenticação para o cliente sem fio. (Passo 6)
5. As informações de autenticação do cliente sem fio serão enviadas ao servidor de portal, e o servidor de portal enviará as informações ao servidor de autenticação (Passo 7 e Passo 8). No entanto, como o servidor de portal obtém as informações de autenticação do cliente e como ele se comunica com o servidor de autenticação depende de sua própria implementação, o que está fora do escopo deste artigo.
6. O servidor de autenticação verifica as informações e retorna o resultado ao servidor de portal. (Passo 9)

NOTA: Neste exemplo, o servidor de portal e o servidor de autenticação estão separados. Mas eles podem ser instalados no mesmo servidor, se desejar. O método de autenticação também depende de você. Apenas certifique-se de que o servidor de portal saiba quando a autenticação foi aprovada.

7. Se a autenticação for bem-sucedida, o servidor de portal deve enviar as informações do cliente ao controlador EAP chamando a API do controlador. Primeiro, ele deve fazer o login no controlador EAP enviando uma requisição POST. A URL da requisição será https://controller_server_ip:https_port/login e carregará os dados “name=username_do_controller&password=senha_do_controller” usando o formato JSON no corpo da mensagem HTTP.

Exemplo PHP para Login:

private static function login()
{
    $ch = curl_init();
    // post
    curl_setopt($ch, CURLOPT_POST, TRUE);
    // Definir retorno para um valor, não retornar 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, CONTROLLER_SERVER . "/login");
    curl_setopt($ch, CURLOPT_POSTFIELDS, "name=" . CONTROLLER_USER . "&password=" . CONTROLLER_PASSWORD);
    curl_exec($ch);
    curl_close($ch);
}

(Passo 10)

8. Se o servidor de portal fez o login no controlador com sucesso, ele enviará as informações do cliente para https://controller_server_ip:https_port/extportal/site_name/auth usando o método POST. Os dados das informações podem ser representados pelo formato JSON e devem conter estes parâmetros: “cid=client_mac&ap=ap_mac&ssid=ssid_name&t=time_since_epoch&rid=Radio_id&site=site_name&time=expire_time”.

Exemplo PHP para Autorização:

private static function authorize($cid,$ap,$ssid,$rid,$t,$seconds,$site)
{
    // Enviar usuário para autorizar e o tempo permitido
    $authInfo = array(
        'cid' => $cid,
        'ap' => $ap,
        'ssid' => $ssid,
        'rid' => $rid,
        't' => $t,
        'time' => $seconds
    );
    $ch = curl_init();
    // post
    curl_setopt($ch, CURLOPT_POST, TRUE);
    // Definir retorno para um valor
    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, CONTROLLER_SERVER . "/extportal/" . $site . "/auth");
    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);
}

(Passo 11)

O significado destes parâmetros é o mesmo da Tabela 1. O parâmetro time aqui é o número de segundos antes que a autenticação do cliente expire. Este parâmetro é definido pelo servidor de portal.

9. O controlador EAP retorna uma mensagem JSON: {"success": [true/false], "message":" return information"} ao servidor de portal após processar as informações fornecidas. Como o servidor de portal lida com a mensagem JSON depende de sua implementação. Por fim, o servidor de portal deve fazer o logout do controlador EAP enviando um POST para https://controller_server_ip:https_port/

Exemplo PHP para Logout:

private static function logout()
{
    $ch = curl_init();
    // Post
    curl_setopt($ch, CURLOPT_POST, TRUE);
    // Definir retorno para um valor, não retornar 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, CONTROLLER_SERVER . "/logout");
    curl_exec($ch);
    curl_close($ch);
}

(Passo 12 e Passo 13)