Saltar para o conteúdo principal
Português

Captive Portal for Ubiquiti UniFi

Este guia técnico de referência detalha a configuração de um captive portal externo (Purple) na aplicação Ubiquiti UniFi Network. Abrange o funcionamento subjacente da rede, a implementação passo a passo da rede de convidados, a configuração de domínios permitidos (walled garden), a autenticação RADIUS e estratégias de resolução de problemas para profissionais de TI seniores e administradores de rede.

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

Ouça este guia

Ver transcrição do podcast
Captive Portal para Ubiquiti UniFi — Uma Sessão Técnica da Purple [INTRODUÇÃO E CONTEXTO — aproximadamente 1 minuto] Bem-vindo à série de Sessões Técnicas da Purple. Sou o vosso anfitrião e hoje vamos analisar em detalhe a 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 a UniFi Network Application, este episódio é para si. Vamos explicar exatamente como funciona o mecanismo de portal externo nos bastidores, como configurá-lo corretamente, quais os erros comuns e por que motivo sobrepor a Purple a uma implementação UniFi é a decisão de arquitetura correta para locais que necessitam de mais do que uma página de boas-vindas básica. Vamos começar. [ANÁLISE TÉCNICA DETALHADA — aproximadamente 5 minutos] Primeiro, vamos compreender o que acontece realmente quando um dispositivo convidado se liga a um SSID UniFi que tem um captive portal ativo. 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 designa por estado "pendente". Neste estado, o processo DNSmasq integrado no 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 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 responde com um redirecionamento 302, enviando o browser para a página de boas-vindas 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 boas-vindas é 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 emails, login social, gestão de consentimento de RGPD (GDPR), integração de CRM e nenhuma análise de dados relevante além da contagem de sessões. Quando configura um Servidor de Portal Externo — que é a definição em que nos focamos hoje —, está a dizer ao controlador UniFi para redirecionar os convidados para uma aplicação web completamente separada. No nosso caso, a Purple. O URL que introduz no campo External Portal Server 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 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 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 splash page adequada, processa 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 handshake crucial. A partir do UniFi Network Application 9.1 e posterior, existe uma API REST 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 velocidade 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 chama de Acesso Pré-Autorização. Esta é a lista de permissões (whitelist) de domínios e endereços IP aos quais os visitantes 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 intervalos CIDR para os quais a infraestrutura da Purple resolve. Se estiver a utilizar o início de sessão social — Facebook, Google, Microsoft — também precisa de adicionar os domínios do endpoint OAuth para esses fornecedores. Os endpoints de início de sessão do Google abrangem vários intervalos de IP e diversos domínios, incluindo accounts.google.com e oauth2.googleapis.com. A infraestrutura de início de sessão do Facebook requer, de igual modo, 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 fornecedores atualizam a sua infraestrutura. Existe uma particularidade crítica específica do UniFi que apanha muitas implementações desprevenidas. O redirecionador HTTP no AP apenas interseta 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 mostrar o aviso de início de sessão. A solução é 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 ser executada num Cloud Gateway, num Cloud Key ou num servidor auto-alojado — deve ser alcançável a partir da infraestrutura da Purple para que as chamadas de autorização da API tenham sucesso. Se o seu controlador estiver numa rede privada atrás de NAT, precisará de garantir que as portas da 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 API mais recente introduzida na versão 9.1. A documentação de suporte da Purple especifica as gamas exatas de IP que necessitam de acesso de entrada ao seu controlador. Para 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 convidado aberto — o servidor RADIUS integrado da UniFi suporta métodos standard 802.1X EAP. Configura o perfil RADIUS em Definições, Redes, Servidores RADIUS e, em seguida, 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 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] Permita-me apresentar-lhe a lista de verificação de implementação prática que eu analisaria com qualquer cliente que estivesse 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 Definições, Redes, atribua-lhe um ID de VLAN e associe o seu SSID de convidado a essa rede. Ative o isolamento de clientes na rede de convidados para evitar 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 para o mesmo e configure a UniFi para utilizar esse certificado. Isto resolve a maioria dos problemas de redirecionamento HTTPS. Terceiro, configure o seu walled garden com cuidado e teste-o. As entradas mínimas são: o domínio do portal da Purple e as suas gamas de IP, os domínios de deteção de Captive Portal para iOS, Android e Windows, e quaisquer domínios de fornecedores de 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 mascarar falhas no walled garden 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 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 a duração da sessão com atenção. A expiração predefinida da sessão de convidado da UniFi pode ser de apenas oito horas. Para implementações no setor hoteleiro, onde os hóspedes podem permanecer várias noites, configure 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 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 no UniFi Dream Machine Pro? Sim. Todas as consolas UniFi OS — UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max — suportam a configuração de Servidor de Portal Externo. A aplicação de rede é 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 isto. Cada espaço é 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? O 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, 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 no 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 as durações de sessão adequadas para o seu tipo de espaço. O caso de negócio é simples. O portal integrado do UniFi oferece-lhe uma página de boas-vindas. A Purple oferece-lhe uma plataforma de experiência de convidado orientada para a análise e em conformidade normativa que se integra com o seu CRM, capta 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 de espaços e equipas de marketing realmente precisam. Se é um MSP ou integrador de sistemas a implementar UniFi em 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 obter documentação de configuração detalhada, listas de IP 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 espaços físicos empresariais — que vão desde grandes cadeias de retalho [1] e grupos de hotelaria multi-site [2] a importantes hubs de transporte [3] e instituições de ensino [4] — procuram maximizar o valor da sua infraestrutura sem fios, as limitações dos controladores de hotspot integrados tornam-se um estrangulamento operacional significativo. O ecossistema Ubiquiti UniFi fornece hardware altamente fiável, económico e escalável. No entanto, o seu portal de convidados nativo carece de captura de dados avançada, analítica multi-site, integração com CRM, conformidade global de privacidade (GDPR, CCPA, PCI DSS) e capacidades de monetização exigidas pelas operações empresariais modernas.

