Pular para o conteúdo principal
Português (Brasil)

Captive Portal for Ubiquiti UniFi

Este guia técnico definitivo detalha a configuração de um captive portal externo (Purple) no Ubiquiti UniFi Network Application. Ele abrange a mecânica de rede subjacente, a implantação passo a passo da rede de convidados, a lista de permissões do walled garden, a autenticação RADIUS e estratégias de solução de problemas para profissionais de TI seniores e administradores de rede.

📖 10 min de leitura📝 2,475 palavras🔧 2 exemplos práticos❓ 3 questões práticas📚 8 definições principais

Ouça este guia

Ver transcrição do podcast
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 detalhar as especificidades da implantação de um Captive Portal externo na infraestrutura Ubiquiti UniFi — uma das plataformas de rede mais implantadas globalmente em ambientes de hotelaria, varejo e corporativos. Se você é um gerente de TI, arquiteto de rede ou integrador de sistemas que trabalha com UniFi Cloud Gateways, Dream Machines ou com o UniFi Network Application, este episódio é para você. Vamos explicar 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. [APROFUNDAMENTO TÉCNICO — aproximadamente 5 minutos] Primeiro, vamos entender o que realmente acontece quando um dispositivo de convidado se conecta a um SSID UniFi que possui um Captive Portal ativado. Quando um dispositivo de convidado se associa ao seu SSID de convidado, o Access Point UniFi atribui a ele um endereço IP via DHCP normalmente. Mas o dispositivo é colocado imediatamente no que a UniFi chama de estado "pendente". Nesse estado, o processo DNSmasq integrado do AP intercepta todas as consultas DNS que o dispositivo faz, independentemente de qual servidor DNS 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 convidado faz qualquer solicitaçã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 ao Wi-Fi" em 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 é servida 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 via Stripe. Não há captura de e-mail, login social, gerenciamento de consentimento da GDPR, integração com 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 em que estamos focados hoje —, você está dizendo ao controlador UniFi para redirecionar os convidados para uma aplicação web completamente separada. No nosso caso, essa aplicação é a Purple. A URL que você insere no campo Servidor de Portal Externo torna-se o destino de todos esses redirecionamentos 302.Aqui está o detalhe técnico importante sobre essa URL de redirecionamento. Quando o UniFi redireciona um visitante para o seu portal externo, ele anexa vários parâmetros de consulta à URL. Estes incluem: o endereço MAC do AP, o endereço MAC do dispositivo cliente, um timestamp 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 REST API oficial com autenticação baseada em chave adequada. O endpoint de autorização é uma requisiçã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 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 o 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 — precisará adicionar também os domínios de endpoint OAuth desses provedores. Os endpoints de login do Google abrangem vários intervalos de IP e diversos 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 atualizada das entradas exatas necessárias, e essa lista é mantida em dia conforme esses provedores atualizam sua infraestrutura. Há uma particularidade crítica específica do UniFi que afeta muitas implantações. O redirecionador HTTP no AP intercepta apenas o tráfego HTTP comum na porta 80. Os dispositivos modernos — iOS, Android, Windows, macOS — realizam a detecção de Captive Portal baseada em HTTPS. Os dispositivos Apple acessam captive.apple.com via HTTPS. Os dispositivos Android acessam connectivitycheck.gstatic.com. Se essas requisições HTTPS não receberem uma resposta específica, o dispositivo pode decidir que não há um Captive Portal e simplesmente falhar em exibir 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 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 — quer esteja rodando em um Cloud Gateway, em um Cloud Key ou em um servidor auto-hospedado — deve estar acessível a partir da infraestrutura da Purple para que as chamadas de autorização de API funcionem. 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 auto-hospedados, essa porta geralmente é 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 da Purple especifica os intervalos de IP exatos que precisam de acesso de entrada ao seu controlador. Para autenticação baseada em RADIUS — que é relevante quando você está implantando a Purple junto com 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 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, que 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. [RECOMENDAÇÕES DE IMPLEMENTAÇÃO E ARMADILHAS — 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 a Purple no UniFi. Primeiro, segmentação de rede. Seu SSID de visitante deve estar em uma VLAN dedicada, isolada de suas redes corporativas e de IoT. O UniFi torna isso simples — crie uma rede dedicada em Settings, Networks, atribua um ID de VLAN a ela e associe seu SSID de visitante a essa rede. Ative o isolamento de clientes na rede de visitantes para evitar o tráfego de visitante para visitante. 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 maioria dos problemas de redirecionamento HTTPS. Terceiro, configure seu walled garden com cuidado e teste-o. As entradas mínimas são: o domínio do seu Captive Portal da 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 OAuth que você esteja usando. Teste com um dispositivo que nunca tenha se conectado à rede antes — o cache de DNS e o estado da rede 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 posterior, use 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 cuidado. A expiração padrão da sessão de convidado da UniFi pode ser de apenas oito horas. Para implantações em hospitalidade, onde os hóspedes podem passar várias noites, configure durações de sessão apropriadas 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 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 produçã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 Servidor de Portal Externo. 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? O 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 no UniFi é uma integração bem suportada e arquitetonicamente sólida. As etapas principais são: configurar seu SSID de convidado com a opção de Servidor de Portal Externo apontando para a URL do seu portal Purple, criar um 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 uma splash page. A Purple oferece uma plataforma de experiência de convidado pronta para conformidade e orientada por análises que se integra ao seu CRM, captura dados primários sob o 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 que implanta 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 obter 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.

