Portal de convidados Ubiquiti UniFi não redireciona: causas e correções

Um Captive Portal UniFi geralmente deixa de redirecionar porque o SSID já não é um Hotspot ativo, o utilizador convidado não se encontra no estado não autorizado, os caminhos de pré-autorização necessários não conseguem alcançar o serviço externo, ou o portal não consegue comunicar a autorização à UniFi. Verifique estes passos exatamente por esta ordem 1 2 3.

Que condições devem ser cumpridas para que ocorra o redirecionamento de convidados UniFi?

Este é um guia de resolução de problemas para uma configuração que anteriormente funcionava. Não lhe será pedido que reconstrua a sua rede WiFi de convidados do zero. Em vez disso, o guia avança do dispositivo convidado para a controladora, e depois regressa através do serviço externo. Esta ordem previne um erro comum: modificar um SSID, uma firewall ou uma configuração de DNS antes de saber qual foi o passo que realmente falhou.

A Ubiquiti define um Hotspot como a funcionalidade que pode ser aplicada a um SSID WiFi ou a uma rede ou VLAN inteira. O Captive Portal é depois ativado dentro dessa configuração de Hotspot. Consequentemente, uma VLAN de convidados, um SSID de convidados ou uma política de isolamento de rede não provam por si só que o fluxo de redirecionamento está ativo. Se a interface de utilizador da aplicação UniFi Network mudou após uma atualização, confirme o estado atual do Hotspot e do Captive Portal seguindo a documentação oficial da Ubiquiti, em vez de confiar na localização histórica do menu. 1

Para um portal externo, a Ubiquiti descreve um percurso de utilizador preciso. Um dispositivo liga-se a um SSID configurado com Hotspot e Captive Portal. Começa como GUEST com authorised: false. Quando tenta fazer um pedido web, a UniFi redireciona-o para o servidor do portal externo. O servidor recebe os detalhes de identificação do cliente e do ponto de acesso, obtém o ID do cliente UniFi e, em seguida, solicita a autorização através da API Network. Um fluxo concluído com sucesso resulta em authorised: true. 2

A regra de diagnóstico: não considere a condição "ligado ao WiFi" como a condição de sucesso. A condição de sucesso é um cliente de teste não autorizado que alcança o serviço de início de sessão pretendido, conclui o respetivo processo, mostra authorised: true e, em seguida, recebe o acesso pretendido. 2

Do que precisa antes de iniciar o isolamento de falhas?

Utilize um dispositivo de teste novo e não autorizado. Um dispositivo já autorizado é uma ferramenta de diagnóstico fraca porque pode saltar a etapa que precisa de examinar. Registe o SSID ou o nome da rede, a hora do teste, o tipo de dispositivo, o sistema operativo e se o dispositivo apresenta um pedido de início de sessão automático ou apenas um resultado normal do navegador. A Apple afirma que o iOS e o macOS enviam um probe no primeiro acesso a uma rede para detetar a interceção do Captive Portal e apresentar uma página de início de sessão. Isso significa que a falta de uma janela automática é uma pista útil, mas não é uma prova conclusiva de que o gateway não consegue redirecionar um pedido normal do navegador. [4]

Mantenha o teste circunscrito. Não comece por adicionar regras de acesso de convidados amplas. Não elimine uma integração que funciona. Não copie uma lista de permissões de pré-autorização de outra instalação. É necessário estabelecer o caminho real do convidado e a fase exata em que ocorre a falha. Se o problema afetar vários locais, execute o mesmo teste com um dispositivo novo em cada um deles. Uma diferença entre os locais é mais útil do que uma teoria sobre uma atualização do controlador partilhado.

Para uma implementação Purple, mantenha o artigo atual UniFi Integration: Best Practices & Common Questions aberto durante o teste. A Purple utiliza um início de sessão direto na API do controlador em vez de um canal de autenticação em segundo plano RADIUS. A conta de API dedicada deve, portanto, ser local no controlador, ter direitos de escrita como administrador, ter o 2FA desativado e não exigir a alteração de palavra-passe. A Purple também documenta vários requisitos de posicionamento de conta para consolas de hardware e para o UniFi OS Server autoalojado. 3

Como isolar a etapa com falha?

