Ver transcrição do podcast
Captive Portal for Ubiquiti UniFi - A Purple Technical Briefing
[INTRODUCTION & CONTEXT - approximately 1 minute]
Welcome to the Purple Technical Briefing series. I'm your host, and today we're getting into the specifics of deploying an external captive portal on Ubiquiti UniFi infrastructure - one of the most widely deployed network platforms in hospitality, retail, and enterprise environments globally.
If you're an IT manager, network architect, or systems integrator working with UniFi Cloud Gateways, Dream Machines, or the UniFi Network Application, this episode is for you. We're going to walk through exactly how the external portal mechanism works under the bonnet, how to configure it correctly, where the common pitfalls are, and why overlaying Purple on top of a UniFi deployment is the right architectural decision for venues that need more than a basic splash page.
Let's get into it.
[TECHNICAL DEEP-DIVE - approximately 5 minutes]
First, let's understand what's actually happening when a guest connects to a UniFi SSID that has a captive portal enabled.
When a guest device associates with your guest SSID, the UniFi Access Point assigns it an IP address via DHCP as normal. But the device is immediately placed in what UniFi calls a "pending" state. In this state, the AP's built-in DNSmasq process intercepts every DNS query the device makes, regardless of what DNS server the device thinks it's using. The AP redirects all DNS traffic to itself.
Simultaneously, the AP runs a lightweight HTTP redirector on port 80. The moment the guest's browser makes any HTTP request - and this is the key word, HTTP, not HTTPS - the redirector fires back a 302 redirect, sending the browser to the captive portal splash page. This is the mechanism that triggers the "Sign in to WiFi" notification on iOS and Android devices.
Now, this is where the built-in portal versus external portal distinction becomes critical. With the built-in UniFi Hotspot Portal, the splash page is served directly by the UniFi Network Application. It's functional, it's quick to set up, but it's severely limited. You get basic password authentication, vouchers, and Stripe payments. There's no email capture, no social login, no GDPR consent management, no CRM integration, and no meaningful analytics beyond session counts.
When you configure an External Portal Server - which is the setting we're focused on today - you're telling the UniFi controller to redirect guests to a completely separate web application. In our case, that's Purple. The URL you enter in the External Portal Server field becomes the destination for all those 302 redirects.
Aqui está o detalhe técnico importante sobre essa URL de redirecionamento. Quando a UniFi redireciona um visitante para o seu portal externo, ela anexa vários parâmetros de consulta à URL. Eles 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 splash page 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 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 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 a controladora recebe essa autorização, ela 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 - também precisará adicionar os domínios de endpoint OAuth desses provedores. 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 essa 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 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. Os dispositivos Apple acessam captive.apple.com por HTTPS. Os dispositivos Android acessam connectivitycheck.gstatic.com. Se essas solicitações HTTPS não obtiverem 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 por 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 em produção.
A outra consideração específica do UniFi é a acessibilidade do controlador. O UniFi Network Application - esteja ele rodando em um Cloud Gateway, em um Cloud Key ou em um servidor próprio - deve estar acessível a partir da infraestrutura do Purple para que as chamadas de autorização de API ocorram com sucesso. 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 próprios, essa porta costuma ser a 8443 para a API legada, 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 - aplicável quando você está implantando o Purple junto a SSIDs WPA2-Enterprise ou WPA3-Enterprise em vez do modelo de SSID de visitante aberto - o servidor RADIUS integrado do UniFi suporta métodos padrão 802.1X EAP. Você configura o perfil do 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 passa pela 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 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 redes corporativas e de IoT. O UniFi torna isso simples - crie uma rede dedicada em Settings, Networks, atribua a ela um ID de VLAN e associe seu SSID de visitante a essa rede. Ative o isolamento de clientes na rede de visitantes para evitar o tráfego entre os próprios visitantes.
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 para ele e configure o UniFi para usar esse certificado. Isso resolve a maior parte dos problemas de redirecionamento de HTTPS.
Terceiro, crie seu walled garden com atenção 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 provedores de OAuth que você esteja utilizando. Teste com um dispositivo que nunca tenha se conectado à rede antes - cache de DNS e estados de rede anteriores 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 principal. Se você estiver no Network Application 9.1 ou superior, utilize o novo mecanismo de chave de API em Control Plane, Integrations - ele é mais seguro e não exige autenticação baseada em credenciais.
Em quinto lugar, considere a duração da sessão com atenção. O tempo padrão de expiração da sessão de convidado da UniFi pode ser de apenas oito horas. Para implantações no setor de 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 transmitidas corretamente na chamada de autorização de 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 será carregado, 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 External Portal Server. O Network Application é executado no próprio dispositivo.
Posso usar a Purple em múltiplos 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 na 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]
Para resumir: implantar a Purple como um Captive Portal externo na UniFi é uma integração bem suportada e arquitetonicamente sólida. As etapas principais são: configurar seu SSID de convidado com a opção External Portal Server apontando para a URL do seu portal Purple, criar uma 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 apropriadas para o seu tipo de local.
O caso de negócios é simples. O portal UniFi integrado oferece apenas uma splash page. A Purple oferece uma plataforma de experiência de convidado orientada por análises e em conformidade com as normas que se integra ao seu CRM, captura dados primários sob o consentimento da GDPR e fornece as análises de fluxo de visitantes e tempo de permanência de 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 white label da Purple a tornam a sobreposição ideal para 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.