📚 Part of our core series: Multi-Tenant WiFi →

header_image.png

Resumo Executivo

À medida que os locais físicos corporativos — que variam de redes de varejo de grande porte [1] e grupos de hospitalidade multi-site [2] a grandes hubs de transporte [3] e instituições de ensino [4] — buscam maximizar o valor de sua infraestrutura sem fio, as limitações dos controladores de hotspot integrados tornam-se um gargalo operacional significativo. O ecossistema Ubiquiti UniFi oferece hardware altamente confiável, econômico e escalável. No entanto, seu portal de convidados nativo carece de captura de dados avançada, análise multi-site, integração com CRM, conformidade global de privacidade (GDPR, CCPA, PCI DSS) e recursos de monetização exigidos pelas operações corporativas modernas.

Este guia de referência técnica fornece um passo a passo arquitetônico abrangente para sobrepor a Plataforma de Inteligência de WiFi Corporativo da Purple [5] em uma arquitetura de rede Ubiquiti UniFi. Ao utilizar o recurso de External Portal Server do UniFi, arquitetos de rede e integradores de sistemas podem contornar as limitações do controlador local. Essa integração roteia a autenticação de convidados por meio do mecanismo de identidade e análise seguro e hospedado em nuvem da Purple, transformando um serviço básico em um ativo de marketing e operacional de classe corporativa.

Aprofundamento Técnico

Para implantar um Captive Portal externo seguro e estável, os engenheiros de rede devem compreender a comunicação de baixo nível e as transições de estado que ocorrem quando um cliente não autenticado se conecta à rede sem fio.

O Ciclo de Vida de Conexão e Redirecionamento do Convidado

O fluxo de trabalho do Captive Portal do UniFi opera em um modelo estrito baseado em estados. Quando um cliente se associa a um SSID habilitado para convidados, o seguinte processo sequencial é iniciado:

Fase Componente Ação / Transição de Estado Mecanismo Técnico
1. Associação Cliente & Access Point O cliente se associa ao SSID; o servidor DHCP atribui endereço IP, máscara de sub-rede, gateway e servidores DNS. Associação padrão 802.11 e concessão de DHCP.
2. Quarentena UniFi Access Point (AP) O AP coloca o endereço MAC do cliente em um estado de Quarentena / Pendente (authorized: false). Regras de bloqueio de Camada 2/3 aplicadas localmente na interface virtual do AP.
3. Interceptação de DNS Daemon Local do AP O AP executa um processo DNSmasq local que intercepta todas as consultas DNS de clientes pendentes. O AP redireciona todo o tráfego da porta 53 (UDP/TCP) para seu resolvedor DNS local, independentemente das configurações de DNS do cliente.
4. Interceptação HTTP Redirecionador do AP O AP executa um daemon redirecionador HTTP leve na porta 80. Qualquer solicitação HTTP feita pelo cliente é interceptada. O AP responde com um redirecionamento HTTP 302 Found.
5. Redirecionamento Navegador do Cliente O navegador do cliente (ou o Assistente de Captive Portal do SO) é redirecionado para a URL do Portal Externo configurada. A URL de redirecionamento 302 é acrescida de parâmetros de consulta críticos contendo metadados do cliente e do AP.
6. Autenticação Portal Externo (Purple) O cliente interage com a splash page da Purple, concluindo a autenticação (ex.: login social, cadastro de e-mail, OTP por SMS). Sessão HTTPS segura hospedada na infraestrutura de nuvem da Purple.
7. Integração de API Nuvem Purple & Controladora UniFi A Purple valida as credenciais e emite uma chamada de API segura para o UniFi Network Application. Chamada de API REST (requisição POST) contendo o endereço MAC do cliente, ID do site e parâmetros de sessão.
8. Autorização Controladora UniFi & AP A Controladora UniFi atualiza o estado do cliente para authorized: true e envia a ACL atualizada para o AP. O AP remove os bloqueios de Camada 2/3 para o endereço MAC do cliente, concedendo roteamento total para o gateway de internet.

Os Parâmetros de Consulta de Redirecionamento

