Manual de integração — UniFi Controller

Integração do CaptiveWeb com UniFi Network Application self-hosted (7.x / 8.x) rodando em Linux, Windows ou UniFi OS Console (UDM, UCK Gen2+, UDR). A autorização dos convidados é feita via API local do controller — o CaptiveWeb chama a API do UniFi para liberar o acesso do cliente após autenticação no portal.

1. Criar conta de serviço local no UniFi

O CaptiveWeb precisa de uma conta administrativa para chamar a API do UniFi. Não use sua conta principal — crie uma conta de serviço dedicada com acesso mínimo necessário.

1a. UniFi OS Console (UDM Pro, UDM SE, UCK Gen2+, UDR, UX)

1. Acesse Settings → Admins & Users

   No painel do UniFi OS, vá em Settings → Admins & Users e clique no botão + para adicionar um admin.

2. Desative o Acesso Remoto

   Desmarque a opção "Remote Access" (ou "Usar conta UI.com"). Isso cria uma conta local — sem MFA, sem dependência de cloud. Contas cloud exigem MFA obrigatório desde julho/2024 e quebram integrações automatizadas.

3. Defina usuário e senha

   Digite um nome de usuário de serviço (ex.: captiveweb-svc) e uma senha forte. Sem e-mail necessário para contas locais.

4. Atribua o papel correto

   Em Network, selecione Administrador do Site (Site Administrator). Em Control Plane, deixe como Nenhum. Clique em Add.

1b. Network Application self-hosted (Linux / Windows — sem UniFi OS)

1. Acesse Settings → Admins

   No controller, vá em Settings → Admins e clique em +.

2. Desmarque "usar conta UI"

   Desmarque a opção "This admin will use a UI account". Isso habilita conta local sem nuvem.

3. Defina usuário, senha e papel

   Digite o usuário (ex.: captiveweb-svc), senha, e selecione o papel Site Administrator. Clique em Add.

2. Cadastrar a controladora no painel CaptiveWeb

1. Acesse Equipamentos → Nova controladora

   No painel CaptiveWeb, vá em Equipamentos → Nova controladora.

2. Selecione o tipo e preencha os dados

   Escolha UniFi Controller (API local). Informe o IP ou hostname do controller e a porta (padrão 8443 para self-hosted; 443 para UniFi OS). Informe o usuário e senha criados no passo anterior.

3. Salve e copie a Bridge URL

   Após salvar, o painel exibirá a URL para External Portal Server. Copie essa URL — ela será usada no UniFi. Formato: https://portal.captiveweb.com.br/public/portal-connect/unifi-redirect?key=SUA_CHAVE

3. Criar SSID de Convidados no UniFi

Se ainda não possui uma rede Wi-Fi de convidados, siga estes passos. Pule se já tiver um SSID configurado.

1. Crie a rede de convidados (VLAN)

   Em Settings → Networks → Create New, crie uma rede chamada "Convidados". Configure sub-rede isolada (ex.: 10.100.0.0/24), VLAN ID (ex.: 100), DHCP Server ativo e Client Isolation ON.

2. Crie o SSID de convidados

   Em Settings → WiFi → Create New: defina o nome do Wi-Fi (ex.: "WiFi Convidados"), deixe a senha em branco (rede aberta — obrigatório para o redirect do portal funcionar), associe à rede de Convidados criada acima e ative Client Isolation.

3. Ative o Hotspot Portal no SSID

   Na mesma tela de configuração do SSID, role até a seção Hotspot e ative o toggle "Hotspot Portal". Isso habilita o captive portal para este SSID.

4. Configurar External Portal Server no UniFi

No UniFi Network 8.x, a configuração global do portal está em Insights → Hotspot → Landing Page:

1. Acesse Insights → Hotspot → Landing Page

   No menu lateral esquerdo do UniFi, clique em Insights e depois em Hotspot. Abra a aba Landing Page.

2. Selecione External Portal Server

   Na aba Authentication, em Type, selecione External Portal Server. Em Template, selecione Custom.

3. Configure o endereço do portal

   Em IPv4 Address, informe o IP do servidor CaptiveWeb. Em Redirect Hostname, informe portal.captiveweb.com.br. Ative "Use Secure Portal" para forçar HTTPS.

4. Configure a expiração da sessão

   Na aba Settings, ajuste o campo Default Expiration conforme o plano padrão (ex.: 480 minutos para 8 horas). Este valor é o timeout máximo de sessão no UniFi — o CaptiveWeb pode definir valores menores via API por plano.

5. Salve as configurações

   Clique em Apply Changes.

5. Walled Garden — Pre-Authorization

Em Insights → Hotspot → Landing Page → aba Pre-Authorization, clique em "Add Hostname, IP or Subnet" e adicione cada entrada abaixo:

portal.captiveweb.com.br
*.captiveweb.com.br
fonts.googleapis.com
fonts.gstatic.com
*.mercadopago.com
*.mercadolibre.com
*.asaas.com

No UniFi 7.x, a lista fica em Settings → Guest Control → Access Control → Pre-Authorization Access.

6. Limite de banda por plano (opcional)

Para aplicar limite de download/upload na rede de convidados:

1. Acesse Settings → Traffic Management

   Clique em Add Rule, selecione a rede de Convidados como alvo e defina os limites de download e upload em Mbps.

O CaptiveWeb também pode enviar os atributos up (kbps) e down (kbps) diretamente na chamada de autorização da API, sobrescrevendo o limite da regra global para cada cliente individualmente.

7. Atalho: importar configuração via ZIP

O CaptiveWeb gera um arquivo ZIP com as configurações de Guest Control e Walled Garden prontas para importar:

1. Baixe o ZIP no painel

   No painel CaptiveWeb, acesse o equipamento UniFi e clique em Baixar configuração ZIP.

2. Importe no UniFi

   No UniFi Controller, vá em Settings → System → Import e envie o arquivo ZIP. As configurações de External Portal e Walled Garden serão aplicadas automaticamente.

Modelos compatíveis