Guia de configuração do captive portal UniFi

Captive Portal para Ubiquiti UniFi - Um Informativo Técnico da Purple [INTRODUÇÃO E CONTEXTO - aproximadamente 1 minuto] Bem-vindo à 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 amplamente implantadas em ambientes de hotelaria, varejo e corporativos globalmente. Se você é um gerente de TI, arquiteto de rede ou integrador de sistemas que trabalha com UniFi Cloud Gateways, Dream Machines ou o UniFi Network Application, este episódio é para você. Nós vamos detalhar exatamente como o mecanismo de portal externo funciona nos bastidores, como configurá-lo corretamente, onde estão as armadilhas comuns e por que sobrepor a Purple a uma implantação UniFi é a decisão de arquitetura correta para locais que precisam de mais do que uma página de login básica. Vamos começar. [MERGULHO TÉCNICO PROFUNDO - aproximadamente 5 minutos] Primeiro, vamos entender o que realmente acontece quando um dispositivo de visitante se conecta a um SSID UniFi que possui um Captive Portal ativado. Quando um dispositivo de visitante se associa ao seu SSID de visitantes, 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". 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á usando. O AP redireciona todo o tráfego DNS para si mesmo. Simultaneamente, o AP executa um redirecionador HTTP leve na porta 80. No momento em que o navegador do visitante faz qualquer requisição HTTP - e esta é a palavra-chave, HTTP, não HTTPS - o redirecionador envia de volta um redirecionamento 302, enviando o navegador para a página de login do Captive Portal. Este é o mecanismo que aciona a notificação "Conectar à rede 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 login é veiculada 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 com Stripe. Não há captura de e-mail, login social, gerenciamento de consentimento de GDPR, integração de 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 visitantes para uma aplicação web completamente separada. No nosso caso, essa aplicação é a Purple. O URL que você insere no campo do Servidor de Portal Externo se torna o destino para todos esses redirecionamentos 302.Aqui está o detalhe técnico importante sobre esse URL de redirecionamento. Quando a UniFi redireciona um visitante para o seu portal externo, ela 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 tentando acessar e o nome do SSID. O seu portal externo - Purple neste contexto - captura esses parâmetros, usa-os para identificar o dispositivo de conexão, apresenta a Captive Portal adequada, 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, existe uma API REST oficial com autenticação adequada baseada em chave. O endpoint de autorização é uma solicitação POST para a versão um da API de sites, visando o ID do 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 Walled Garden, que a 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 serem autenticados. É essencial, e é uma das fontes mais comuns de configuração incorreta. No mínimo, seu walled garden 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 da Purple aponta. 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 da 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 da UniFi que afeta muitas implantações. O redirecionador HTTP no AP apenas intercepta 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á Captive Portal e simplesmente falhar em mostrar a tela de login. A solução é garantir que seu walled garden 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 no navegador que bloqueiam o carregamento do portal. Isso é inegociável para implantações em produção.A outra consideração específica do UniFi é a acessibilidade do controller. O UniFi Network Application - esteja ele sendo executado em um Cloud Gateway, em um Cloud Key ou em um servidor auto-hospedado - deve estar acessível a partir da infraestrutura do Purple para que as chamadas de autorização de API sejam bem-sucedidas. Se o seu controller estiver em uma rede privada atrás de NAT, você precisará garantir que as portas de API relevantes estejam acessíveis. Para controllers auto-hospedados, essa é normalmente a porta 8443 para a API legada, ou a porta HTTPS padrão 443 para a nova API introduzida na versão 9.1. A documentação de suporte do Purple especifica as faixas de IP exatas que precisam de acesso de entrada ao seu controller. Para autenticação baseada em RADIUS - que é relevante quando você está implantando o Purple junto com SSIDs WPA2-Enterprise ou WPA3-Enterprise em vez do modelo de SSID de visitantes aberto - o servidor RADIUS integrado do UniFi suporta os métodos padrão 802.1X EAP. Você configura o perfil RADIUS em Settings, Networks, RADIUS Servers 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, o qual 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 é fortemente recomendado. [IMPLEMENTATION RECOMMENDATIONS & PITFALLS - aproximadamente 2 minutos] Deixe-me passar a lista de verificação de implementação prática pela qual eu passaria com qualquer cliente que estivesse implantando o Purple no UniFi. Primeiro, a segmentação de rede. O seu SSID de visitantes deve estar em uma VLAN dedicada, isolada de suas redes corporativas e IoT. O UniFi torna isso simples - crie uma rede dedicada em Settings, Networks, atribua um VLAN ID a ela e associe o seu SSID de visitantes a essa rede. Ative o isolamento de clientes na rede de visitantes para evitar o tráfego entre visitantes. Segundo, o controller 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 para ele e configure o UniFi para usar esse certificado. Isso resolve a maior parte dos problemas de redirecionamento de HTTPS. Terceiro, monte 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 suas faixas de IP, os domínios de detecção de Captive Portal para iOS, Android e Windows, e quaisquer domínios de provedores OAuth que você esteja utilizando. Teste com um dispositivo que nunca tenha se conectado à rede antes - o cache de DNS e o estado da rede podem mascarar falhas no jardim murado 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 usando o Network Application 9.1 ou posterior, use o novo mecanismo de chave de API em Control Plane, Integrations - ele é mais seguro e não requer autenticação baseada em credenciais. Em quinto lugar, considere a duração da sessão com cuidado. O vencimento padrão da sessão de visitante da UniFi pode ser de apenas oito horas. Para implantações em hospitalidade onde os visitantes 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 uma controladora própria (self-hosted) que não está publicamente acessível. Se o Purple não conseguir alcançar sua controladora para autorizar os visitantes, o portal será carregado, mas a autenticação falhará silenciosamente. Sempre verifique a conectividade da API a partir da infraestrutura do 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 - oferecem suporte à configuração do External Portal Server. 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 do 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 visitantes possa alcançar o domínio do portal Purple na porta 443. A porta da API da controladora também precisa estar acessível a partir dos servidores do Purple. A documentação do Purple fornece os intervalos de IP específicos. E quanto ao WPA3? A UniFi oferece suporte ao WPA3 Personal e WPA3 Enterprise. O mecanismo de Captive Portal funciona com WPA3 Personal em redes de visitantes. O WPA3 Enterprise usa 802.1X e RADIUS, que é um fluxo de autenticação diferente. [RESUMO E PRÓXIMOS PASSOS - aproximadamente 1 minuto] Para resumir: implantar o Purple como um Captive Portal externo na UniFi é uma integração robusta e com excelente suporte de arquitetura. As etapas principais são: configurar o seu SSID de visitante com a opção External Portal Server apontando para a URL do seu portal Purple, criar um walled garden abrangente que cubra a infraestrutura do Purple e quaisquer provedores de OAuth que você esteja usando, garantir que sua controladora UniFi tenha um certificado SSL válido e esteja 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ócios é direto. O portal integrado da UniFi oferece apenas uma tela de autenticação. O Purple oferece uma plataforma de experiência de visitantes orientada por análises e em conformidade regulatória, que se integra ao seu CRM, captura dados primários sob 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 implantando UniFi em escala, o gerenciamento multi-site e os recursos de marca própria do Purple fazem dele a sobreposição certa 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.