Quando o AP UniFi emite o redirecionamento HTTP 302, ele anexa um conjunto padronizado de parâmetros de consulta à URL do Portal Externo. O portal externo deve capturar esses parâmetros para identificar o cliente e realizar a autorização de API subsequente:

https://portal.purplehotspot.com/guest/s/default/?ap=94:2a:6f:d0:30:57&id=1c:71:25:63:e4:24&t=1742398732&url=http://connectivitycheck.gstatic.com%2F&ssid=purple-guest
  • ap: O endereço MAC do Access Point UniFi específico ao qual o cliente está associado.
  • id: O endereço MAC do dispositivo cliente que está solicitando acesso à rede.
  • t: Um timestamp Unix epoch que representa o momento de início do redirecionamento, usado para verificação de segurança.
  • url: A URL original que o cliente tentou acessar (geralmente um endpoint de detecção de captive portal do SO).
  • ssid: O nome do SSID ao qual o cliente se conectou, permitindo que o portal apresente a identidade visual específica do local.

architecture_overview.png

O Walled Garden (Controle de Acesso Pré-Autorização)

Antes que um cliente seja autorizado, todo o tráfego é bloqueado, exceto para os destinos explicitamente definidos na lista de Acesso Pré-Autorização (comumente chamada de Walled Garden). Como os dispositivos clientes modernos executam Assistentes de Captive Portal (CPAs) automatizados que testam a conectividade via HTTPS, e como a autenticação externa frequentemente depende de provedores de identidade (IdPs) de terceiros, a configuração de um walled garden robusto e preciso é fundamental.

Se um domínio ou intervalo de IP obrigatório for omitido do walled garden, a splash page não será carregada, os botões de login social travarão ou o dispositivo do cliente perderá totalmente a conexão WiFi, assumindo que a rede está com problemas.

Guia de Implementação

Esta seção descreve a configuração passo a passo necessária para integrar o Captive Portal externo da Purple com o Ubiquiti UniFi Network Application (Controller).

Passo 1: Segmentação de Rede e Configuração de VLAN

Para garantir segurança e conformidade de nível empresarial (como PCI DSS e GDPR), o tráfego de convidados deve ser completamente isolado dos recursos corporativos, sistemas de PDV e redes IoT.

  1. Navegue até Settings > Networks no UniFi Network Application.
  2. Clique em Create New Network.
  3. Configure as definições de rede da seguinte forma:
    • Name: Purple Guest Network
    • VLAN ID: 90 (ou qualquer tag de VLAN dedicada para convidados)
    • Network Type: Guest (isso aplica automaticamente o isolamento de clientes, impedindo a comunicação entre convidados).
    • Gateway IP/Subnet: Configure uma sub-rede apropriada (ex: 10.90.0.1/22 para suportar até 1022 concessões simultâneas de convidados).
    • DHCP Range: Ative o DHCP e defina o intervalo (ex: 10.90.0.10 a 10.90.3.254).
    • DNS Server: Defina para resolvedores públicos confiáveis (ex: Cloudflare 1.1.1.1 e Google 8.8.8.8) para garantir uma resolução de DNS rápida.

Passo 2: Configuração do SSID de Convidados

  1. Navegue até Settings > WiFi e clique em Create New WiFi Network.
  2. Configure os parâmetros do SSID:
    • Name (SSID): Purple Guest WiFi
    • Security Protocol: Open (o Captive Portal lidará com a autenticação).
    • Network: Selecione a Purple Guest Network (VLAN 90) criada no Passo 1.
    • Client Device Isolation: Certifique-se de que esta opção esteja ativada (ON).
  3. Role para baixo até Hotspot Portal e marque a caixa para Enable Captive Portal.

Passo 3: Configurando o Servidor de Portal Externo

Assim que o Hotspot Portal estiver ativado, você deve redirecionar a autenticação para os servidores em nuvem seguros da Purple.

  1. Navegue até Settings > Profiles > Guest Hotspot (ou Settings > Guest Control em versões mais antigas do controller).
  2. Em Authentication, selecione External Portal Server.
  3. Configure os seguintes campos:
    • IP / FQDN: Insira o FQDN fornecido pela Purple (ex: portal.purplehotspot.com).
    • Use Secure Portal (HTTPS): Ative (ON) (Obrigatório para segurança e compatibilidade com navegadores modernos).
    • Redirect Using Hostname: Ative (ON) e insira o FQDN portal.purplehotspot.com.
    • Port: 443 (HTTPS padrão).
    • HTTPS Redirection: Ative (ON) (isso permite que o AP intercepte as requisições HTTPS iniciais e as redirecione, embora exija um gerenciamento cuidadoso de DNS).

Passo 4: Configurando o Acesso de Pré-Autorização (Walled Garden)

Para permitir que convidados não autenticados carreguem a splash page da Purple e se autentiquem por meio de IdPs de terceiros, adicione os seguintes domínios e intervalos de IP à lista de Pre-Authorization Access em Settings > Profiles > Guest Hotspot > Pre-Authorization Access:

[
  "portal.purplehotspot.com",
  "*.purple.ai",
  "*.purplehotspot.com",
  "accounts.google.com",
  "ssl.gstatic.com",
  "*.googleapis.com",
  "*.facebook.com",
  "*.facebook.net",
  "*.fbcdn.net",
  "*.apple.com",
  "captive.apple.com",
  "connectivitycheck.gstatic.com",
  "*.microsoft.com",
  "*.live.com"
]

Nota: Para implantações que utilizam o processamento de pagamentos do Stripe, adicione *.stripe.com e *.stripe.network à lista de pré-autorização.

Passo 5: Estabelecendo o Handshake da API

Para que a Purple autorize os visitantes, seus servidores em nuvem devem se comunicar com o seu UniFi Network Application.

Para UniFi Network Application 9.1 e posteriores (REST API Recomendada)

  1. No controlador UniFi, navegue até Settings > Control Plane > Integrations.
  2. Na seção API Keys, clique em Generate New API Key.
  3. Atribua um nome (ex: Purple Integration Key) e defina as permissões como Administrator.
  4. Copie a API Key gerada.
  5. Faça login no seu Purple Portal, navegue até Venue Settings > Integration > Ubiquiti UniFi e cole a API Key junto com o FQDN público do seu UniFi Controller (ex: unifi.yourdomain.com:443).

Para Controladores Legados (API Baseada em Credenciais)

  1. Navegue até Settings > System > Admins.
  2. Crie uma conta de administrador local dedicada (ex: purple_api).
  3. Atribua privilégios de Administrator ou Hotspot Operator.
  4. Configure uma senha forte e exclusiva.
  5. No Purple Portal, insira essas credenciais na aba de Integração do UniFi.

Melhores Práticas

1. Requisitos de Certificado SSL

