Resolução de problemas do captive portal Ubiquiti UniFi: checklist de portal externo, hotspot e walled garden

Um Captive Portal UniFi falha por um de cinco motivos. O endereço do servidor de portal externo está incorreto, ou os domínios de portal e login estão ausentes do acesso de pré-autorização. O isolamento de convidados pode bloquear o host do portal. O redirecionamento pode usar HTTP para um endereço IP. Ou o console está inacessível. Verifique cada um por vez e, em seguida, teste a partir de um cliente.

Como é um Captive Portal UniFi que não está funcionando?

A maioria das falhas se apresenta como um de quatro sintomas. Identificar o sintoma primeiro restringe a causa antes de você abrir o aplicativo UniFi Network.

• Nenhum portal aparece. O dispositivo se conecta ao SSID de convidados e obtém um endereço IP, mas nenhuma tela de login aparece. O telefone pode relatar "sem internet" ou mostrar que está conectado, mas sem tráfego.
• Uma página em branco ou carregando infinitamente. O Captive Network Assistant (CNA) se abre, mas a splash page nunca é renderizada. O CNA é o pequeno navegador que seu sistema operacional inicia em uma rede cativa.
• Um aviso de certificado. Os notebooks mostram "Sua conexão não é privada" antes da página de login. Os convidados precisam clicar para ignorar o aviso e continuar.
• Um portal parcial. A splash page carrega, mas um botão de login social ou de pagamento fica girando, falha ou volta ao início.

O artigo de suporte do Captive Portal do Purple explica o CNA com mais detalhes. O CNA verifica um domínio predefinido para testar se a internet está acessível. Em seguida, ele notifica o dispositivo, inicia um navegador e confirma o status "online". Quando qualquer parte dessa cadeia falha, seus convidados veem um dos sintomas acima.

Este guia pressupõe que o seu portal de hotspot UniFi ou portal externo já está configurado. É uma lista de verificação para solução de problemas, não um guia de configuração.

O que geralmente faz um Captive Portal UniFi falhar?

Seis causas representam a maioria dos casos de solução de problemas do portal de convidados UniFi.

1. Configuração incorreta do servidor de portal externo. O endereço aponta para um host antigo, contém um erro de digitação ou aponta para um servidor que o gateway não consegue alcançar.
2. Acesso de pré-autorização incompleto. O UniFi rotula essa configuração como "Pre-Authorization Access". É o walled garden do UniFi: os hosts e sub-redes que um convidado pode acessar antes de fazer o login. Se o portal, seus recursos ou um provedor de login social estiverem ausentes, a página ficará em branco ou parcial.
3. Restrições de rede de convidados. As redes de convidados UniFi bloqueiam faixas de endereços privados. Um servidor de portal ou servidor DNS em uma sub-rede interna torna-se inacessível.
4. Incompatibilidades de redirecionamento de HTTPS e nome de host. Um redirecionamento HTTPS para um endereço IP, ou para um nome de host sem certificado correspondente, gera avisos no navegador.
5. Acessibilidade do controlador ou console. Os UniFi Network Servers auto-hospedados e os consoles em nuvem devem permanecer acessíveis. Com um portal externo, o controlador também deve alcançar o servidor RADIUS que conclui o login.
6. Interferência do lado do cliente. VPNs, configurações de DNS personalizadas ou uma notificação de CNA descartada impedem o redirecionamento naquele dispositivo.

Como identificar qual falha do Captive Portal UniFi você tem?

Comece pelo sintoma e execute a primeira verificação da tabela antes de alterar qualquer configuração.