Comece pelo nível de acesso. Confirme se o SSID WiFi afetado, ou a respetiva configuração de toda a rede, ainda está definido como Hotspot com o Captive Portal ativado. A Ubiquiti documenta o caminho atual do WiFi-SSID e documenta separadamente um caminho de Zona de Hotspot para uma configuração de toda a rede ou VLAN. Esta distinção é a resposta à confusão comum de UniFi guest network vs hotspot. Uma rede de convidados isolada pode ser o segmento correto e, mesmo assim, falhar ao iniciar o fluxo de trabalho de início de sessão se a funcionalidade de Hotspot não estiver ativa. 1 A seguir, inspecione o cliente recém-conectado. Deve verificar o estado não autorizado documentado, e não apenas uma simples associação sem fios. Se o estado não estiver presente, volte à configuração do Hotspot e ao SSID ou rede selecionada. Não proceda com o DNS, um fornecedor externo ou uma integração UDM Pro até que esta fase esteja correta. Um serviço externo não pode autorizar um convidado que nunca entrou no fluxo do Hotspot externo. 2

De seguida, acione um pedido web normal a partir do mesmo dispositivo. Se o pedido chegar ao serviço externo, guarde o resultado como prova. Caso contrário, concentre-se no caminho de pré-autorização do segmento de convidados. A Purple apenas liga os convidados após a conclusão do seu processo externo, e as suas diretrizes de suporte associam um ecrã em branco após o envio do formulário a regras de convidados que bloqueiam o tráfego web oculto necessário para concluir o início de sessão. Verifique a ACL de Pre-Auth e as definições de pós-autorização. Declare as rotas de encaminhamento de destino essenciais retiradas da documentação atual do fornecedor. 3

Nesta fase, mantenha preciso o termo allow list. Não se trata de uma lista de destinos web gerais para um convidado autorizado. É o conjunto de caminhos necessários antes da aprovação, como o serviço externo e os elementos necessários para concluir a transação de login. O artigo de suporte da Purple é a fonte autorizada para os seus requisitos atuais. Introduza o link para o artigo de suporte no seu ticket de incidente e registe a data da versão, em vez de incorporar uma lista copiada e desatualizada num runbook. 3

Como se verifica a autorização do portal externo e o caminho UDM?

Se a página de login carregar, a sua investigação passa da interceção para a autorização. A Ubiquiti afirma que o redirecionamento passa o endereço MAC do ponto de acesso, o endereço MAC do cliente, o URL original solicitado e o SSID para o portal externo. O serviço externo pode utilizar o endereço MAC do cliente para obter o ID do cliente a partir da API de rede e, em seguida, emitir um pedido de autorização. A confirmação do lado do controlador é o estado authorised: true do cliente. 2

Examine as provas nesta ordem. Em primeiro lugar, o fornecedor recebeu um redirecionamento para o cliente afetado? Em segundo lugar, identificou o mesmo cliente listado pela UniFi? Em terceiro lugar, enviou um pedido de autorização? Em quarto lugar, a UniFi comunicou o cliente como autorizado? Esta sequência fornece a uma equipa de TI local e a um MSP um registo de incidente partilhado. Além disso, interrompe o ciclo improdutivo em que uma parte afirma que "o portal carregou" enquanto a outra alega que "o firewall está bem".

A questão relativa ao UDM Pro guest portal requer a mesma verificação, com um controlo adicional sobre a classificação do controlador. As diretrizes da Purple indicam que as implementações atuais em consolas de hardware UniFi e em versões modernas do UniFi OS Server devem utilizar a opção de integração UniFi Network atual, enquanto apenas as aplicações de controlador standalone mais antigas e desatualizadas utilizam a seleção legacy. Nas consolas de hardware, a Purple sugere a criação da conta dedicada no painel principal do UniFi OS. Se uma implementação tiver sido atualizada, migrada ou reclassificada, reveja a localização dessa conta e a classificação da integração antes de alterar as políticas de firewall para convidados. 3

Le linee guida di supporto di Purple identificano inoltre la raggiungibilità del controller come un confine separato. Se il servizio esterno non riesce a raggiungere il tuo controller al suo indirizzo pubblico stabile o FQDN attraverso il percorso approvato del firewall, l'autorizzazione non può essere completata. Verifica l'indirizzo registrato per l'integrazione, il relativo percorso in entrata e le regole di consenso approvate dal provider. Segui l'articolo di supporto per i passaggi di implementazione correnti e appropriati per la versione, anziché riprodurre i valori di connessione in una checklist locale. 3

Cosa va storto e come risolvere il problema?

La rete ospite è isolata, ma la pagina di accesso non si avvia mai

Gestisci questo problema come una verifica dello stato dell'Hotspot prima di un incidente DNS. Conferma se l'SSID WiFi o la rete interessata ha la funzione Hotspot e Captive Portal abilitata. Ubiquiti separa esplicitamente una configurazione Hotspot solo WiFi da una configurazione dell'intera rete o VLAN. Ripristina la configurazione desiderata, riconnetti un nuovo dispositivo e conferma che UniFi registri ora un ospite non autorizzato prima di testare qualsiasi collegamento esterno. 1 2

