Objetivo:
- Este tutorial tem como objetivo repassar informações sobre como configurar equipamentos UDM (Unifi Dream Machine) e UDM PRO (Unifi Dream Machine PRO) com o sistema MamboWiFi, o mesmo encontra-se em problema de homologação, ou seja, não está pronto para ser vendido ou ser colocado em produção em massa.
- As informações contidas nesse documento são privadas e devem ser mantidas internas do inicio ao fim da homologação.
Requisitos para a instalação:
- Possuir UniFi UDM ou UDM PRO com UnifiOS e Unifi Network acima da 7.5
- Possuir pelo menos uma antena na linha Unifi provisionada no UDM que será instalado o MamboWiFi.
- Licença Mambo WiFi e painel com o escopo Unifi Beta aplicado (solicitar aos devs o escopo de unifi beta antes da reunião de instalação).
- Conexão a internet.
- Liberar as portas 80, 443, 8080, 8880 para livre comunicação na rede do Unifi (O Unifi precisa dessas portas para funcionar o hotspot)
- IP Público DEDICADO NA INTERFACE (O UDM não pode estar atrás de um NAT/port forward. Ainda não é possível utilizar com redirecionamento de portal ou VPN).
- Criar usuário administrador na UDM, user: suportemambo_integracao / senha: MI8tMNsk3lldiyx
Vídeo explicando
Informações importantes sobre o status de homologação UDM:
O UDM não esta pronto para ser colocado em produção, isso porque existe a implantação da homologação por parte do time de desenvolvimento, todo o processo de homologação por parte do suporte foi feita, porém existem responsabilidades que não cabem ao time realizar, uma delas é a programação e a infraestrutura que vai manter essa programação, logo sem isso pronto, não tem como instalar algo sem ser por "gambiarras" (que nem deveriam ser cogitadas).
Todo o desenho, processo, escopo etc da homologação do sistema MamboWiFi com UDM está nesse documento AQUI.
O documento com todo o processo, testes e informações foi repassado ao Guilherme no dia 04/10/2023 as 15:21, onde o mesmo confirmou que recebeu e manteve documentários dentro do mesmo (que já foram respondidos).
Qual passo estamos da homologação?
Após todo o processo de bancada do time de suporte, agora necessário o time de desenvolvimento implementar todo o escopo desenhado no documento mencionado (link dele de novo aqui), sem essa implementação, NÃO É POSSÍVEL implementar nenhum novo UDM em produção, sendo restrito somente para os clientes que querem testar e participar de um processo de homologação (que é o caso da Sicredi), pois se abrirmos para POC, venda etc num momento de homologação, além de não dar vazão para o mesmo, a estrutura ainda não está pronta para vendas e POCs.
Qual a diferença entre UNIFI Controller e UDM para a instalação de hotspot?
Unifi Controller possui gerenciamento de multi-site, ou seja, é possível configurar o hotspot a partir da importação de site (técnica usada pelo suporte em casos de não acesso via ftp), no caso do UDM, o mesmo NÃO POSSUI gerenciamento de multi-site, ou seja, sem esse gerenciamento de site, não possui a opção de importar de outra controladora.
Outra diferença é que o UDM não possui Guest Control (igual a versão 7.4 e superior a unifi controller), ou seja, não permite aplicar a opção "Override Template", essa opção habilita a gestão da pasta onde no unifi, se gerencia os arquivos .html para redirecionar para o hotspot, impossibilitando de criar o redirecionamento igual utilizamos no unifi controller, por conta disso, que foi desenhado o novo escopo para incluir o UDM
Gambiarra... (NÃO USAR, documentado somente para documentar...):
Sim, existe uma gambiarra, porém ela é impossível de ser usada, funciona assim:
- O UnifiOS (sistema de roda no UDM) não possui gerenciador de multi-site
- O UnifiOS (sistema de roda no UDM) não possui a opção de override template, para habilitar a pasta de gerenciamento de hotspot para modificar/incluir arquivos .html
- Com a falta de multi-site, não é possível importar um site de outra controladora já com a configuração de hotspot pronta (quando importamos um site, tanto as configurações, tanto os arquivos .html são importados)
- Com a falta da opção de override template no UDM, não é possível, via FTP, encontrar a pasta de gerenciamento dos arquivos .html
- Porém existe uma gambiarra (que não deve ser usada) que é subir um BACKUP de uma controladora que já possui as configurações de hotspot, por exemplo, eu subo uma controladora na mesma versão de network da UDM em minha maquina, configuro ela normalmente com os arquivos .html, SSID etc para hotspot e exporto o BACKUP do mesmo para IMPORTAR no UDM.
- O problema disso é que todas as configurações do UDM são apagadas e substituídas pela configuração importada, ou seja, fazer esse método pode gerar um gigantesco problema, pois qualquer configuração de SSH, SNMP, REDE, DNS etc vai ser apagada e sobrescrita.
- Outro problema é que fazer a configuração dessa maneira, precisa da intervenção do desenvolvimento, em nossos testes, o Evandro (Dev) precisou criar um escopo separado para os testes, colocando hard coded o IP da controladora, sua porta, usuário e senha super admin criado na UDM
- Ou seja, esse método foi usado somente para TESTAR as opções de autenticação e não deve ser usado em produção com nenhum cliente;
Configuração:
Estamos a espera do time de desenvolvimento para seguir com o manual de configuração, sem a definição final do escopo, IP de apontamento, e testes, não podemos cravar como será a configuração, todo e qualquer escopo desenho pode ser modificado para o funcionamento da plataforma com UDM.
=========================================================================
Segue abaixo o desenho do escopo e todo o dossiê, também disponível AQUI via docs:
Homologação de Unifi Ubiquiti API V2 para MamboWiFi (Unifi Controller e UDM)
OBJETIVO
Este documento tem como objetivo mostrar o novo projeto de modelo de autenticação via API da Unifi Ubiquiti, mostrando os detalhes, fluxos, testes etc.
Trazer um serviço de autenticação de melhor qualidade para clientes com Unifi, facilitar a instalação do serviço, padronização de mercado e gerar compatibilidade com UDM e UDM Pro (Dream Machine da Ubiquiti).
O modelo atual
A controladora da Unifi, hospedada ou em CloudKey era compatível com o sistema da MamboWiFi realizando o fluxo de modificação de index.html em sua pasta raiz de gerenciamento de site (Linux: /usr/lib/unifi/data/sites || Windows: C:\Users\SeuUsuario\Ubiquiti UniFi\data\sites), porém a partir da versão 7.4 da Unifi, esse recurso não está mais disponível nativamente, é necessário fazer uma “gambiarra” de exportar um site criado em uma versão anterior e importar na controladora, gerando um trabalho considerável. Outro detalhe importante é que a Ubiquiti pode retirar essa “gambiarra” a qualquer momento, forçando a MamboWiFi correr atrás de uma nova versão de integração.
O novo modelo
A nova versão de autenticação consiste em usar o recurso de External Portal Server, localizado em Hotspot Manager > External Portal Server nas versões acima da 7.4 ou em configure > Guest Portal > External Portal Server nas versões abaixo de 7.4.
O novo modelo continua exigindo um ip público na controladora, contendo também um usuário super admin criado para a integração na controladora.
(obs: A interface de hotspot da Unifi Controller e UDM/UDM Pro a partir da versão 7.4 são iguais).
Fluxo de autenticação
O campo de apontamento de External Portal Server dentro do Unifi só permite utilizar um endereço IPV4, ou seja, não é possível apontar um endereço de domínio como qualquer outro fabricante, com isso, vamos precisar criar um fluxo de autenticação utilizando um IP público ipv4 hospedado em nossa infraestrutura para autenticar usuários de Unifi.
Utilizar o IP 152.70.220.32
O exemplo de diagrama de autenticação é o seguinte:
1 - O cliente se conecta em um SSID que possui a configuração de hotspot habilitada no Unifi.
2 - A antena que distribui o sinal SSID repassa para a controladora/UDM Unifi gerenciar a autenticação do cliente.
3 - A controladora/UDM repassa para o cliente qual o endereço que vai ser acesso para a autenticação.
4 - Como vamos ter um servidor com IP único e não domínio, é necessário criar um redirecionamento (com html, php etc) para o domínio do cliente, detectando o mesmo por alguma variável, pode ser pelo IP da controladora do cliente ou mac address da antena.
5 - Em algum banco de dados nosso, consultamos essas informações e direcionamos para a URL de mambowifi adequada para o cliente, por exemplo, se a autenticação for para luisagner.mambowifi.com, é nesse cruzamento de dados dentro do banco que irá definir qual URL vai redirecionar.
6 - Usuário preenche os dados e solicita autenticação na interface web (padrão como qualquer outro).
7 - API da Mambo faz um request para a controladora do cliente (necessário ter um usuário e senha com super admin na controladora e ser repassado para a mambowifi), autorizando ou não a autenticação.
8 - A controladora libera o cliente por X minutos (valor a ser definido), terminando assim o fluxo de autenticação com um START do request AAA.
Problemas encontrados nesse fluxo:
Necessário escrever um código para redirecionamento para o painel mambowifi correto, pois é impossível termos um ip para cada cliente unifi, o que é viável é ter um ipv4 na OCI ou AWS por exemplo somente para as autenticações Unifi e no código aplicar o redirecionamento.
Esse fluxo de redirecionamento vai precisar ser estudado, pois para identificar de onde vem a solicitação, pode ser necessário que o cliente cadastre a sua controladora (ip/domínio) no painel administrativo da mambo, parecido com o que acontece com old mambo.
Testes de bancada
Foram feitos diversos testes para validar a autenticação utilizando esse método, tanto em Unifi Controller, quanto em UDM, os resultados foram satisfatórios. Em ambos, o apontamento foi feito para 68.183.98.217, onde possui um servidor apache hospedado na digitalocean (nuvem de testes), dentro deste apache, tem hospedado um arquivo index.html, é ele que faz o redirecionamento para o captive externo, além disso, esse arquivo precisa estar dentro pastas e subpastas, simulando o caminho de um index.html dentro do unifi:
Isso ocorre pois ao redirecionar, o Unifi complementa o url de IP com as informações de pasta, o que criei no apache foi em hard coded, será necessário criar um método padronizado para unifi na criação de site ou criar alguma automatização para detecção do mesmo.
EX de url ao ser redirecionado:
http://68.183.98.217/guest/s/default/?ap=00:27:22:f2:15:c9&id=48:49:c7:03:ae:
4e&t=1696255504&url=http://teste.com
Abaixo, segue o index.html utilizado para os testes:
<script>
var redirectUrl = "https://unifibeta.mambowifi.com/unifi";
</script>
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Carregando...</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
.loading-unifi {
width: 100vw;
height: 100vh;
display: flex;
justify-content: center;
align-items: center;
}
.loading-unifi > img {
width: 50px;
height: 50px;
}
</style>
</head>
<body>
<div class="loading-unifi">
<img src="/bundles/admin/frontend/images/loading-unifi.gif" alt="">
</div>
<script>
var ap = 'fc:ec:da:0e:91:2b';
var mac = '6a:c9:5b:d5:53:53';
var ssid = 'teste_mambo';
var url = '';
// var authUrl = 'https' + '//' + '143.198.60.172' + ':' + '8443' + '/' + 'index.html';
//authUrl = authUrl.replace("index.htmlindex.html", "index.html");
window.location.replace(redirectUrl + "?ap_mac=" + ap + "&client_mac=" + mac + "&ssid=" + ssid + "&url=" + url + "&login_url=https://177.22.80.238:443/guest/s/default/index.html");
//console.log(authUrl);
</script>
</body>
</html>
Perceba que:
Na linha 2, é feito o direcionamento para o URL mambowifi, provavelmente, será necessário tratar essa variável antes com o redirecionador mencionado no documento.
As linhas 8 e 27 são somente exibição, não afetam o funcionamento.
As linhas 30, 31, 32 estão em hard coded por conta dos testes em bancada, também é necessário verificar e tratar com variável
A linha 36 é qual é o redirecionamento para o cliente, ou seja, a formação de url, o mesmo também possui hard coded, no campo “login_url”, de forma estática, está um controlador que utilizamos para testes, esse mesmo controlador também precisa ser tratado via variável ou com o sistema de redirecionamento mencionado no documento.
Segue como é declarado as variáveis de AP, MAC SSID E URL segundo a documentação da Ubiquiti:
var ap = '<unifi var="ap_mac" />';
var mac = '<unifi var="mac" />';
var ssid = '<unifi var="ssid" />';
var url = '';
O método antigo de redirecionamento de usuário era feito dessa forma:
var authUrl = window.location.protocol + '//' + window.location.host + window.location.pathname + 'auth.html';
window.location.replace(redirectUrl + "?ap_mac=" + ap + "&client_mac=" + mac + "&ssid=" + ssid + "&url=" + url + "&login_url=" + authUrl);
Conclusão
O objetivo desse documento foi trazer riqueza de detalhes sobre o novo projeto de autenticação de Unifi, mostrando quais são seus pontos de vantagens em base ao modelo atual, em quais sistemas da ubiquiti podemos utilizar, além dos relatos de testes de bancada e códigos utilizados dentro deste escopo, é importante salientar que os códigos, exemplos de como o fluxo deve funcionar e outros detalhes podem ser modificados, ou seja, se for necessário para o funcionamento, podemos verificar a possibilidade de modificação de alguma etapa.
Reforço também que essa será, provavelmente, a principal forma de autenticação de Unifi controllers e UDM, sendo necessário testes antes de qualquer integração em produção no serviço mambowifi, para isso, o time de suporte fica a disposição para ajudar nos testes, utilizando tanto unifi controller, quanto UDM.
Objetivos futuros
Realizar testes com VPN (openvpn Client para comunicação com os servidores da mambowifi)
Testar com redirecionamento de portas (port forward)
Testar com DDNS.