Nunca use um certificado SSL autoassinado em um UniFi Controller de produção ou em um Servidor de Portal Externo. Os navegadores web modernos e os Assistentes de Captive Portal (CPAs) dos sistemas operacionais exigem uma validação SSL/TLS rigorosa. Um certificado autoassinado gerará um aviso de segurança altamente visível (ex: "Sua conexão não é privada"), resultando em altas taxas de abandono e danos à marca.

  • Implante um certificado SSL válido e publicamente confiável (ex: Let's Encrypt ou um certificado de CA comercial) no FQDN do UniFi Controller.
  • Certifique-se de que o FQDN do controlador seja resolvido corretamente tanto a partir da VLAN de visitantes interna quanto da internet pública.

2. Configuração de DNS

A lentidão na resolução de DNS é a principal causa de redirecionamentos demorados no Captive Portal.

  • Não aponte o DNS dos visitantes para o IP local do UniFi Gateway, a menos que o gateway tenha um encaminhamento de DNS de alto desempenho configurado.
  • Em vez disso, configure o escopo DHCP de visitantes para distribuir servidores DNS públicos rápidos e resilientes diretamente aos clientes (ex: Primário: 1.1.1.1, Secundário: 8.8.8.8).

3. Configuração de WiFi de Visitantes com RADIUS (Alternativa Enterprise)

Para locais que exigem segurança 802.1X baseada em certificados ou credenciais, em vez de um SSID aberto com um portal web, o UniFi suporta a integração com Cloud RADIUS externo [6].

  • Configure um RADIUS Profile em Settings > Profiles > RADIUS.
  • Insira os IPs dos Servidores RADIUS Primário e Secundário e os Segredos Compartilhados fornecidos pela Purple.* Ative o RADIUS Accounting e defina o Interim Update Interval para 300 segundos para garantir o rastreamento de sessão em tempo real.
  • Nas configurações de SSID, defina o Protocolo de Segurança como WPA2 Enterprise ou WPA3 Enterprise [7] e selecione o Perfil RADIUS.

comparison_chart.png

Solução de Problemas e Mitigação de Riscos

Ao implantar Captive Portals externos, os administradores de rede frequentemente encontram vários modos de falha comuns. A tabela abaixo detalha esses problemas, suas causas raiz e as etapas exatas de mitigação:

Sintoma Análise de Causa Raiz Ação Corretiva e Mitigação
Tela Branca / Portal Não Carrega O dispositivo cliente não consegue resolver ou alcançar o FQDN do servidor do portal externo. 1. Verifique se portal.purplehotspot.com está na lista de Acesso de Pré-Autorização.
2. Certifique-se de que o cliente visitante recebeu um IP válido e um servidor DNS via DHCP.
3. Realize uma consulta DNS no dispositivo cliente para verificar a resolução do FQDN do portal.
Erro de SSL "A Conexão Não É Privada" O UniFi Controller está usando um certificado autoassinado, ou o FQDN de redirecionamento não corresponde ao nome comum do certificado SSL. 1. Instale um certificado SSL publicamente confiável no UniFi Controller.
2. Verifique se Redirect Using Hostname está ativado e corresponde exatamente ao FQDN no certificado.
3. Desative "Redirect HTTPS" nas configurações de controle de visitantes do UniFi para evitar que o AP tente interceptar o tráfego HTTPS na porta 443, o que naturalmente gera avisos de SSL.
A Autenticação Funciona, mas a Internet é Bloqueada A nuvem Purple conseguiu autenticar o usuário, mas a chamada de API para autorizar o endereço MAC do cliente no UniFi Controller falhou. 1. Verifique as regras de firewall para garantir que a porta 443 (ou 8443 para sistemas legados) esteja aberta para entrada no UniFi Controller a partir dos intervalos de IP da Purple.
2. Verifique se a Chave de API ou as credenciais de administrador local inseridas no Purple Portal são válidas e possuem permissões de Administrador.
3. Verifique os logs do UniFi Controller (server.log) para falhas de autenticação de API.
Botões de Login Social (ex: Google) Não Funcionam Os domínios de autenticação do IdP estão bloqueados pela lista de controle de acesso do AP. 1. Adicione os domínios curinga (wildcard) completos para o IdP específico à lista de Acesso de Pré-Autorização (ex: *.google.com, *.googleapis.com).
2. Se estiver usando o Facebook, certifique-se de que os domínios do Facebook SDK estejam totalmente na lista de permissões.
Desconexões Frequentes / Solicitações de Reautenticação O tempo limite de sessão do UniFi Controller é menor do que a duração da sessão da Purple, ou os tempos de concessão (lease) do DHCP são muito curtos. 1. Alinhe a configuração de Tempo Limite de Sessão do UniFi Guest Hotspot com a política de sessão da Purple (ex: 24 horas).
2. Aumente o tempo de concessão do DHCP na VLAN de Visitantes para pelo menos 12 ou 24 horas para evitar o esgotamento de endereços IP e a reautenticação no meio da sessão.

ROI e Impacto nos Negócios

Embora a implantação de um Captive Portal externo exija uma engenharia de rede cuidadosa, os resultados de negócios e o retorno sobre o investimento (ROI) superam em muito a complexidade inicial de implementação.

Captura de Dados Corporativos e Enriquecimento de CRM

O portal de visitantes nativo do UniFi é um utilitário "cego"; ele concede acesso à internet sem capturar a identidade do usuário. Ao sobrepor a Purple, os estabelecimentos podem capturar dados primários (first-party data) valiosos (e-mails, números de telefone, perfis sociais) de maneira totalmente em conformidade com a GDPR e a CCPA. Esses dados são sincronizados automaticamente em tempo real com sistemas de CRM, plataformas de marketing (ex: Salesforce, HubSpot, Mailchimp) e programas de fidelidade, permitindo campanhas de marketing altamente direcionadas que impulsionam visitas repetidas e o valor do tempo de vida do cliente (LTV).

Gerenciamento de Múltiplos Locais e White-Labeling

Para Provedores de Serviços Gerenciados (MSPs) e operadores corporativos de múltiplos locais, gerenciar o WiFi de visitantes em centenas de estabelecimentos por meio de controladores UniFi individuais é altamente ineficiente. A Purple fornece um painel em nuvem único e centralizado para gerenciar splash pages, termos de conformidade e análises em todos os locais globalmente, independentemente da distribuição subjacente do controlador UniFi.

Análises em Tempo Real e Inteligência Espacial

A Purple transforma a rede sem fio UniFi em uma poderosa matriz de sensores. Ao analisar probe requests e metadados de conexão, a Purple fornece inteligência espacial profunda, incluindo:

  • Análise de Fluxo de Pessoas (Footfall): Total de visitantes, tráfego de passagem e taxas de conversão (passagem para entrada).
  • Tempo de Permanência (Dwell Time): Duração média das visitas, segmentada por tipo de cliente (novo vs. recorrente).
  • Recência e Frequência: Com que frequência os clientes retornam e o tempo decorrido entre as visitas.
  • Mapas de Calor do Estabelecimento: Representação visual do fluxo e da densidade de visitantes, permitindo que operadores de varejo e estabelecimentos otimizem layouts e equipes.

Monetização via Redes de Mídia de Varejo (Retail Media Networks)

Para grandes estabelecimentos, como estádios, shopping centers e aeroportos, a splash page do Captive Portal representa um espaço digital altamente valioso. A Purple permite que os estabelecimentos monetizem esse espaço integrando-se com redes de mídia de varejo, exibindo publicidade programática direcionada, experiências de login patrocinadas e promoções localizadas diretamente aos visitantes no momento da conexão.

Referências

Definições principais

Captive Portal

Uma página web que intercepta a conexão de rede inicial de um visitante e exige autenticação, registro ou aceitação de termos antes de conceder acesso total à internet.

Encontrado imediatamente após a conexão a um SSID de visitante aberto; gerenciado pelo redirecionador do AP e pelo servidor de portal externo.

External Portal Server

Um aplicativo web de terceiros (como o Purple) que hospeda a splash page de visitantes e lida com a autenticação do usuário, contornando as limitações de portal do controlador integrado.

Configurado nas configurações de Guest Hotspot do UniFi para substituir a página de destino nativa do UniFi.

Walled Garden (Acesso de Pré-Autorização)

Uma lista de permissões (whitelist) de domínios, subdomínios ou endereços IP que clientes não autenticados podem acessar antes de concluir o processo de login no Captive Portal.

Essencial para carregar a própria página do portal, recursos de CSS/JS e endpoints de login OAuth de terceiros.

DNSmasq

Um encaminhador de DNS leve e servidor DHCP executado localmente nos Access Points UniFi para interceptar e redirecionar consultas de DNS de visitantes durante o estado de pré-autorização.

Lida com o redirecionamento de DNS inicial que força os dispositivos dos clientes a acionarem seus assistentes de Captive Portal integrados.

API Authorization Handshake

O processo em que o servidor de portal externo (Purple) faz uma chamada de API segura de volta para o controlador UniFi para transicionar o endereço MAC de um cliente de 'quarentena' para 'autorizado'.

Ocorre imediatamente após o usuário concluir com sucesso o fluxo de login na splash page.

Isolamento de Dispositivo Cliente

Um recurso de segurança que impede que clientes sem fio no mesmo SSID ou VLAN se comuniquem entre si, mitigando o risco de ataques na rede local.

Ativado nas configurações de WiFi e de rede do UniFi para proteger a privacidade dos visitantes e garantir a segurança da rede do local.

RADSEC (RADIUS over TLS)

Um protocolo que protege o tráfego de autenticação e tarifação RADIUS ao envolvê-lo em um túnel TLS seguro, evitando interceptações e adulterações em redes públicas.

Suportado no UniFi Network 8.4+ para implantações corporativas seguras em múltiplos locais usando WPA2/WPA3 Enterprise.

CPA (Captive Portal Assistant)

Um utilitário de sistema operacional integrado no iOS, Android, Windows e macOS que detecta automaticamente um Captive Portal ao tentar buscar um endpoint HTTP/HTTPS conhecido.

Aciona a janela pop-up 'Conectar ao WiFi' no dispositivo do usuário imediatamente após a conexão.

Exemplos práticos

Um shopping center de alto fluxo com 150 APs UniFi e uma UniFi Network Application auto-hospedada na AWS precisa implantar o Purple. A equipe de TI deseja usar o login social do Google e do Facebook para autenticação de visitantes. No entanto, durante os testes iniciais, os visitantes que clicam nos botões de login social se deparam com uma tela em branco ou um erro de resolução de DNS.

O problema é causado por um walled garden restritivo (Pre-Authorization Access) que impede o dispositivo do visitante de resolver ou alcançar os endpoints de autenticação do Google e do Facebook antes de serem autorizados. Para resolver isso, o administrador de rede deve fazer login na UniFi Network Application, navegar até Settings > Profiles > Guest Hotspot e expandir a seção Pre-Authorization Access. Eles devem adicionar os domínios curinga (wildcard) completos para os provedores de identidade do Google e do Facebook. Para o Google, isso inclui accounts.google.com, ssl.gstatic.com e *.googleapis.com. Para o Facebook, exige *.facebook.com, *.facebook.net e *.fbcdn.net. Além disso, certifique-se de que o escopo DHCP da rede de visitantes esteja configurado para distribuir servidores DNS públicos e rápidos (por exemplo, 1.1.1.1 e 8.8.8.8) diretamente aos clientes, em vez de apontá-los para o gateway UniFi local, o que pode se tornar um gargalo para consultas DNS de pré-autorização.

Comentário do examinador: Este é um caso clássico de falha por 'lacuna no walled garden'. Como os fluxos de login social dependem de redirecionamentos OAuth complexos em múltiplos subdomínios, a omissão de um único domínio de entrega de ativos (como o CDN do Facebook `fbcdn.net`) impedirá a renderização da página. Os arquitetos de rede devem sempre usar curingas (`*.domain.com`) onde houver suporte pelo controlador e verificar a resolução de DNS a partir de um cliente não autenticado usando ferramentas padrão como `nslookup` ou `dig` contra os domínios liberados na lista.

Um MSP está implantando o Purple em uma rede de 50 hotéis boutique. Cada hotel possui um UniFi Cloud Gateway Max local no local. O MSP deseja gerenciar todos os sites a partir de uma única conta Purple, mas está preocupado com a segurança e como a nuvem do Purple se comunicará de volta com os controladores locais individuais para autorizar os endereços MAC dos visitantes, considerando que os gateways locais estão atrás de IPs públicos dinâmicos com NAT.

A arquitetura ideal utiliza a API REST oficial da UniFi com redirecionamento de porta de entrada (port forwarding) ou um proxy reverso, combinado com DNS dinâmico (DDNS). Para cada hotel: 1) Configure um hostname DDNS no Cloud Gateway Max (por exemplo, hotel01.mspdomain.com) para que o IP público do gateway seja sempre rastreável. 2) Configure uma regra de redirecionamento de porta no gateway para encaminhar o tráfego HTTPS de entrada em uma porta alta e não padrão (por exemplo, 10443) para o IP de gerenciamento do gateway local na porta 443. 3) No controlador UniFi, navegue até Settings > Control Plane > Integrations e gere uma API Key exclusiva. 4) No Portal Purple, configure um 'Venue' exclusivo para cada hotel, selecionando a integração Ubiquiti UniFi. Insira o endereço DDNS exclusivo com a porta redirecionada (por exemplo, hotel01.mspdomain.com:10443) e a API Key específica gerada para aquele site. Por fim, proteja o redirecionamento de porta de entrada em cada gateway restringindo os IPs de origem aos intervalos de IP da nuvem pública do Purple, impedindo o acesso não autorizado do restante da internet.