Este guia de referência técnica fornece uma análise detalhada e abrangente da arquitetura para sobrepor a Purple's Enterprise WiFi Intelligence Platform [5] sobre uma arquitetura de rede Ubiquiti UniFi. Ao utilizar a funcionalidade External Portal Server da UniFi, os arquitetos de rede e integradores de sistemas podem contornar as limitações dos controladores locais. Esta integração encaminha a autenticação de convidados através do motor de identidade e analítica seguro e alojado na nuvem da Purple, transformando uma ferramenta básica num ativo operacional e de marketing de nível empresarial.

Análise Técnica Detalhada

Para implementar 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 liga à rede sem fios.

O Ciclo de Vida de Ligação e Redirecionamento de Convidados

O fluxo de trabalho do Captive Portal UniFi funciona com base num modelo estrito baseado em estados. Quando um cliente se associa a um SSID com acesso de convidados ativado, é iniciado o seguinte processo sequencial:

Fase Componente Ação / Transição de Estado Mecanismo Técnico
1. Associação Cliente e Access Point O cliente associa-se ao SSID; o servidor DHCP atribui o endereço IP, máscara de sub-rede, gateway e servidores DNS. Associação standard 802.11 e concessão DHCP.
2. Quarentena Access Point UniFi (AP) O AP coloca o endereço MAC do cliente num estado Quarentenado / Pendente (authorized: false). Regras de bloqueio de Camada 2/3 aplicadas localmente na interface virtual do AP.
3. Interceção de DNS Daemon Local do AP O AP executa um processo DNSmasq local que interceciona todas as consultas de DNS dos clientes pendentes. O AP redireciona todo o tráfego da porta 53 (UDP/TCP) para o seu resolvedor de DNS local, independentemente das definições de DNS do cliente.
4. Interceção de HTTP Redirecionador do AP O AP executa um daemon redirecionador HTTP leve na porta 80. Qualquer pedido HTTP feito pelo cliente é intercecionado. O AP responde com um redirecionamento HTTP 302 Found.
5. Redirecionamento Navegador do Cliente O navegador do cliente (ou o Assistente do Captive Portal do SO) é redirecionado para o URL do Portal Externo configurado. O URL de redirecionamento 302 é anexado com 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, completando a autenticação (ex.: login social, registo por e-mail, OTP por SMS). Sessão HTTPS segura alojada na infraestrutura de nuvem da Purple.
7. Comunicação da API Nuvem da Purple e Controlador UniFi A Purple valida as credenciais e emite uma chamada de API segura para a Aplicação de Rede UniFi. Chamada de API REST (pedido POST) contendo o endereço MAC do cliente, o ID do site e os parâmetros da sessão.
8. Autorização Controlador UniFi e AP O Controlador UniFi atualiza o estado do cliente para authorized: true e envia o ACL atualizado 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 ao URL do Portal Externo. O portal externo deve capturar estes parâmetros para identificar o cliente e realizar a subsequente autorização da API:

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 Ponto de Acesso UniFi específico ao qual o cliente está associado.
  • id: O endereço MAC do dispositivo do cliente que solicita acesso à rede.
  • t: Um timestamp da época Unix que representa a hora de início do redirecionamento, utilizado para verificação de segurança.
  • url: O URL original que o cliente tentou aceder (frequentemente um endpoint de deteção de captive portal do SO).
  • ssid: O nome do SSID ao qual o cliente se ligou, permitindo que o portal apresente uma marca específica do site.