Il reindirizzamento fallisce prima che la pagina esterna venga caricata

Gestisci questo problema come un test del percorso di pre-autorizzazione. Acquisisce il resolver DNS del dispositivo ospite, il risultato della risoluzione di destinazione e l'esito del browser. Successivamente, confronta le regole degli ospiti con i requisiti attuali del provider del portale. Le linee guida di Purple sono specifiche: quando un ospite visualizza una schermata vuota dopo l'invio del modulo, le impostazioni della Pre-Auth ACL o di post-autorizzazione potrebbero bloccare il traffico necessario per completare il processo. Non sostituire una policy di pre-autorizzazione mirata con un ampio accesso internet per gli ospiti. 3

La pagina esterna si carica, ma l'ospite rimane offline

Questo è un limite di autorizzazione. Convalida l'identità del client nell'evento del provider, la richiesta del provider a UniFi e lo stato finale del client del controller. Il flusso esterno di Ubiquiti distingue il reindirizzamento dalla successiva azione di autorizzazione tramite API. Il caricamento di una pagina dimostra che la prima fase è avvenuta, ma non prova che il client sia stato successivamente contrassegnato come autorizzato. 2

Un aggiornamento di UniFi Network o di UDM ha modificato il percorso previsto

Não assuma que uma configuração antiga do controlador ainda corresponde à integração atual. O Purple distingue uma implementação moderna da UniFi Network de um controlador standalone anterior e documenta diretrizes separadas para a criação de contas para consolas de hardware e UniFi OS Server self-hosted. Verifique novamente a conta local dedicada, a sua permissão de escrita, o estado da 2FA, a definição de alteração de palavra-passe e a classificação da integração. Em seguida, execute novamente o teste com um novo dispositivo. 3

O Pi-hole ou a filtragem de DNS a montante podem bloquear o hotspot UniFi?

Pode fazer parte da análise, mas não deve ser a conclusão sem provas. As fontes primárias aprovadas não estabelecem que o Pi-hole seja a causa de um erro de redirecionamento UniFi. Trate o DNS como um caminho mensurável. Confirme o resolver fornecido ao segmento guest, verifique se o destino do serviço externo se resolve, teste o caminho de DNS aprovado sob controlo de alterações e compare os resultados. O probe de dispositivo Apple é outro motivo para registar tanto a experiência de início de sessão automático como um pedido normal do browser. [4]

Como se prova que a solução funciona antes do próximo período de pico?

Utilize uma verificação de lançamento repetível. Deve seguir o mesmo caminho que um visitante real, não apenas uma simples verificação de conectividade do controlador. Primeiro, desassocie a rede ou utilize um novo dispositivo de teste. Segundo, ligue-se ao SSID afetado. Terceiro, confirme que o cliente não está autorizado. Quarto, inicie um pedido web normal. Quinto, confirme que o serviço externo recebe o redirecionamento. Sexto, conclua o processo de início de sessão aprovado. Sétimo, confirme o estado authorised: true e teste o acesso normal. 2

Execute a verificação antes das chegadas de pico numa estrutura do setor de Hospitality, antes de um período de campanha no Retail, antes de um evento nos Transport ou antes que aumente a procura dos visitantes no Healthcare. Guarde o resultado como um registo operacional: resultado positivo ou negativo em cada passo, tipo de dispositivo, classificação do controlador e qualquer alteração aplicada. Isto é muito mais útil do que um aviso genérico de "WiFi de convidados indisponível".

Cenário de exemplo real: incidente de ecrã em branco num hotel

Um hotel com 200 quartos relata que os hóspedes se ligam ao SSID da marca, mas veem uma página de início de sessão em branco. O engenheiro de serviço utiliza um novo dispositivo e confirma o estado authorised: false, o que significa que a fase de Hotspot está presente. A página começa a carregar, mas a transação não é concluída. O engenheiro compara as rotas de pré-autorização de convidados com as diretrizes atuais de suporte do fornecedor, valida o resolvedor efetivamente atribuído ao segmento de convidados e repete o teste. A condição de conclusão mensurável é que o dispositivo conclua o início de sessão, mude para authorised: true e atinja o acesso esperado. 2 3

Cenário de exemplo real: pontos de venda retail após alteração de controlador

Uma equipa de retail relata que os compradores se ligam a um SSID isolado, mas nunca veem a página de início de sessão após uma alteração do controlador. O engenheiro não começa pelo DNS. Confirma que o SSID está isolado e, em seguida, verifica se as opções de Hotspot e Captive Portal estão ativadas na configuração UniFi atual. Após restaurar o estado de Hotspot pretendido, volta a ligar um novo dispositivo e verifica o estado não autorizado documentado antes de testar o serviço externo. O resultado observável é um evento de redirecionamento seguido de um estado de autorização concluído. 1 2