Comentário do examinador: O uso de uma porta alta e não padrão para o redirecionamento de porta, combinado com uma lista de permissões estrita de IPs de origem para aceitar apenas os blocos de IP de nuvem do Purple, mitiga os riscos de segurança de expor a porta de API do controlador à internet pública. Essa arquitetura evita a necessidade de IPs públicos estáticos caros em cada site, mantendo recursos robustos de autorização de MAC em tempo real.

Questões práticas

Q1. Um administrador de rede configurou um Captive Portal externo em uma rede de visitantes UniFi. Durante os testes, ele percebe que a splash page do Captive Portal é carregada com sucesso, mas depois que o visitante insere seu endereço de e-mail e clica em 'Conectar', o navegador trava e eventualmente exibe um erro de timeout. O cliente permanece em quarentena. Qual é a causa mais provável desse problema e como ele deve ser investigado?

Dica: A página do portal foi carregada, o que significa que o DNS e o walled garden estão funcionando. A falha ocorre *após* o visitante enviar suas credenciais.

Ver resposta modelo

A causa mais provável é uma falha no handshake de autorização da API entre a nuvem da Purple e o UniFi Controller. Como a página do portal foi carregada e o visitante conseguiu interagir com ela, as configurações de DNS e Pre-Authorization Access (Walled Garden) estão corretas. No entanto, quando o visitante conclui a autenticação, a Purple tenta enviar uma chamada de API REST segura (requisição POST) para o UniFi Controller para autorizar o endereço MAC do cliente. Se o UniFi Controller estiver atrás de um firewall, NAT ou em uma rede privada sem o redirecionamento de portas adequado, ou se as credenciais da API (ou Chave de API) estiverem incorretas, a requisição de autorização falhará ou expirará por timeout. Para investigar: 1) Verifique se o FQDN e a porta do UniFi Controller estão acessíveis publicamente a partir dos intervalos de IP da Purple. 2) Verifique as regras de firewall de entrada no gateway que protege o UniFi Controller para garantir que a porta 443 (ou 8443) esteja aberta. 3) No portal da Purple, verifique se as configurações de integração do UniFi contêm a Chave de API ou credenciais de administrador corretas e se a URL do controller está precisa. 4) Inspecione o arquivo server.log do UniFi Controller para verificar se há tentativas de conexão de entrada ou erros de autenticação de API vindos dos IPs da Purple.