architecture_overview.png

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

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

Se um domínio ou intervalo de IP necessário for omitido do walled garden, a splash page falhará ao carregar, os botões de login social irão congelar ou o dispositivo do cliente perderá a ligação WiFi por completo, assumindo uma rede avariada.

Guia de Implementação

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

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

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

  1. Navegue até Settings > Networks na 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 etiqueta de VLAN dedicada a convidados)
    • Network Type: Guest (isto aplica automaticamente o isolamento de clientes, impedindo a comunicação entre convidados).
    • Gateway IP/Subnet: Configure uma sub-rede adequada (por exemplo, 10.90.0.1/22 para suportar até 1022 concessões de convidados simultâneas).
    • DHCP Range: Ative o DHCP e defina o intervalo (por exemplo, 10.90.0.10 a 10.90.3.254).
    • DNS Server: Configure para resolvedores públicos fiáveis (por exemplo, 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 tratará da autenticação).
    • Network: Selecione a Purple Guest Network (VLAN 90) criada no Passo 1.
    • Client Device Isolation: Certifique-se de que esta opção está ativada.
  3. Desça até Hotspot Portal e marque a caixa para Enable Captive Portal.

Passo 3: Configurar o Servidor de Portal Externo

Assim que o Hotspot Portal estiver ativado, deve redirecionar a autenticação para os servidores na 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 (por exemplo, portal.purplehotspot.com).
    • Use Secure Portal (HTTPS): Ative (Obrigatório para segurança e compatibilidade com navegadores modernos).
    • Redirect Using Hostname: Ative e insira o FQDN portal.purplehotspot.com.
    • Port: 443 (HTTPS padrão).
    • HTTPS Redirection: Ative (isto permite que o AP intersete os pedidos HTTPS iniciais e os redirecione, embora exija uma gestão de DNS cuidadosa).

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

Para permitir que convidados não autenticados carreguem a splash page da Purple e se autentiquem através 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 implementações que utilizem o processamento de pagamentos da Stripe, adicione *.stripe.com e *.stripe.network à lista de pré-autorização.

Passo 5: Estabelecer o Handshake da API

Para que a Purple autorize os convidados, os seus servidores na cloud devem comunicar com a sua UniFi Network Application.