Cenário de exemplo real: falha na autorização externa num centro de congressos

A página de início de sessão de um centro de congressos carrega e aceita o formulário de convidado, mas os participantes continuam offline. A equipa regista o endereço MAC do cliente e verifica o evento do fornecedor externo para o redirecionamento. Em seguida, valida se o fornecedor reconheceu o mesmo cliente, enviou o pedido de autorização e se o UniFi regista authorised: true. Para uma integração Purple, também verificam a conta API local, as permissões de escrita, a definição de 2FA e a classificação atual do controlador. O resultado esperado é uma cadeia de provas rastreável, e não uma suposição sobre a causa. 2 3

Assim que o incidente estiver encerrado, utilize o mesmo controlo de libertação no seu processo operacional de Guest WiFi. A secção Guest WiFi fornece o contexto do serviço, enquanto o WiFi Analytics pode ajudar as equipas operacionais a monitorizar a experiência pós-restauro. Para controlos operacionais adjacentes, consulte Guest WiFi Management: Smart Authentication & Segmentation, Cloud Wifi Management: Secure Enterprise Connectivity 2026, o guia Cisco Meraki splash page not working: a troubleshooting flowchart e WiFi 7 Venue Deployment: Infrastructure Readiness for Stadiums and Hospitality Sites.

Perguntas frequentes

Preciso de uma VLAN guest e de um UniFi Hotspot para mostrar uma página de início de sessão?

Não. A Ubiquiti documenta um Hotspot tanto num SSID WiFi como numa rede ou VLAN inteira. A condição fundamental é que o respetivo SSID ou rede tenha a função Hotspot e Captive Portal ativada. Uma VLAN guest isolada é uma escolha de segmentação. Não estabelece por si só o estado de cliente não autorizado nem inicia um redirecionamento externo. 1 2

O que deve ser inserido numa lista de pré-autorização UniFi?

Apenas os caminhos necessários para concluir o processo de início de sessão de guest selecionado antes da aprovação. A Purple associa ecrãs em branco pós-formulário a regras de guest que bloqueiam o tráfego necessário para concluir o acesso. Verifique a ACL de pré-autorização e as definições de pós-autorização comparando-as com a documentação atual do seu fornecedor. Não copie uma lista de domínios de outro site nem adicione acesso à internet não protegido apenas para carregar a página. 3

Porque é que o portal de guest UniFi parou de funcionar após uma atualização da aplicação?

Verifique o estado do Hotspot, a classificação do controlador e a conta de integração antes de modificar a rede. A documentação atual da Ubiquiti distingue a configuração do Hotspot de uma rede guest geral. A Purple também distingue as integrações de rede UniFi atuais das implementações com controladores autónomos legados, com diretrizes diferentes para contas de consolas de hardware e UniFi OS Server auto-hospedado. Execute novamente o teste com um dispositivo limpo após cada correção. 1 3

Porque é que um portal externo carrega no meu UDM Pro mas não autoriza o guest?

Uma página carregada demonstra a fase de redirecionamento, não a fase de autorização final. Verifique se o fornecedor externo recebeu a identidade do cliente, encontrou a correspondência com o cliente UniFi, enviou um pedido de autorização e se o controlador mostra authorised: true. Para a Purple, verifique também se a conta local dedicada dispõe de permissões de escrita, não tem 2FA e não apresenta alterações obrigatórias de palavra-passe. 2 3

O Pi-hole interrompe o redirecionamento do hotspot UniFi?

Não assuma que seja esse o caso. As fontes primárias aprovadas não identificam o Pi-hole como uma causa principal comprovada para o UniFi. Teste o resolver real do segmento guest, a resolução de destino e o caminho DNS aprovado sob controlo de alterações. Registe tanto o pedido automático do dispositivo como o resultado de um browser normal, uma vez que os dispositivos Apple utilizam uma verificação de rede captive ao ligarem-se. [4]

Preciso de substituir os meus access points UniFi para resolver um erro de redirecionamento?

Não, não como primeira medida. O fluxo externo documentado indica uma sequência de passos de configuração e autorização: estado do Hotspot, estado do cliente não autorizado, redirecionamento, processamento externo e aprovação do controlador. Identifique o passo que falhou com um novo dispositivo de teste antes de considerar uma substituição de hardware. 1 2

Referências

[4]: https://developer.apple.com/news/?id=q78sq5rv "Apple Developer: How to modernize your captive network"` your network"