Sintoma	Causa mais provável	Primeira verificação	Correção
Sem Captive Portal, sem solicitação de login	DNS inacessível ou teste de CNA bloqueado	O cliente consegue resolver um hostname público antes do login?	Disponibilize um servidor DNS fora dos intervalos privados bloqueados ou permita-o no acesso de pré-autorização
Página em branco ou carregando infinitamente	Host do Captive Portal ou recursos ausentes no acesso de pré-autorização	O hostname do Captive Portal resolve e carrega a partir de um dispositivo de convidado?	Adicione o host do Captive Portal, seus domínios de recursos e sua sub-rede ao acesso de pré-autorização
Aviso de certificado em laptops	Redirecionamento HTTPS para um endereço IP ou hostname incompatível	Qual URL aparece na barra de endereços quando o aviso é exibido?	Desative o redirecionamento HTTPS ou redirecione por hostname com um certificado publicamente confiável correspondente a esse hostname
Botão de login social gira ou falha	Domínios do provedor de identidade ausentes	Qual domínio falha na visualização de rede do navegador?	Adicione todos os domínios que a página de login do provedor carrega
Falha na etapa de pagamento	Domínios do gateway de pagamento ausentes	A página de pagamento chega a carregar?	Adicione os hosts do provedor de pagamento ao acesso de pré-autorização
Captive Portal carrega, mas o login nunca é concluído	RADIUS ou controladora inacessível	As tentativas de autenticação aparecem nos eventos da controladora?	Restabeleça a conectividade com a controladora e confirme se os dados do RADIUS coincidem com o seu provedor de Captive Portal
Um dispositivo falha, outros funcionam	VPN do lado do cliente, DNS personalizado ou CNA rejeitado	O site neverssl.com redireciona nesse dispositivo?	Desative a VPN ou o DNS personalizado, esquive a rede e conecte-se novamente

Dois testes rápidos separam a maioria das falhas. Primeiro, acesse neverssl.com em um dispositivo conectado, mas não autenticado. A equipe de suporte da Purple recomenda este site porque ele evita problemas com redirecionamentos SSL. Se o neverssl.com redirecionar para o seu Captive Portal, o redirecionamento funciona e a falha está no acesso de pré-autorização ou no próprio Captive Portal. Se não redirecionar, verifique o DNS, a configuração do servidor de Captive Portal externo ou a controladora.

Segundo, verifique a entrada do cliente no aplicativo UniFi Network. A lista de clientes e os eventos mostram se o dispositivo está na rede de convidados e se foi autorizado. Um dispositivo marcado como autorizado, mas que ainda exibe o Captive Portal, aponta para um problema de cache no lado do cliente ou de CNA.

Como você corrige cada causa do Captive Portal UniFi?

A Purple não reproduz os caminhos de menu do UniFi aqui, pois eles mudam entre as versões do UniFi Network. Use a documentação atual da Ubiquiti para a localização exata de cada configuração.

Servidor de Captive Portal externo

Confirme se o valor do servidor de Captive Portal externo coincide com o especificado pelo seu provedor de Captive Portal. Um único caractere incorreto direciona todos os convidados para um host inativo. Se você mudou de provedor de Captive Portal, remova o endereço antigo em vez de deixá-lo ao lado do novo. When you use Purple, the splash page servers collect guest details and issue a one-time login. The controller passes that login to Purple's RADIUS server to complete authentication. RADIUS is the protocol network equipment uses to check credentials against a central server. If the portal loads but login fails, check the RADIUS profile next.

Pre-authorisation access for the portal, social login and payment domains

This is the most common fix. Add these entries to pre-authorisation access:

• The portal server host and any subnet it lives on.
• Every domain the splash page loads, including fonts, images and scripts from content delivery networks.
• Each social login provider's authentication domains, if you offer Facebook, Google or Apple sign-in.
• Your payment gateway's hosts, if you charge for premium access.

Open the splash page from a laptop on an unrestricted network, with the browser's developer tools showing network requests. Every domain listed there must be reachable before login. Where your UniFi Network version accepts IP entries only, re-check them whenever a provider changes its addresses.

Guest network isolation and blocked subnets

Guest isolation does not block the captive portal on its own. Client device isolation stops guest devices from talking to each other. The guest network's subnet restrictions block private address ranges, and those restrictions catch internal portal or DNS servers.

If your portal server or DNS resolver sits on an internal subnet, add that specific host to pre-authorisation access. A cleaner pattern is to hand guests a public DNS resolver and host the portal on a public address.