Para a UniFi Network Application 9.1 e Superior (REST API Recomendada)

  1. No controlador UniFi, navegue até Definições > Plano de Controlo > Integrações (Settings > Control Plane > Integrations).
  2. Na secção Chaves de API (API Keys), clique em Gerar Nova Chave de API (Generate New API Key).
  3. Atribua um nome (ex. Purple Integration Key) e defina as permissões como Administrador (Administrator).
  4. Copie a API Key gerada.
  5. Inicie sessão no seu Portal Purple, navegue até Definições do Local > Integração > Ubiquiti UniFi (Venue Settings > Integration > Ubiquiti UniFi) e cole a API Key juntamente com o FQDN público do seu Controlador UniFi (ex. unifi.oseudominio.com:443).

Para Controladores Antigos (API Baseada em Credenciais)

  1. Navegue até Definições > Sistema > Administradores (Settings > System > Admins).
  2. Crie uma conta de administrador local dedicada (ex. purple_api).
  3. Atribua privilégios de Administrador (Administrator) ou Operador de Hotspot (Hotspot Operator).
  4. Configure uma palavra-passe forte e única.
  5. No Portal Purple, introduza estas credenciais no separador de Integração UniFi.

Melhores Práticas

1. Requisitos de Certificado SSL

Nunca utilize um certificado SSL autoassinado num Controlador UniFi de produção ou num Servidor de Portal Externo. Os navegadores web modernos e os Assistentes de Captive Portal (CPAs) dos sistemas operativos impõem uma validação SSL/TLS rigorosa. Um certificado autoassinado irá desencadear um aviso de segurança altamente visível (ex. "A sua ligação não é privada"), levando a elevadas taxas de abandono e danos à imagem da marca.

  • Implemente um certificado SSL válido e publicamente fidedigno (ex. Let's Encrypt ou um certificado de CA comercial) no FQDN do Controlador UniFi.
  • Certifique-se de que o FQDN do controlador é resolvido corretamente tanto a partir da VLAN de convidados interna como da internet pública.

2. Configuração de DNS

Uma resolução de DNS lenta é a principal causa de redirecionamentos demorados no Captive Portal.

  • Não aponte o DNS de convidados para o IP local do Gateway UniFi, a menos que o gateway tenha o encaminhamento de DNS de alto desempenho configurado.
  • Em vez disso, configure o âmbito de DHCP de convidados 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 Convidados via RADIUS (Alternativa Enterprise)

Para locais que requerem 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 Perfil RADIUS (RADIUS Profile) em Definições > Perfis > RADIUS (Settings > Profiles > RADIUS).
  • Introduza os IPs dos Servidores RADIUS Primário e Secundário e os Segredos Partilhados fornecidos pela Purple.
  • Ative o RADIUS Accounting e defina o Interim Update Interval para 300 segundos para garantir a monitorização de sessões em tempo real.
  • Nas definições de SSID, defina o Protocolo de Segurança para WPA2 Enterprise ou WPA3 Enterprise [7] e selecione o Perfil RADIUS.

comparison_chart.png

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

Ao implementar portais cativos externos, os administradores de rede encontram frequentemente vários modos de falha comuns. A tabela abaixo detalha estes problemas, as suas causas de raiz e os passos de mitigação exatos:

Sintoma Análise da Causa de Raiz Ação Corretiva e Mitigação
Ecrã em Branco / Portal Não Carrega O dispositivo do 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 Pré-Autorizado.
2. Garanta que o cliente convidado recebeu um IP e servidor DNS válidos via DHCP.
3. Realize uma pesquisa de DNS no dispositivo do cliente para verificar a resolução do FQDN do portal.
Erro de SSL "Ligação Não Privada" O UniFi Controller está a utilizar um certificado autoassinado, ou o FQDN de redirecionamento não corresponde ao common name do certificado SSL. 1. Instale um certificado SSL publicamente fidedigno no UniFi Controller.
2. Verifique se a opção Redirect Using Hostname está ativada e se corresponde exatamente ao FQDN no certificado.
3. Desative o "Redirect HTTPS" nas definições de controlo de convidados do UniFi para evitar que o AP tente interceptar tráfego HTTPS na porta 443, o que naturalmente aciona avisos de SSL.
Autenticação Concluída com Sucesso, mas a Internet Está Bloqueada A nuvem Purple conseguiu autenticar o utilizador, 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) está aberta para tráfego de entrada no UniFi Controller a partir das gamas de IP da Purple.
2. Verifique se a Chave API ou as credenciais de administrador local introduzidas no Purple Portal são válidas e têm permissões de Administrador.
3. Verifique os registos do UniFi Controller (server.log) para identificar falhas de autenticação de API.
Os Botões de Login Social (ex. Google) Não Funcionam Os domínios de autenticação do IdP estão bloqueados pela lista de controlo de acesso do AP. 1. Adicione os domínios wildcard completos para o IdP específico à lista de Acesso Pré-Autorizado (ex. *.google.com, *.googleapis.com).
2. Se utilizar o Facebook, garanta que os domínios do Facebook SDK estão totalmente na lista branca.
Desconexões Frequentes / Pedidos de Reautenticação O tempo limite da sessão do UniFi Controller é inferior à duração da sessão do Purple, ou os tempos de concessão (lease) de DHCP são demasiado curtos. 1. Alinhe a definição de Session Timeout do UniFi Guest Hotspot com a política de sessão do Purple (ex.: 24 horas).
2. Aumente o tempo de concessão (lease) de DHCP na VLAN de Convidados para pelo menos 12 ou 24 horas para evitar a exaustão de endereços IP e a reautenticação a meio da sessão.