Q2. Uma implantação corporativa exige a configuração de uma rede de visitantes com um Captive Portal externo. O arquiteto de rede deseja usar HTTPS para todo o tráfego do Captive Portal para evitar a interceptação de credenciais. Ele ativa as opções 'Use Secure Portal (HTTPS)' e 'Redirect Using Hostname' no UniFi, apontando para o FQDN do portal externo. No entanto, quando os clientes se conectam, seus navegadores exibem imediatamente um aviso grave de 'SSL Certificate Common Name Mismatch' ou 'Certificate Not Trusted', bloqueando o acesso. Como isso pode ser resolvido?

Dica: Pense em qual dispositivo está realizando o redirecionamento inicial e qual certificado SSL ele está apresentando ao cliente.

Ver resposta modelo

Este problema ocorre porque o Access Point ou o Controller UniFi está tentando interceptar uma requisição HTTPS do cliente e redirecioná-la para o Captive Portal. Quando um cliente se conecta e tenta visitar um site HTTPS (por exemplo, https://www.google.com), o redirecionador do AP intercepta o tráfego. Para realizar o redirecionamento via HTTPS, o AP precisa apresentar um certificado SSL. Como o AP não possui um certificado SSL válido para www.google.com, o navegador do cliente detecta uma condição de Man-in-the-Middle (MITM) e exibe um aviso de SSL grave. Para resolver isso: 1) Certifique-se de que o próprio UniFi Controller tenha um certificado SSL válido e publicamente confiável instalado, correspondente ao seu FQDN configurado. 2) Nas configurações de rede de visitantes do UniFi, desative 'Redirect HTTPS' (deixe apenas o redirecionamento HTTP ativado). Isso impede que o AP tente interceptar o tráfego HTTPS. Em vez disso, a rede dependerá do Assistente de Captive Portal (CPA) do sistema operacional do dispositivo cliente, que testa a conectividade usando endpoints HTTP simples (por exemplo, http://captive.apple.com ou http://connectivitycheck.gstatic.com). O AP pode interceptar com segurança essas requisições HTTP na porta 80 e redirecioná-las para a URL HTTPS segura do portal da Purple (https://portal.purplehotspot.com) sem acionar nenhum aviso de SSL no navegador.

Q3. Uma rede de hotéis deseja implantar a segurança WPA3-Enterprise para sua rede de visitantes VIP, mantendo a integração com a plataforma de analytics da Purple. A equipe de TI local não tem certeza se pode usar o redirecionamento padrão de Captive Portal com External Portal Server junto com o WPA3-Enterprise. Qual é a abordagem arquitetônica correta para este cenário?

Dica: O WPA3-Enterprise usa autenticação 802.1X, que ocorre na fase de associação, antes que um endereço IP seja atribuído. Isso é fundamentalmente diferente de um SSID aberto com um Captive Portal.

Ver resposta modelo

O WPA3-Enterprise (e o WPA2-Enterprise) utiliza autenticação 802.1X, que é fundamentalmente incompatível com o redirecionamento web padrão de Captive Portal. Em uma rede 802.1X, a autenticação ocorre na fase de associação (Camada 2) usando métodos EAP (como EAP-TLS ou PEAP) antes que o cliente receba um endereço IP ou tenha permissão para acessar a rede. Portanto, não é possível redirecionar um cliente para uma splash page baseada na web. Para integrar o WPA3-Enterprise com a Purple: 1) Mude do modelo de 'External Portal Server' para um modelo de RADIUS Externo. 2) Configure um Perfil RADIUS no UniFi Network Application, inserindo os endereços IP dos servidores Cloud RADIUS da Purple, as portas de autenticação (geralmente 1812), as portas de accounting (geralmente 1813) e o segredo compartilhado. 3) Ative o RADIUS Accounting e defina um Interim Update Interval de 300 segundos. 4) Configure o SSID VIP para usar WPA3 Enterprise e selecione o Perfil RADIUS. Quando um visitante VIP se conecta, seu dispositivo se autentica diretamente contra o servidor Cloud RADIUS da Purple usando suas credenciais corporativas exclusivas ou certificado. O servidor RADIUS da Purple autoriza a conexão e recebe as atualizações de accounting, permitindo que o estabelecimento capture analytics de conexão, duração da sessão e uso de dados sem a necessidade de uma splash page baseada na web.

