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 seu anfitrião e hoje vamos entrar nos detalhes 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 empresariais 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 sob o capô, como configurá-lo corretamente, onde estão as armadilhas comuns e por que razão sobrepor o Purple a uma implementação UniFi é a decisão arquitetural correta para locais que precisam de mais do que uma página de entrada básica.
Vamos a isto.
[MERGULHO TÉCNICO PROFUNDO - aproximadamente 5 minutos]
Primeiro, vamos compreender o que está realmente a acontecer 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 de costume. Mas o dispositivo é imediatamente colocado no que a UniFi chama de estado "pendente". Neste estado, o processo DNSmasq integrado do AP intercepta todas as consultas de DNS que o dispositivo faz, independentemente do servidor de DNS que o dispositivo pensa que está a utilizar. O AP redireciona todo o tráfego de DNS para si próprio.
Simultaneamente, o AP executa um redirecionador HTTP leve na porta 80. No momento em que o browser do convidado faz qualquer pedido HTTP - e esta é a palavra-chave, HTTP, não HTTPS - o redirecionador devolve um redirecionamento 302, enviando o browser para a página de entrada do Captive Portal. Este é o mecanismo que despoleta a notificação "Iniciar sessão no WiFi" nos dispositivos iOS e Android.
Agora, é aqui que a distinção entre o portal integrado e o portal externo se torna crítica. Com o UniFi Hotspot Portal integrado, a página de entrada é servida diretamente pela UniFi Network Application. É funcional, é rápida de configurar, mas é severamente limitada. Obtém autenticação básica por palavra-passe, vouchers e pagamentos Stripe. Não há captura de e-mails, nem início de sessão social, nem gestão de consentimento em conformidade com o GDPR, nem integração com CRM e sem análises significativas além da contagem de sessões.
Quando configura um Servidor de Portal Externo - que é a definição em que nos estamos a focar hoje - está a dizer ao controlador UniFi para redirecionar os convidados para uma aplicação web completamente separada. No nosso caso, trata-se do Purple. O URL que introduz no campo Servidor de Portal Externo torna-se o destino de todos esses redirecionamentos 302.
Aqui está o detalhe técnico importante sobre esse URL de redirecionamento. Quando o UniFi redireciona um convidado para o seu portal externo, ele anexa vários parâmetros de consulta ao URL. Estes incluem: o endereço MAC do AP, o endereço MAC do dispositivo do cliente, um carimbo de data/hora Unix, o URL original que o cliente estava a tentar aceder e o nome do SSID. O seu portal externo - Purple neste contexto - captura esses parâmetros, utiliza-os para identificar o dispositivo que se está a ligar, apresenta a Captive Portal adequada, trata da autenticação e, em seguida, faz uma chamada de API de volta à aplicação de rede UniFi 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 API REST oficial com autenticação baseada em chaves adequada. O endpoint de autorização é um pedido POST para a versão um da API de sites, direcionado ao 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 taxa em kilobits por segundo. Assim que o controlador recebe essa autorização, envia a instrução para o AP e o convidado passa de pendente a autorizado. O acesso à Internet é concedido.
Agora vamos falar sobre o Walled Garden, que o UniFi chama de Acesso Pré-Autorização. Esta é a lista de permissões de domínios e endereços IP que os convidados 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 se resolve. Se estiver a utilizar o início de sessão social - Facebook, Google, Microsoft - também precisa de adicionar os domínios de endpoint OAuth para esses fornecedores. Os endpoints de início de sessão da Google abrangem várias gamas de IP e vários domínios, incluindo accounts.google.com e oauth2.googleapis.com. A infraestrutura de início de sessão do Facebook também requer várias entradas. A documentação da Purple fornece uma lista atualizada das entradas exatas necessárias, e esta lista é mantida atualizada à medida que esses fornecedores atualizam a sua infraestrutura.
Existe uma particularidade crítica específica do UniFi que afeta muitas implementações. O redirecionador HTTP no AP apenas interpõe tráfego HTTP simples na porta 80. Os dispositivos modernos - iOS, Android, Windows, macOS - realizam todos 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 nenhum Captive Portal e simplesmente não mostrar o aviso de início de sessão.
A solução é garantir que o seu walled garden inclua os domínios de deteção de Captive Portal para os principais sistemas operativos e que o seu portal Purple esteja 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 de 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 auto-alojado - deve estar acessível a partir da infraestrutura da Purple para que os pedidos de autorização da API tenham sucesso. Se o seu controlador estiver numa rede privada atrás de NAT, terá de garantir que as portas de API relevantes estão acessíveis. Para controladores auto-alojados, esta é normalmente a porta 8443 para a API antiga, ou a porta HTTPS padrão 443 para a nova API 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 - aplicável 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 802.1X EAP padrão. Configura o perfil RADIUS em Settings, Networks, RADIUS Servers, e depois faz referência a esse perfil na configuração do seu SSID. A UniFi também suporta RADIUS sobre TLS, conhecido como RADSEC, a partir da versão 8.4, que encripta o tráfego RADIUS entre o AP e o servidor de autenticação. Para implementações multi-site 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 a lista de verificação prática de 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 IoT. A UniFi torna isto simples - crie uma rede dedicada em Settings, Networks, atribua-lhe um VLAN ID e associe o seu SSID de convidado a essa rede. Ative o isolamento de clientes na rede de convidados para impedir 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 e configure a UniFi para utilizar esse certificado. Isto resolve a maioria dos problemas de redirecionamento HTTPS.
Terceiro, configure o seu jardim murado (walled garden) com cuidado e teste-o. As entradas mínimas são: o domínio do seu portal Purple e respetivos 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 anteriormente - a cache de DNS e o estado da rede podem ocultar falhas no jardim murado durante os testes.
Quarto, para a integração da 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 principal. Se estiver na Network Application 9.1 ou posterior, 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 cuidadosamente a duração da sessã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 permanecer várias noites, configure durações de sessão adequadas nas definições do portal Purple, e certifique-se de 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 auto-sediado que não está acessível publicamente. Se a 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 da Purple antes de entrar em produção.
[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 Servidor de Portal Externo. A Network Application é executada no dispositivo.
Posso utilizar a Purple em múltiplos sites UniFi a partir de uma única conta Purple? Sim. A arquitetura multi-site da Purple foi concebida exatamente para isto. Cada local é configurado como um site separado na 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 da Purple. A documentação da Purple fornece as gamas de IP específicas.
E em relação ao WPA3? A UniFi suporta WPA3 Personal e WPA3 Enterprise. O mecanismo do Captive Portal funciona com WPA3 Personal em redes de convidados. O WPA3 Enterprise utiliza 802.1X e RADIUS, que é um fluxo de autenticação diferente.
[RESUMO E PRÓXIMOS PASSOS - aproximadamente 1 minuto]
Em resumo: implementar a 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 de Servidor de Portal Externo a apontar para o URL do seu portal Purple, criar um walled garden abrangente que cubra a infraestrutura da Purple e quaisquer fornecedores de 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 da 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. A Purple oferece-lhe uma plataforma de experiência de convidado orientada para a análise de dados e em conformidade com as normas, que se integra com o seu CRM, recolhe dados primários sob consentimento do GDPR, e fornece as análises de tráfego de visitantes e tempo de permanência de que os operadores dos locais e as equipas de marketing realmente precisam.
Se é um MSP ou um integrador de sistemas que implementa UniFi em grande escala, a gestão multi-site da Purple e as capacidades de white-label tornam-na a sobreposição certa para os seus clientes.
Para documentação detalhada de configuração, listas de IP de walled garden e guias de integração de API, visite purple.ai. Obrigado por ouvir.