ROI e Impacto no Negócio

Embora a implementação de um Captive Portal externo exija uma engenharia de rede cuidadosa, os resultados de negócio e o retorno do investimento (ROI) superam amplamente a complexidade inicial da implementação.

Captura de Dados Empresariais e Enriquecimento de CRM

O portal de convidados nativo do UniFi é um utilitário "cego"; concede acesso à internet sem capturar a identidade do utilizador. Ao sobrepor o Purple, os espaços podem capturar dados primários valiosos (emails, números de telefone, perfis sociais) de forma totalmente em conformidade com o GDPR e a CCPA. Estes 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).

Gestão de Vários Locais e White-Labeling

Para Fornecedores de Serviços Geridos (MSPs) e operadores empresariais com vários locais, gerir o WiFi de convidados em centenas de espaços através de controladores UniFi individuais é altamente ineficiente. O Purple fornece um painel centralizado em nuvem único para gerir splash pages, termos de conformidade e análises em todos os espaços globalmente, independentemente da distribuição subjacente do controlador UniFi.

Análises em Tempo Real e Inteligência Espacial

O Purple transforma a rede sem fios UniFi num poderoso array de sensores. Ao analisar os pedidos de sonda (probe requests) e os metadados de ligação, o Purple fornece inteligência espacial profunda, incluindo:

  • Análise de Fluxo de Clientes: Total de visitantes, tráfego de passagem e taxas de conversão (passagem para entrada).
  • Tempo de Permanência: 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 regressam e o tempo decorrido entre visitas.
  • Mapas de Calor do Espaço: Representação visual do fluxo e densidade de visitantes, permitindo que os operadores de retalho e de espaços otimizem layouts e a alocação de pessoal.

Monetização através de Redes de Media de Retalho

Para grandes espaços, como estádios, centros comerciais e aeroportos, a splash page do Captive Portal representa um espaço digital altamente valioso. O Purple permite que os espaços monetizem este espaço integrando-se com redes de media de retalho, apresentando publicidade programática direcionada, experiências de login patrocinadas e promoções localizadas diretamente aos convidados no momento da ligação.

Referências

Definições Principais

Captive Portal

Uma página web que intercepta a ligação inicial de rede de um convidado e requer autenticação, registo ou aceitação de termos antes de conceder acesso total à internet.

Encontrado imediatamente após a ligação a um SSID de convidado aberto; gerido pelo redirecionador de AP e pelo servidor de portal externo.

External Portal Server

Uma aplicação web de terceiros (como a Purple) que aloja a splash page de convidados e lida com a autenticação do utilizador, contornando as limitações de portal do controlador integrado.

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

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

Uma lista de domínios, subdomínios ou endereços IP permitidos aos quais os clientes não autenticados podem aceder antes de concluírem o processo de início de sessão no Captive Portal.

