Guia de configuração do captive portal UniFi

Captive Portal para Ubiquiti UniFi - Um Briefing Técnico da Purple [INTRODUÇÃO E CONTEXTO - aproximadamente 1 minuto] Bem-vindo à série de Briefings Técnicos da Purple. Eu sou o seu anfitrião e hoje vamos analisar em detalhe as especificidades 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 corporativos 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 com a UniFi Network Application, este episódio é para si. Vamos explicar exatamente como o mecanismo do portal externo funciona sob o capô, como configurá-lo corretamente, quais são as armadilhas comuns e por que razão a sobreposição da Purple a uma implementação UniFi é a decisão arquitetónica certa para recintos que precisam de mais do que uma página de splash básica. Vamos a isso. [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 habitualmente. 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 DNS que o dispositivo faz, independentemente do servidor DNS que o dispositivo pensa que está a utilizar. O AP redireciona todo o tráfego DNS para si próprio. Simultaneamente, o AP corre 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 responde com um redirecionamento 302, enviando o navegador para a página de splash 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 splash é servida diretamente pela UniFi Network Application. É funcional, é rápido de configurar, mas é severamente limitado. Dispõe apenas de autenticação básica por palavra-passe, vouchers e pagamentos Stripe. Não há recolha de emails, não há login social, não há gestão de consentimento GDPR, não há integração com CRM e não há 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, essa aplicação é a Purple. O URL que introduz no campo Servidor de Portal Externo torna-se o destino para todos esses redirecionamentos 302. Eis o detalhe técnico importante sobre esse URL de redirecionamento. Quando o 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 timestamp 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 splash page adequada, lida com a 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 passo crucial de comunicação. A partir da UniFi Network Application 9.1 e posterior, existe uma REST API oficial com autenticação adequada baseada em chaves. 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 taxa 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 o 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 estarem 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 requer 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 do UniFi que afeta muitas implementações. O redirecionador HTTP no AP apenas intercepta 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 nenhum Captive Portal e simplesmente não apresentar o ecrã 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 correr num Cloud Gateway, num Cloud Key ou num servidor alojado localmente - tem de estar acessível a partir da infraestrutura da Purple para que os pedidos de autorização de API sejam bem-sucedidos. 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 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 a 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 visitante aberto - o servidor RADIUS integrado da UniFi suporta métodos EAP 802.1X 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, o qual encripta o tráfego RADIUS entre o AP e o servidor de autenticação. Para implementações em múltiplos locais onde o tráfego RADIUS atravessa a internet pública, o RADSEC é fortemente recomendado. [IMPLEMENTATION RECOMMENDATIONS & PITFALLS - aproximadamente 2 minutos] Permita-me apresentar-lhe a lista de verificação prática de implementação que eu analisaria com qualquer cliente que estivesse a implementar a Purple em UniFi. Primeiro, a segmentação de rede. O seu SSID de visitante tem de 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 visitante a essa rede. Ative o isolamento de clientes na rede de visitantes para impedir o tráfego entre visitantes. Segundo, o controlador tem de 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, crie a sua walled garden com cuidado e teste-a. As entradas mínimas são: o domínio do seu portal Purple e os respetivos intervalos de IP, os domínios de deteção de Captive Portal para iOS, Android e Windows, e quaisquer domínios de provedores OAuth que esteja a utilizar. Teste com um dispositivo que nunca se tenha ligado à rede antes - o cache de DNS e o estado da rede podem ocultar falhas na 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 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 as 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 auto-alojado que não está acessível publicamente. Se a Purple não conseguir contactar o seu controlador para autorizar convidados, o portal será carregado, 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 External Portal Server. A Network Application é executada no próprio 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 isso. 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 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 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 convidados 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 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 as durações de sessão adequadas para o seu tipo de local. O caso de negócio é simples. O portal UniFi integrado oferece-lhe uma splash page. A Purple oferece-lhe uma plataforma de experiência de convidado orientada para analítica e em conformidade com as normas, que se integra com o seu CRM, recolhe dados primários sob consentimento do GDPR e fornece a analítica de tráfego de visitantes e tempo de permanência de que os operadores de locais e 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 da Purple 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.