HTTPS and hostname redirect options

Modern browsers expect HTTPS for login pages. Purple's Cisco WLC certificate article describes the same pattern on Cisco hardware. A redirect to an HTTP address such as a bare IP triggers a security warning, and guests must click through it.

The fix follows the same principle on UniFi. Either leave HTTPS redirection off and let the CNA use HTTP, or redirect by hostname. A hostname redirect needs a publicly trusted SSL/TLS certificate, and the hostname must match the certificate's Common Name. A self-signed certificate or a mismatched name brings the warning straight back.

Controller reachability for self-hosted and cloud consoles

For a self-hosted UniFi Network Server, confirm the server is running and reachable from your gateway and access points. Check firewall rules between sites if the server sits in a head office or data centre. For cloud consoles, confirm the console shows online and the gateway is adopted. Then confirm outbound traffic to your RADIUS server is allowed.

Client checks

Peça ao visitante para esquecer a rede e se reconectar. Desative qualquer VPN ou configuração de DNS personalizada, que podem ignorar totalmente o redirecionamento. Se a notificação do CNA foi perdida, abra um navegador e acesse neverssl.com. No Android, tocar na notificação "pode ser necessário fazer login" inicia a sessão do navegador CNA.

Exemplos práticos dos setores de hotelaria, varejo e eventos

Estes exemplos práticos mostram como a lista de verificação se aplica no nível do local.

Um hotel de 200 quartos com uma splash page em branco

Situação. Um hotel executava um UniFi Network Server auto-hospedado e um portal externo. Após uma alteração na rede, os hóspedes no SSID de convidados viam uma página em branco. A equipe da recepção registrava cerca de uma dúzia de reclamações por noite.

O que foi feito. O site neverssl.com não redirecionava, então a equipe verificou o DNS primeiro. O escopo DHCP da VLAN de convidados estava distribuindo um servidor DNS interno em uma sub-rede privada. As restrições de convidados bloqueavam essa sub-rede. A equipe alterou o escopo de convidados para um resolvedor público.

Resultado. Os redirecionamentos do portal funcionaram na conexão seguinte. A recepção não registrou mais reclamações de WiFi naquela semana.

Uma rede de varejo de 40 lojas com um login social travado

Situação. Uma rede de varejo adicionou login social à sua splash page. O formulário de e-mail funcionava, mas o botão social carregava indefinidamente em todas as lojas.

O que foi feito. A equipe abriu a splash page com as ferramentas do desenvolvedor e listou todos os domínios que o login do provedor carregava. Eles adicionaram esses domínios ao acesso de pré-autorização em uma loja piloto, testaram no Android e no iOS e, em seguida, aplicaram a alteração em todas as 40 lojas.

Resultado. O login social foi concluído em todas as 40 lojas. A equipe agora testa novamente a loja piloto após cada atualização do provedor.

Um centro de convenções com avisos de certificado

Situação. Os participantes em laptops viam "Sua conexão não é privada" antes do portal. Os celulares funcionavam por meio do CNA, então a falha parecia intermitente.

O que foi feito. A barra de endereços mostrava um redirecionamento HTTPS para um endereço IP. A equipe desativou o redirecionamento HTTPS até que um certificado publicamente confiável correspondente ao nome de host de redirecionamento estivesse ativo.

Resultado. O aviso desapareceu nos laptops. O suporte do evento parou de receber chamados sobre o portal pelo resto da conferência.

Como evitar que o Captive Portal do UniFi falhe novamente?

• Mantenha um registro de pré-autorização. Liste todos os hosts e sub-redes, o motivo de estarem lá e quem é o proprietário. Revise-o sempre que adicionar um método de login ou provedor de pagamento.
• Teste após cada alteração. Use um celular Android, um iPhone e um laptop. Confirme se o neverssl.com redireciona e se o login é concluído.
• Monitore a expiração do certificado. Um certificado expirado em um redirecionamento de nome de host produz o mesmo aviso que a ausência de certificado.
• Monitore o controlador. Configure alertas para quando um servidor auto-hospedado ficar offline, antes que os visitantes percebam.
• Execute uma rede de convidados aberta. A Purple recomenda redes de convidados abertas porque a familiaridade reduz a fricção no login.