Essencial para carregar a própria página do portal, recursos CSS/JS e endpoints de início de sessão OAuth de terceiros.

DNSmasq

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

Gere o redirecionamento DNS inicial que força os dispositivos dos clientes a acionar os seus assistentes integrados de Captive Portal.

Handshake de Autorização de API

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

Ocorre imediatamente após o utilizador concluir com sucesso o fluxo de início de sessão na splash page.

Isolamento de Dispositivo do Cliente

Uma funcionalidade de segurança que impede que os clientes sem fios no mesmo SSID ou VLAN comuniquem entre si, mitigando o risco de ataques na rede local.

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

RADSEC (RADIUS sobre TLS)

Um protocolo que protege o tráfego de autenticação e contabilização RADIUS, envolvendo-o num túnel TLS seguro, evitando a interceção e a adulteração em redes públicas.

Suportado no UniFi Network 8.4+ para implementações empresariais seguras em vários locais utilizando WPA2/WPA3 Enterprise.

CPA (Assistente de Captive Portal)

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

Aciona a janela pop-up 'Iniciar sessão no WiFi' no dispositivo do utilizador imediatamente após a ligação.

Exemplos Práticos

Um centro comercial com elevado fluxo de visitantes, equipado com 150 APs UniFi e uma aplicação UniFi Network auto-alojada em AWS, necessita de implementar o Purple. A equipa de TI pretende utilizar o login social da Google e do Facebook para a autenticação de convidados. No entanto, durante os testes iniciais, os convidados que clicam nos botões de login social deparam-se com um ecrã em branco ou com um erro de resolução de DNS.

O problema é causado por um walled garden restritivo (Pre-Authorization Access) que impede o dispositivo do convidado de resolver ou alcançar os endpoints de autenticação da Google e do Facebook antes de ser autorizado. Para resolver isto, o administrador de rede deve iniciar sessão na aplicação UniFi Network, aceder a Settings > Profiles > Guest Hotspot e expandir a secção Pre-Authorization Access. Deve adicionar os domínios wildcard completos para os fornecedores de identidade Google e Facebook. Para a Google, isto inclui accounts.google.com, ssl.gstatic.com e *.googleapis.com. Para o Facebook, é necessário *.facebook.com, *.facebook.net e *.fbcdn.net. Adicionalmente, certifique-se de que o âmbito DHCP da rede de convidados está configurado para distribuir servidores DNS públicos rápidos (ex.: 1.1.1.1 e 8.8.8.8) diretamente aos clientes, em vez de os apontar para o gateway UniFi local, o qual pode tornar-se um estrangulamento para consultas de DNS de pré-autorização.

Comentário do Examinador: Esta é uma falha clássica de 'lacuna no walled garden'. Como os fluxos de login social dependem de redirecionamentos OAuth complexos através de múltiplos subdomínios, a omissão de um único domínio de entrega de recursos (como o CDN do Facebook `fbcdn.net`) irá impedir a renderização da página. Os arquitetos de rede devem utilizar sempre wildcards (`*.domain.com`) quando suportados pelo controlador, e verificar a resolução de DNS a partir de um cliente não autenticado utilizando ferramentas padrão como `nslookup` ou `dig` contra os domínios permitidos.

