Ver transcrição do podcast
Captive Portal para Ubiquiti UniFi - Um Informativo Técnico da Purple
[INTRODUÇÃO E CONTEXTO - aproximadamente 1 minuto]
Boas-vindas à série de Informativos Técnicos da Purple. Eu sou o seu apresentador e hoje vamos entrar nos detalhes da implantação de um Captive Portal externo na infraestrutura Ubiquiti UniFi - uma das plataformas de rede mais implantadas globalmente em ambientes de hotelaria, varejo e corporativos.
Se você é gerente de TI, arquiteto de rede ou integrador de sistemas trabalhando com UniFi Cloud Gateways, Dream Machines ou o UniFi Network Application, este episódio é para você. Vamos explicar exatamente como o mecanismo de portal externo funciona nos bastidores, como configurá-lo corretamente, quais são as armadilhas comuns e por que sobrepor o Purple a uma implantação UniFi é a decisão arquitetônica certa para locais que precisam de mais do que uma página de login básica.
Vamos começar.
[APROFUNDAMENTO TÉCNICO - aproximadamente 5 minutos]
Primeiro, vamos entender o que realmente acontece quando um dispositivo de convidado se conecta a um SSID UniFi que tem um Captive Portal habilitado.
Quando um dispositivo de convidado se associa ao seu SSID de convidados, o Access Point UniFi atribui a ele um endereço IP via DHCP normalmente. Mas o dispositivo é imediatamente colocado no que a UniFi chama de estado "pendente". Nesse estado, o processo DNSmasq integrado do AP intercepta todas as consultas DNS que o dispositivo faz, independentemente de qual servidor DNS o dispositivo pensa que está usando. O AP redireciona todo o tráfego de DNS para si mesmo.
Simultaneamente, o AP executa um redirecionador HTTP leve na porta 80. No momento em que o navegador do convidado faz qualquer solicitação HTTP - e esta é a palavra-chave, HTTP, não HTTPS - o redirecionador responde com um redirecionamento 302, enviando o navegador para a tela de autenticação do Captive Portal. Este é o mecanismo que aciona a notificação "Conectar-se ao WiFi" em dispositivos iOS e Android.
Agora, é aqui que a distinção entre portal integrado e portal externo se torna crítica. Com o UniFi Hotspot Portal integrado, a tela de autenticação é servida diretamente pelo UniFi Network Application. É funcional, rápido de configurar, mas é severamente limitado. Você obtém autenticação básica por senha, vouchers e pagamentos via Stripe. Não há captura de e-mail, login social, gerenciamento de consentimento da GDPR, integração com CRM e nenhuma análise significativa além da contagem de sessões.
Quando você configura um Servidor de Portal Externo - que é a configuração na qual estamos focados hoje - você está dizendo ao controlador UniFi para redirecionar os convidados para um aplicativo web completamente separado. No nosso caso, esse aplicativo é o Purple. A URL que você insere no campo do Servidor de Portal Externo torna-se o destino de todos esses redirecionamentos 302.
Aqui está o detalhe técnico importante sobre essa URL de redirecionamento. Quando o UniFi redireciona um visitante para o seu portal externo, ele anexa vários parâmetros de consulta à URL. Estes incluem: o endereço MAC do AP, o endereço MAC do dispositivo cliente, um carimbo de data/hora Unix, a URL original que o cliente estava tentando acessar e o nome do SSID. Seu portal externo - Purple neste contexto - captura esses parâmetros, usa-os para identificar o dispositivo de conexão, apresenta a tela de login apropriada, lida com a autenticação e, em seguida, faz uma chamada de API de volta para o UniFi Network Application para autorizar esse endereço MAC.
Essa chamada de API é o aperto de mão crucial. A partir do UniFi Network Application 9.1 e posterior, há uma API REST oficial com autenticação baseada em chave adequada. O endpoint de autorização é uma solicitação POST para a versão um da API de sites, visando o ID de cliente específico, com um corpo JSON que pode especificar limites de tempo em minutos, limites de uso de dados em megabytes e limites de taxa em kilobits por segundo. Assim que o controlador recebe essa autorização, ele envia a instrução para o AP, e o visitante passa de pendente para autorizado. O acesso à Internet é concedido.
Agora vamos falar sobre o Jardim Murado, que o UniFi chama de Pre-Authorization Access. Esta é a lista de permissões de domínios e endereços IP que os visitantes podem acessar antes de se autenticarem. É essencial e é uma das fontes mais comuns de configuração incorreta.
No mínimo, seu jardim murado precisa incluir o nome de domínio totalmente qualificado do seu portal Purple e os endereços IP ou intervalos CIDR para os quais a infraestrutura do Purple se resolve. Se você estiver usando login social - Facebook, Google, Microsoft - você precisa adicionar os domínios de endpoint OAuth para esses provedores também. Os endpoints de login do Google abrangem vários intervalos de IP e vários domínios, incluindo accounts.google.com e oauth2.googleapis.com. A infraestrutura de login do Facebook exige de forma semelhante várias entradas. A documentação do Purple fornece uma lista mantida das entradas exatas necessárias, e esta lista é mantida atualizada à medida que esses provedores atualizam sua infraestrutura.
Há uma peculiaridade crítica específica do UniFi que atrapalha muitas implantações. O redirecionador HTTP no AP intercepta apenas o tráfego HTTP simples na porta 80. Dispositivos modernos - iOS, Android, Windows, macOS - todos realizam detecção de Captive Portal baseada em HTTPS. Dispositivos Apple acessam captive.apple.com via HTTPS. Dispositivos Android acessam connectivitycheck.gstatic.com. Se essas solicitações HTTPS não receberem uma resposta específica, o dispositivo pode decidir que não há um Captive Portal e simplesmente falhar em mostrar a tela de login.
A solução é garantir que seu jardim murado inclua os domínios de detecção de Captive Portal para os principais sistemas operacionais, e que seu portal Purple esteja acessível via HTTPS com um certificado SSL válido e confiável. Certificados autoassinados causarão avisos de segurança do navegador que impedem o carregamento do portal. Isso é inegociável para implantações de produção.
A outra consideração específica do UniFi é a acessibilidade do controlador. O UniFi Network Application - quer esteja sendo executado em um Cloud Gateway, em um Cloud Key ou em um servidor auto-hospedado - deve ser acessível a partir da infraestrutura do Purple para que as chamadas de autorização de API sejam bem-sucedidas. Se o seu controlador estiver em uma rede privada atrás de NAT, você precisará garantir que as portas de API relevantes estejam acessíveis. Para controladores auto-hospedados, essa é normalmente a porta 8443 para a API herdada, ou a porta HTTPS padrão 443 para a API mais recente introduzida na versão 9.1. A documentação de suporte do Purple especifica os intervalos de IP exatos que precisam de acesso de entrada ao seu controlador.
Para autenticação baseada em RADIUS - o que é relevante quando você está implantando o Purple junto com SSIDs WPA2-Enterprise ou WPA3-Enterprise em vez do modelo de SSID de visitante aberto - o servidor RADIUS integrado do UniFi oferece suporte aos métodos padrão EAP 802.1X. Você configura o perfil RADIUS em Configurações, Redes, Servidores RADIUS e, em seguida, faz referência a esse perfil na configuração do seu SSID. O UniFi também suporta RADIUS sobre TLS, conhecido como RADSEC, a partir da versão 8.4, que criptografa o tráfego RADIUS entre o AP e o servidor de autenticação. Para implantações em vários locais onde o tráfego RADIUS atravessa a internet pública, o RADSEC é altamente recomendado.
[RECOMENDAÇÕES DE IMPLEMENTAÇÃO E ARMADILHAS - aproximadamente 2 minutos]
Deixe-me fornecer a lista de verificação prática de implementação que eu passaria para qualquer cliente que estivesse implantando o Purple no UniFi.
Primeiro, a segmentação de rede. O seu SSID de visitante deve estar em uma VLAN dedicada, isolada das suas redes corporativas e de IoT. O UniFi torna isso simples - crie uma rede dedicada em Configurações, Redes, atribua a ela um ID de VLAN e associe seu SSID de visitante a essa rede. Ative o isolamento de cliente na rede de visitantes para evitar o tráfego de visitante para visitante.
Segundo, o controlador deve ter um FQDN válido e um certificado SSL confiável. Não dependa do endereço IP. Use um nome de domínio adequado, obtenha um certificado Let's Encrypt ou comercial nele e configure o UniFi para usar esse certificado. Isso resolve a maioria dos problemas de redirecionamento HTTPS.
Terceiro, crie seu walled garden com cuidado e teste-o. As entradas mínimas são: o domínio do seu portal Purple e seus intervalos de IP, os domínios de detecção de Captive Portal para iOS, Android e Windows, e quaisquer domínios de provedor OAuth que você esteja usando. Teste com um dispositivo que nunca se conectou à rede antes - o cache de DNS e o estado da rede podem mascarar falhas no walled garden durante os testes.
Quarto, para a integração de API, use uma conta de administrador local dedicada no UniFi Network Application com as permissões mínimas necessárias. Não use suas credenciais de administrador principais. Se você estiver no Network Application 9.1 ou posterior, use o novo mecanismo de chave de API em Painel de Controle, Integrações - é mais seguro e não requer autenticação baseada em credenciais.
Em quinto lugar, considere a duração da sessão com atenção. A expiração padrão da sessão de convidados da UniFi pode ser de apenas oito horas. Para implantações em hotelaria onde os hóspedes podem passar várias noites, configure durações de sessão adequadas nas configurações do portal Purple e garanta que essas durações sejam passadas corretamente na chamada de autorização da API.
O erro mais comum que vejo é a implantação em um controlador auto-hospedado que não está acessível publicamente. Se a Purple não conseguir alcançar seu controlador para autorizar os convidados, o portal carregará, mas a autenticação falhará silenciosamente. Sempre verifique a conectividade da API a partir da infraestrutura da Purple antes de entrar em operação.
[PERGUNTAS E RESPOSTAS RÁPIDAS - aproximadamente 1 minuto]
Isso funciona no UniFi Dream Machine Pro? Sim. Todos os consoles UniFi OS - UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max - suportam a configuração de Servidor de Portal Externo. O Network Application é executado no próprio dispositivo.
Posso usar o Purple em vários sites UniFi a partir de uma única conta Purple? Sim. A arquitetura multi-site da Purple foi projetada exatamente para isso. Cada local é configurado como um site separado no Purple, mapeado para o site UniFi correspondente.
Preciso abrir portas de firewall no gateway UniFi? Você precisa garantir que o tráfego da VLAN de convidados possa alcançar o domínio do portal Purple na porta 443. A porta da API do controlador também precisa estar acessível a partir dos servidores da Purple. A documentação da Purple fornece os intervalos de IP específicos.
E quanto ao WPA3? A UniFi suporta WPA3 Personal e WPA3 Enterprise. O mecanismo de Captive Portal funciona com WPA3 Personal em redes de convidados. O WPA3 Enterprise usa 802.1X e RADIUS, que é um fluxo de autenticação diferente.
[RESUMO E PRÓXIMOS PASSOS - aproximadamente 1 minuto]
Resumindo: implantar o Purple como um Captive Portal externo na UniFi é uma integração bem suportada e arquitetonicamente sólida. As principais etapas são: configurar o seu SSID de convidados com a opção de Servidor de Portal Externo apontando para a URL do seu portal Purple, criar um walled garden abrangente que cubra a infraestrutura da Purple e quaisquer provedores de OAuth que você esteja usando, garantir que seu controlador UniFi tenha um certificado SSL válido e esteja acessível a partir dos servidores de API da Purple, e configurar durações de sessão adequadas para o seu tipo de local.
O caso de negócios é direto. O portal UniFi integrado oferece a você uma página de entrada. A Purple oferece uma plataforma de experiência de convidados baseada em análise e pronta para conformidade, que se integra ao seu CRM, captura dados primários sob o consentimento da GDPR e fornece as análises de fluxo de pessoas e tempo de permanência que os operadores de locais e equipes de marketing realmente precisam.
Se você é um MSP ou integrador de sistemas que implanta UniFi em escala, o gerenciamento multi-site e os recursos de white label da Purple tornam ela a solução complementar ideal para os seus clientes.
Para documentação detalhada de configuração, listas de IPs de walled garden e guias de integração de API, visite purple.ai. Obrigado por ouvir.