Continue a ler esta série

CommScope Ruckus Integration with Purple WiFi: Setup and Configuration Guide

Este guia de referência técnica fornece um manual de configuração definitivo para integrar arquiteturas CommScope Ruckus com o Purple WiFi. Ele detalha implementações passo a passo para Captive Portals de Guest WiFi, WiFi seguro para funcionários via 802.1X e isolamento de rede multi-tenant usando Ruckus Dynamic PSK.

Ler o guia →

Integração de Access Points Allied Telesis com o Purple WiFi

Este guia fornece um manual de configuração abrangente para integrar os access points Allied Telesis Série TQ com o Purple WiFi. Ele aborda o redirecionamento de Captive Portal externo, autenticação RADIUS 802.1X e direcionamento dinâmico de VLAN usando Private Pre-Shared Keys (PPSK) para implantações seguras de múltiplos inquilinos (multi-tenant).

Ler o guia →

Integração de Access Points Grandstream GWN com Purple WiFi

Este guia de referência técnica detalhado explica como integrar os access points Grandstream GWN com o Guest WiFi e a plataforma de analytics da Purple. Ele abrange a configuração do Captive Portal Grandstream, definições de RADIUS AAA, configuração de walled garden, autenticação segura de funcionários via 802.1X com direcionamento dinâmico de VLAN e segmentação PPSK multi-tenant — fornecendo orientações práticas passo a passo para MSPs e equipes de TI que implantam WiFi para visitantes e funcionários em escala.

Ler o guia →