Um MSP está a implementar o Purple numa cadeia de 50 hotéis boutique. Cada hotel dispõe de um UniFi Cloud Gateway Max local. O MSP pretende gerir todos os locais a partir de uma única conta Purple, mas está preocupado com a segurança e com a forma como a cloud do Purple comunicará com os controladores locais individuais para autorizar os endereços MAC dos convidados, dado 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 reencaminhamento de portas de entrada (port forwarding) ou um proxy inverso, combinados com DNS dinâmico (DDNS). Para cada hotel: 1) Configure um nome de anfitrião DDNS no Cloud Gateway Max (ex.: hotel01.mspdomain.com) para que o IP público do gateway seja sempre rastreável. 2) Configure uma regra de reencaminhamento de portas no gateway para reencaminhar o tráfego HTTPS de entrada numa porta alta não padrão (ex.: 10443) para o IP de gestão do gateway local na porta 443. 3) No controlador UniFi, aceda a Settings > Control Plane > Integrations e gere uma Chave de API única. 4) No Portal Purple, configure um 'Venue' exclusivo para cada hotel, selecionando a integração Ubiquiti UniFi. Introduza o endereço DDNS exclusivo com a porta reencaminhada (ex.: hotel01.mspdomain.com:10443) e a Chave de API específica gerada para esse local. Finalmente, proteja o reencaminhamento de portas de entrada em cada gateway, restringindo os IPs de origem aos intervalos de IP da cloud pública do Purple, evitando o acesso não autorizado a partir do resto da internet.

Comentário do Examinador: A utilização de uma porta alta e não padrão para o reencaminhamento de portas, combinada com uma lista restrita de IPs de origem permitidos para aceitar apenas os blocos de IP de cloud do Purple, mitiga os riscos de segurança de expor a porta da API do controlador à internet pública. Esta arquitetura evita a necessidade de IPs públicos estáticos dispendiosos em cada local, mantendo capacidades robustas de autorização de MAC em tempo real.

Perguntas de Prática

Q1. Um administrador de rede configurou um portal cativo externo numa rede de convidados UniFi. Durante os testes, nota que a splash page do Captive Portal carrega com sucesso, mas após o convidado introduzir o seu endereço de e-mail e clicar em 'Ligar', o navegador deixa de responder e acaba por apresentar um erro de limite de tempo esgotado. O cliente permanece em quarentena. Qual é a causa mais provável deste problema e como deve ser investigado?

Dica: A página do portal carregou, o que significa que o DNS e o walled garden estão a funcionar. A falha ocorre *após* o convidado submeter as suas credenciais.

Ver resposta modelo

A causa mais provável é uma falha no handshake de autorização da API entre a cloud da Purple e o UniFi Controller. Como a página do portal carregou e o convidado conseguiu interagir com ela, as configurações de DNS e de Acesso Pré-Autorizado (Walled Garden) estão corretas. No entanto, quando o convidado conclui a autenticação, a Purple tenta enviar uma chamada de API REST segura (pedido POST) ao UniFi Controller para autorizar o endereço MAC do cliente. Se o UniFi Controller estiver atrás de uma firewall, NAT ou numa rede privada sem o reencaminhamento de portas adequado, ou se as credenciais da API (ou Chave de API) estiverem incorretas, o pedido de autorização falhará ou expirará. Para investigar: 1) Verifique se o FQDN e a porta do UniFi Controller estão acessíveis publicamente a partir das gamas de IP da Purple. 2) Verifique as regras de entrada da firewall no gateway que protege o UniFi Controller para garantir que a porta 443 (ou 8443) está aberta. 3) No Portal Purple, verifique se as configurações de integração do UniFi contêm a Chave de API ou as credenciais de administrador corretas e se o URL do controlador está correto. 4) Inspecione o ficheiro server.log do UniFi Controller para verificar eventuais tentativas de ligação de entrada ou erros de autenticação de API a partir dos IPs da Purple.

Q2. Uma implementação empresarial exige a configuração de uma rede de convidados com um Captive Portal externo. O arquiteto de rede pretende utilizar HTTPS para todo o tráfego do Captive Portal para evitar a interceção de credenciais. Ativa a opção "Use Secure Portal (HTTPS)" e "Redirect Using Hostname" no UniFi, apontando para o FQDN do portal externo. No entanto, quando os clientes se ligam, os seus browsers apresentam imediatamente um aviso grave de "SSL Certificate Common Name Mismatch" ou "Certificate Not Trusted", bloqueando o acesso. Como pode isto ser resolvido?

Dica: Pense em qual o dispositivo que está a servir o redirecionamento inicial e que certificado SSL está a apresentar ao cliente.

Ver resposta modelo