A mesma disciplina se aplica a outros fabricantes. O guia de resolução de problemas do captive portal da HPE Aruba do Purple e o guia de resolução de problemas do captive portal da Cisco Meraki do Purple seguem a mesma lista de verificação para essas plataformas.

Perguntas frequentes

O Purple funciona com os pontos de acesso Ubiquiti UniFi que já possuímos?

Sim, o Purple funciona no Ubiquiti UniFi como um portal externo e serviço RADIUS, para que você mantenha seus pontos de acesso existentes. O Purple é agnóstico em relação ao hardware e também suporta Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Cambium, Extreme e Fortinet. Isso é importante para propriedades com vários locais e hardware misto, pois uma única configuração de Guest WiFi atende a todos os fabricantes. A plataforma do Purple opera em mais de 80.000 locais ativos, de acordo com os próprios dados do Purple.

Podemos manter um UniFi Network Server auto-hospedado com um portal externo?

Sim, um UniFi Network Server auto-hospedado funciona com um portal externo, desde que permaneça acessível. O gateway e os pontos de acesso devem alcançar o servidor, e o servidor deve alcançar o serviço RADIUS do seu provedor de portal. Verifique as regras de firewall entre os locais se o servidor estiver localizado em uma matriz. Os consoles em nuvem eliminam a tarefa de hospedagem, mas ainda precisam de acesso de saída para o RADIUS.

Nossa rede de convidados UniFi deve ser aberta ou protegida por senha?

Aberto é a escolha recomendada para acesso de convidados. O Purple recomenda fornecer Guest WiFi em uma rede aberta porque este é o padrão atual e reduz a fricção no login. O Captive Portal ainda controla o acesso, coleta opt-ins de escolha consciente e emite para cada convidado um login de uso único. Redes de convidados protegidas por senha adicionam uma etapa extra e geram mais dúvidas na recepção.

Precisamos comprar um certificado SSL para o nosso captive portal?

Sim, se você redirecionar os convidados via HTTPS ou por nome de host. Os navegadores esperam um certificado confiável publicamente, e o nome de host de redirecionamento deve corresponder ao Common Name do certificado. Sem ele, os laptops exibem um aviso de segurança antes que o portal seja carregado. Se você não puder manter um certificado, deixe o redirecionamento HTTPS desativado e permita que o CNA do dispositivo use um redirecionamento HTTP em vez disso.

Como a mudança para o Purple afeta nossa conformidade com a GDPR?

O Purple ajuda você a atender à GDPR em vez de adicionar riscos. O Purple possui as certificações ISO 27001, GDPR, CCPA e Cyber Essentials, e a splash page registra opt-ins de escolha consciente para consentimento de marketing. Os dados primários que você coleta permanecem vinculados ao consentimento que cada convidado deu. O seu próprio aviso de privacidade e política de retenção ainda se aplicam, portanto, revise ambos antes do lançamento.

Quanto esforço é necessário para migrar do hotspot UniFi integrado para o Purple?

Mudar para o Purple é uma alteração de configuração, não um projeto de hardware. Você direciona o servidor do portal externo e as configurações de RADIUS para o Purple, depois atualiza o acesso de pré-autorização para os domínios da splash page. O Purple funciona integrado sobre a sua infraestrutura UniFi existente, então não há necessidade de substituição de equipamentos. Teste um local primeiro e, em seguida, copie as configurações para todo o seu portfólio.

O Purple consegue gerenciar o login de convidados em locais de alto volume?

Sim, o Purple processou 440 milhões de logins em 2024, de acordo com os dados do próprio Purple. Esse volume abrange hotéis, varejo, trens e estabelecimentos de saúde com picos intensos. No UniFi, a capacidade no portal raramente é o gargalo. A acessibilidade do DNS e o acesso completo à pré-autorização são mais importantes, portanto, aplique esta lista de verificação antes de um grande evento.