Ver transcrição do podcast
Captive Portal for Ubiquiti UniFi - A Purple Technical Briefing
[INTRODUÇÃO E CONTEXTO - aproximadamente 1 minuto]
Bem-vindo à série Purple Technical Briefing. Eu sou o vosso anfitrião e hoje vamos analisar os aspetos específicos da implementação de um captive portal externo na infraestrutura Ubiquiti UniFi - uma das plataformas de rede mais amplamente implementadas em ambientes de hotelaria, retalho e empresas a nível global.
Se é um gestor de TI, arquiteto de rede ou integrador de sistemas que trabalha com UniFi Cloud Gateways, Dream Machines ou a UniFi Network Application, este episódio é para si. Vamos analisar exatamente como o mecanismo do portal externo funciona nos bastidores, como o configurar corretamente, quais são as armadilhas comuns e por que razão sobrepor a Purple a uma implementação UniFi é a decisão de arquitetura correta para locais que precisam de mais do que uma página de boas-vindas básica.
Vamos a isso.
[ANÁLISE TÉCNICA DETALHADA - aproximadamente 5 minutos]
Primeiro, vamos compreender o que acontece realmente quando um dispositivo convidado se liga a um SSID UniFi que tem um captive portal ativado.
Quando um dispositivo convidado se associa ao seu SSID de convidados, o Access Point UniFi atribui-lhe um endereço IP via DHCP, como habitualmente. Mas o dispositivo é imediatamente colocado no que a UniFi chama de estado "pendente". Neste estado, o processo DNSmasq integrado no AP intercepta todas as consultas DNS que o dispositivo faz, independentemente do servidor DNS que o dispositivo pense estar a utilizar. O AP redireciona todo o tráfego DNS para si próprio.
Simultaneamente, o AP executa um redirecionador HTTP leve na porta 80. No momento em que o navegador do convidado faz qualquer pedido HTTP - e esta é a palavra-chave, HTTP, não HTTPS - o redirecionador envia um redirecionamento 302, enviando o navegador para a página de boas-vindas do captive portal. Este é o mecanismo que aciona a notificação "Iniciar sessão no WiFi" em dispositivos iOS e Android.
Ora, é aqui que a distinção entre portal integrado e portal externo se torna crítica. Com o UniFi Hotspot Portal integrado, a página de boas-vindas é disponibilizada diretamente pela UniFi Network Application. É funcional, é rápido de configurar, mas é bastante limitado. Dispõe de autenticação básica por palavra-passe, vouchers e pagamentos Stripe. Não há recolha de e-mails, início de sessão através de redes sociais, gestão de consentimento em conformidade com o GDPR, integração com CRM nem análises significativas além da contagem de sessões.
Quando configura um External Portal Server - que é a definição em que nos focamos hoje - está a dizer ao controlador UniFi para redirecionar os convidados para uma aplicação web completamente separada. No nosso caso, a Purple. O URL que introduz no campo External Portal Server torna-se o destino de todos esses redirecionamentos 302.
Aqui está o pormenor técnico importante sobre esse URL de redirecionamento. Quando a UniFi redireciona um visitante para o seu portal externo, anexa vários parâmetros de consulta ao URL. Estes incluem: o endereço MAC do AP, o endereço MAC do dispositivo cliente, um carimbo de data/hora Unix, o URL original que o cliente tentava aceder e o nome do SSID. O seu portal externo — a Purple neste contexto — captura esses parâmetros, utiliza-os para identificar o dispositivo que se está a ligar, apresenta a splash page apropriada, trata da autenticação e, em seguida, faz uma chamada de API de volta para a UniFi Network Application para autorizar esse endereço MAC.
Essa chamada de API é o aperto de mão crucial. A partir da UniFi Network Application 9.1 e posterior, existe uma REST API oficial com autenticação adequada baseada em chave. O endpoint de autorização é um pedido 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 utilização de dados em megabytes e limites de velocidade em kilobits por segundo. Assim que o controlador recebe essa autorização, envia a instrução para o AP e o visitante passa de pendente a autorizado. O acesso à Internet é concedido.
Agora vamos falar sobre o Walled Garden, que a UniFi designa por Pre-Authorization Access. Trata-se da lista de permissões de domínios e endereços IP que os visitantes podem aceder antes de serem autenticados. É essencial e é uma das fontes mais comuns de configuração incorreta.
No mínimo, o seu walled garden precisa de incluir o nome de domínio totalmente qualificado do seu portal Purple e os endereços IP ou gamas CIDR para os quais a infraestrutura da Purple aponta. Se estiver a utilizar o login social — Facebook, Google, Microsoft — também precisa de adicionar os domínios de endpoint OAuth desses fornecedores. Os endpoints de login da Google abrangem várias gamas de IP e vários domínios, incluindo accounts.google.com e oauth2.googleapis.com. A infraestrutura de login do Facebook exige igualmente várias entradas. A documentação da Purple fornece uma lista atualizada das entradas exatas necessárias, e esta lista é mantida em dia à medida que esses fornecedores atualizam a sua infraestrutura.
Existe uma particularidade crítica específica da UniFi que afeta muitas implementações. O redirecionador HTTP no AP apenas interseta tráfego HTTP simples na porta 80. Os dispositivos modernos — iOS, Android, Windows, macOS — realizam todos a deteção de Captive Portal baseada em HTTPS. Os dispositivos Apple acedem a captive.apple.com através de HTTPS. Os dispositivos Android acedem a connectivitycheck.gstatic.com. Se esses pedidos HTTPS não obtiverem uma resposta específica, o dispositivo pode decidir que não existe um Captive Portal e simplesmente não mostrar o aviso de início de sessão.
A solução consiste em garantir que o seu walled garden inclui os domínios de deteção de Captive Portal para os principais sistemas operativos, e que o seu portal Purple está acessível através de HTTPS com um certificado SSL válido e fidedigno. Os certificados autoassinados causarão avisos de segurança no navegador que impedem o carregamento do portal. Isto é inegociável para implementações em produção.A outra consideração específica da UniFi é a acessibilidade do controlador. A UniFi Network Application - quer esteja a ser executada num Cloud Gateway, num Cloud Key ou num servidor alojado localmente - deve estar acessível a partir da infraestrutura da Purple para que as chamadas de autorização da API tenham sucesso. Se o seu controlador estiver numa rede privada atrás de NAT, precisará de garantir que as portas de API relevantes estão acessíveis. Para controladores alojados localmente, esta é normalmente a porta 8443 para a API antiga, ou a porta HTTPS padrão 443 para a API mais recente introduzida na versão 9.1. A documentação de suporte da Purple especifica os intervalos de IP exatos que necessitam de acesso de entrada ao seu controlador.
Para autenticação baseada em RADIUS - que é relevante quando está a implementar a Purple juntamente com SSIDs WPA2-Enterprise ou WPA3-Enterprise em vez do modelo de SSID de convidado aberto - o servidor RADIUS integrado da UniFi suporta métodos EAP 802.1X padrão. Configura o perfil RADIUS em Definições, Redes, Servidores RADIUS e, em seguida, associa esse perfil à configuração do seu SSID. A UniFi também suporta RADIUS sobre TLS, conhecido como RADSEC, a partir da versão 8.4, o qual encripta o tráfego RADIUS entre o AP e o servidor de autenticação. Para implementações em vários locais onde o tráfego RADIUS atravessa a internet pública, o RADSEC é fortemente recomendado.
[RECOMENDAÇÕES DE IMPLEMENTAÇÃO E ERROS COMUNS — aproximadamente 2 minutos]
Deixe-me apresentar-lhe a lista de verificação prática para implementação que eu recomendaria a qualquer cliente que esteja a implementar a Purple na UniFi.
Primeiro, a segmentação de rede. O seu SSID de convidado deve estar numa VLAN dedicada, isolada das suas redes corporativas e de IoT. A UniFi torna isto simples - crie uma rede dedicada em Definições, Redes, atribua-lhe um ID de VLAN e associe o seu SSID de convidado a essa rede. Ative o isolamento de clientes na rede de convidados para evitar o tráfego entre convidados.
Segundo, o controlador deve ter um FQDN válido e um certificado SSL fidedigno. Não dependa do endereço IP. Utilize um nome de domínio adequado, obtenha um certificado Let's Encrypt ou comercial para o mesmo e configure a UniFi para utilizar esse certificado. Isto resolve a maioria dos problemas de redirecionamento HTTPS.
Terceiro, configure o seu walled garden com cuidado e teste-o. As entradas mínimas são: o domínio do seu portal Purple e os seus intervalos de IP, os domínios de deteção de Captive Portal para iOS, Android e Windows, e quaisquer domínios de fornecedores OAuth que esteja a utilizar. Teste com um dispositivo que nunca se tenha ligado à rede antes - a cache de DNS e o estado da rede podem ocultar falhas no walled garden durante os testes.
Quarto, para a integração de API, utilize uma conta de administrador local dedicada na UniFi Network Application com as permissões mínimas necessárias. Não utilize as suas credenciais de administrador principais. Se estiver na Network Application 9.1 ou superior, utilize o novo mecanismo de chave de API em Control Plane, Integrations - é 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 predefinida da sessão de convidado da UniFi pode ser de apenas oito horas. Para implementações no setor da hotelaria, onde os hóspedes podem ficar várias noites, configure durações de sessão adequadas nas definições do portal Purple e garanta que essas durações são transmitidas corretamente na chamada de autorização da API.
O erro mais comum que vejo é a implementação num controlador autoalojado que não está publicamente acessível. Se o Purple não conseguir aceder ao seu controlador para autorizar convidados, o portal irá carregar, mas a autenticação falhará silenciosamente. Verifique sempre a conectividade da API a partir da infraestrutura do Purple antes de entrar em funcionamento.
[PERGUNTAS E RESPOSTAS RÁPIDAS - aproximadamente 1 minuto]
Isto funciona na UniFi Dream Machine Pro? Sim. Todas as consolas UniFi OS - UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max - suportam a configuração do External Portal Server. A Network Application é executada no dispositivo.
Posso utilizar o Purple em vários sites UniFi a partir de uma única conta Purple? Sim. A arquitetura multi-site do Purple foi concebida exatamente para isso. Cada local é configurado como um site separado no Purple, mapeado para o site UniFi correspondente.
Preciso de abrir portas de firewall no gateway UniFi? Precisa de garantir que o tráfego da VLAN de convidados consegue aceder ao domínio do portal Purple na porta 443. A porta da API do controlador também precisa de estar acessível a partir dos servidores do Purple. A documentação do Purple fornece as gamas de IP específicas.
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 utiliza 802.1X e RADIUS, o que constitui um fluxo de autenticação diferente.
[RESUMO E PRÓXIMOS PASSOS - aproximadamente 1 minuto]
Em resumo: implementar o Purple como um Captive Portal externo na UniFi é uma integração bem suportada e arquitetonicamente sólida. Os passos principais são: configurar o seu SSID de convidado com a opção External Portal Server a apontar para o URL do seu portal Purple, construir um walled garden abrangente que cubra a infraestrutura do Purple e quaisquer fornecedores OAuth que esteja a utilizar, garantir que o seu controlador UniFi tem um certificado SSL válido e está acessível a partir dos servidores de API do Purple, e configurar durações de sessão adequadas para o seu tipo de local.
O caso de negócio é simples. O portal integrado da UniFi oferece-lhe uma splash page. O Purple oferece-lhe uma plataforma de experiência de convidado orientada para a análise de dados e em conformidade com a regulamentação, que se integra com o seu CRM, recolhe dados primários ao abrigo do consentimento do GDPR e fornece as análises de tráfego e tempo de permanência que os operadores de espaços e as equipas de marketing realmente precisam.
Se é um MSP ou integrador de sistemas a implementar UniFi à escala, a gestão multi-site e as capacidades de white-label do Purple tornam-no a sobreposição certa para os seus clientes.
Para obter documentação de configuração detalhada, listas de IP de walled garden e guias de integração de API, visite purple.ai. Obrigado por ouvir.