Este problema ocorre porque o Ponto de Acesso ou o Controller UniFi está a tentar intercetar um pedido HTTPS do cliente e a redirecioná-lo para o Captive Portal. Quando um cliente se liga e tenta aceder a um website HTTPS (por exemplo, https://www.google.com), o redirecionador do AP interceta o tráfego. Para realizar o redirecionamento via HTTPS, o AP deve apresentar um certificado SSL. Como o AP não possui um certificado SSL válido para www.google.com, o browser do cliente deteta uma condição de Man-in-the-Middle (MITM) e apresenta um aviso de SSL grave. Para resolver isto: 1) Certifique-se de que o próprio UniFi Controller possui um certificado SSL válido e publicamente fidedigno instalado, correspondente ao seu FQDN configurado. 2) Nas definições de rede de convidados do UniFi, desative a opção "Redirect HTTPS" (deixe apenas o redirecionamento HTTP ativado). Isto evita que o AP tente intercetar o tráfego HTTPS. Em vez disso, a rede dependerá do Assistente de Captive Portal (CPA) do sistema operativo do dispositivo cliente, que testa a conectividade utilizando endpoints HTTP simples (por exemplo, http://captive.apple.com ou http://connectivitycheck.gstatic.com). O AP pode intercetar em segurança estes pedidos HTTP na porta 80 e redirecioná-los para o URL HTTPS seguro do portal Purple (https://portal.purplehotspot.com) sem acionar quaisquer avisos de SSL no browser.

Q3. Uma cadeia de hotéis pretende implementar a segurança WPA3-Enterprise para a sua rede de convidados VIP, mantendo a integração com a plataforma de analítica da Purple. A equipa de TI local não tem a certeza se pode utilizar o redirecionamento padrão de Captive Portal com um External Portal Server com o WPA3-Enterprise. Qual é a abordagem arquitetural correta para este cenário?

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

Ver resposta modelo

O WPA3-Enterprise (e o WPA2-Enterprise) utiliza a autenticação 802.1X, que é fundamentalmente incompatível com a redireção web padrão do Captive Portal. Numa rede 802.1X, a autenticação ocorre na fase de associação (Camada 2) usando métodos EAP (como EAP-TLS ou PEAP) antes de o cliente receber um endereço IP ou ser permitido na rede. Portanto, não é possível redirecionar um cliente para uma splash page baseada na web. Para integrar o WPA3-Enterprise com o Purple: 1) Mude do modelo de 'External Portal Server' para um modelo de RADIUS Externo. 2) Configure um Perfil RADIUS na UniFi Network Application, inserindo os endereços IP do servidor Cloud RADIUS do Purple, portas de autenticação (geralmente 1812), portas de accounting (geralmente 1813) e o segredo partilhado. 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 convidado VIP se liga, o seu dispositivo autentica-se diretamente contra o servidor Cloud RADIUS do Purple usando as suas credenciais ou certificado empresarial únicos. O servidor RADIUS do Purple autoriza a ligação e recebe as atualizações de accounting, permitindo ao local capturar métricas de ligação, duração da sessão e utilização de dados sem necessitar de uma splash page baseada na web.

Continue a ler esta série

Integração do CommScope Ruckus com o Purple WiFi: Guia de Instalação e Configuração

Este guia de referência técnica fornece um manual de configuração autoritativo para integrar arquiteturas CommScope Ruckus com o Purple WiFi. 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 utilizando Ruckus Dynamic PSK.

Ler o guia →

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

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

Ler o guia →

Integração de Pontos de Acesso Grandstream GWN com o Purple WiFi

Este guia de referência técnica detalha como integrar os pontos de acesso Grandstream GWN com a plataforma de Guest WiFi e analítica da Purple. Abrange a configuração do Captive Portal da Grandstream, definições de RADIUS AAA, configuração de walled garden, autenticação segura de funcionários 802.1X com direcionamento dinâmico de VLAN e segmentação PPSK multi-tenant — fornecendo orientações práticas e passo a passo para MSPs e equipas de TI que implementam WiFi para convidados e funcionários em grande escala.

Ler o guia →