Ver transcripción del podcast
Captive Portal for Ubiquiti UniFi - A Purple Technical Briefing
[INTRODUCTION & CONTEXT - approximately 1 minute]
Welcome to the Purple Technical Briefing series. I'm your host, and today we're getting into the specifics of deploying an external captive portal on Ubiquiti UniFi infrastructure - one of the most widely deployed network platforms in hospitality, retail, and enterprise environments globally.
If you're an IT manager, network architect, or systems integrator working with UniFi Cloud Gateways, Dream Machines, or the UniFi Network Application, this episode is for you. We're going to walk through exactly how the external portal mechanism works under the bonnet, how to configure it correctly, where the common pitfalls are, and why overlaying Purple on top of a UniFi deployment is the right architectural decision for venues that need more than a basic splash page.
Let's get into it.
[TECHNICAL DEEP-DIVE - approximately 5 minutes]
First, let's understand what's actually happening when a guest connects to a UniFi SSID that has a captive portal enabled.
When a guest device associates with your guest SSID, the UniFi Access Point assigns it an IP address via DHCP as normal. But the device is immediately placed in what UniFi calls a "pending" state. In this state, the AP's built-in DNSmasq process intercepts every DNS query the device makes, regardless of what DNS server the device thinks it's using. The AP redirects all DNS traffic to itself.
Simultaneously, the AP runs a lightweight HTTP redirector on port 80. The moment the guest's browser makes any HTTP request - and this is the key word, HTTP, not HTTPS - the redirector fires back a 302 redirect, sending the browser to the captive portal splash page. This is the mechanism that triggers the "Sign in to WiFi" notification on iOS and Android devices.
Now, this is where the built-in portal versus external portal distinction becomes critical. With the built-in UniFi Hotspot Portal, the splash page is served directly by the UniFi Network Application. It's functional, it's quick to set up, but it's severely limited. You get basic password authentication, vouchers, and Stripe payments. There's no email capture, no social login, no GDPR consent management, no CRM integration, and no meaningful analytics beyond session counts.
When you configure an External Portal Server - which is the setting we're focused on today - you're telling the UniFi controller to redirect guests to a completely separate web application. In our case, that's Purple. The URL you enter in the External Portal Server field becomes the destination for all those 302 redirects.
Este es el detalle técnico importante sobre esa URL de redirección. Cuando UniFi redirige a un invitado a su portal externo, añade varios parámetros de consulta a la URL. Estos incluyen: la dirección MAC del AP, la dirección MAC del dispositivo cliente, una marca de tiempo Unix, la URL original que el cliente intentaba alcanzar y el nombre del SSID. Su portal externo - Purple en este contexto - captura esos parámetros, los utiliza para identificar el dispositivo que se conecta, presenta la página de inicio correspondiente, gestiona la autenticación y, a continuación, realiza una llamada API de vuelta a la aplicación de red UniFi para autorizar esa dirección MAC.
Esa llamada API es el saludo de conexión crucial. A partir de UniFi Network Application 9.1 y versiones posteriores, existe una API REST oficial con autenticación adecuada basada en claves. El endpoint de autorización es una solicitud POST a la versión uno de la API de sitios, dirigida al ID de cliente específico, con un cuerpo JSON que puede especificar límites de tiempo en minutos, límites de uso de datos en megabytes y límites de velocidad en kilobits por segundo. Una vez que el controlador recibe esa autorización, envía la instrucción al AP y el invitado pasa de estar pendiente a estar autorizado. Se concede el acceso a Internet.
Hablemos ahora del Walled Garden, que UniFi denomina Acceso previo a la autorización. Se trata de la lista blanca de dominios y direcciones IP a los que los invitados pueden acceder antes de haberse autenticado. Es fundamental, y es uno de los orígenes más comunes de configuración incorrecta.
Como mínimo, su walled garden debe incluir el nombre de dominio completo de su portal de Purple, y las direcciones IP o rangos CIDR en los que se resuelve la infraestructura de Purple. Si utiliza el inicio de sesión social - Facebook, Google, Microsoft - también debe añadir los dominios de endpoint de OAuth para esos proveedores. Los endpoints de inicio de sesión de Google abarcan varios rangos de IP y varios dominios, incluidos accounts.google.com y oauth2.googleapis.com. La infraestructura de inicio de sesión de Facebook requiere del mismo modo varias entradas. La documentación de Purple proporciona una lista actualizada de las entradas exactas requeridas, y esta lista se mantiene al día a medida que esos proveedores actualizan su infraestructura.
Existe una particularidad crítica específica de UniFi que afecta a muchas implantaciones. El redireccionador HTTP del AP solo intercepta tráfico HTTP plano en el puerto 80. Los dispositivos modernos - iOS, Android, Windows, macOS - realizan la detección de Captive Portal basada en HTTPS. Los dispositivos Apple acceden a captive.apple.com a través de HTTPS. Los dispositivos Android acceden a connectivitycheck.gstatic.com. Si esas solicitudes HTTPS no obtienen una respuesta específica, el dispositivo puede decidir que no hay ningún Captive Portal y simplemente no mostrar la pantalla de inicio de sesión.
La solución es asegurarse de que su walled garden incluye los dominios de detección de Captive Portal para los principales sistemas operativos, y que su portal de Purple es accesible a través de HTTPS con un certificado SSL válido y de confianza. Los certificados autofirmados provocarán advertencias de seguridad en el navegador que impedirán la carga del portal. Esto es innegociable para las implementaciones en producción.
La otra consideración específica de UniFi es la accesibilidad del controlador. La UniFi Network Application, ya sea que se ejecute en un Cloud Gateway, un Cloud Key o un servidor autoalojado, debe ser accesible desde la infraestructura de Purple para que las llamadas de autorización de la API se realicen correctamente. Si su controlador está en una red privada detrás de NAT, deberá asegurarse de que los puertos de API correspondientes estén accesibles. Para controladores autoalojados, normalmente se trata del puerto 8443 para la API heredada, o del puerto HTTPS estándar 443 para la API más reciente introducida en la versión 9.1. La documentación de soporte de Purple especifica los rangos de IP exactos que necesitan acceso entrante a su controlador.
Para la autenticación basada en RADIUS - que es relevante cuando implementa Purple junto con SSIDs WPA2 o WPA3 en lugar del modelo de SSID para invitados abierto - el servidor RADIUS integrado de UniFi es compatible con los métodos estándar 802.1X EAP. Configure el perfil RADIUS en Ajustes, Redes, Servidores RADIUS y, a continuación, haga referencia a ese perfil en la configuración de su SSID. UniFi también es compatible con RADIUS sobre TLS, conocido como RADSEC, a partir de la versión 8.4, que cifra el tráfico RADIUS entre el AP y el servidor de autenticación. Para implementaciones multisitio donde el tráfico RADIUS atraviesa la internet pública, se recomienda encarecidamente RADSEC.
[RECOMENDACIONES DE IMPLEMENTACIÓN Y ERRORES COMUNES - aproximadamente 2 minutos]
Permítame ofrecerle la lista de verificación de implementación práctica que repasaría con cualquier cliente que implemente Purple en UniFi.
En primer lugar, la segmentación de red. Su SSID de invitados debe estar en una VLAN dedicada, aislada de sus redes corporativas y de IoT. UniFi lo hace de forma sencilla: cree una red dedicada en Ajustes, Redes, asígnele un ID de VLAN y asocie su SSID de invitados a esa red. Habilite el aislamiento de clientes en la red de invitados para evitar el tráfico de invitado a invitado.
En segundo lugar, el controlador debe tener un FQDN válido y un certificado SSL de confianza. No confíe en la dirección IP. Utilice un nombre de dominio adecuado, obtenga un certificado comercial o de Let's Encrypt para el mismo y configure UniFi para utilizar ese certificado. Esto resuelve la mayoría de los problemas de redirección HTTPS.
En tercer lugar, cree su walled garden con cuidado y pruébelo. Las entradas mínimas son: su dominio del portal de Purple y sus rangos de IP, los dominios de detección de Captive Portal para iOS, Android y Windows, y cualquier dominio de proveedor de OAuth que esté utilizando. Realice pruebas con un dispositivo que nunca antes se haya conectado a la red; la caché de DNS y el estado de la red pueden enmascarar lagunas en el walled garden durante las pruebas.
En cuarto lugar, para la integración de la API, utilice una cuenta de administrador local dedicada en la UniFi Network Application con los permisos mínimos requeridos. No utilice sus credenciales de administrador principal. Si utiliza Network Application 9.1 o posterior, use el nuevo mecanismo de clave de API en Panel de control, Integraciones; es más seguro y no requiere autenticación basada en credenciales.
Quinto, considere detenidamente la duración de la sesión. El vencimiento predeterminado de la sesión de invitado de UniFi puede ser de tan solo ocho horas. Para despliegues de hostelería donde los huéspedes pueden alojarse varias noches, configure las duraciones de sesión adecuadas en los ajustes del portal de Purple y asegúrese de que esas duraciones se pasen correctamente en la llamada de autorización de la API.
El error más común que veo es realizar el despliegue en un controlador autohospedado que no es accesible públicamente. Si Purple no puede comunicarse con su controlador para autorizar a los invitados, el portal se cargará pero la autenticación fallará silenciosamente. Verifique siempre la conectividad de la API desde la infraestructura de Purple antes de pasar a producción.
[PREGUNTAS Y RESPUESTAS RÁPIDAS - aproximadamente 1 minuto]
¿Funciona esto en UniFi Dream Machine Pro? Sí. Todas las consolas UniFi OS - UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max - admiten la configuración de External Portal Server. La aplicación de red se ejecuta en el dispositivo.
¿Puedo usar Purple en varios sitios de UniFi desde una sola cuenta de Purple? Sí. La arquitectura multisitio de Purple está diseñada exactamente para esto. Cada espacio se configura como un sitio independiente en Purple, asignado al sitio correspondiente de UniFi.
¿Necesito abrir puertos del firewall en la pasarela de UniFi? Debe asegurarse de que el tráfico de la VLAN de invitados pueda llegar al dominio del portal de Purple en el puerto 443. El puerto de la API del controlador también debe ser accesible desde los servidores de Purple. La documentación de Purple proporciona los rangos de IP específicos.
¿Qué pasa con WPA3? UniFi admite WPA3 Personal y WPA3 Enterprise. El mecanismo de Captive Portal funciona con WPA3 Personal en redes de invitados. WPA3 Enterprise utiliza 802.1X y RADIUS, lo cual es un flujo de autenticación diferente.
[RESUMEN Y PRÓXIMOS PASOS - aproximadamente 1 minuto]
En resumen: desplegar Purple como un Captive Portal externo en UniFi es una integración bien respaldada y arquitectónicamente sólida. Los pasos clave son: configure su SSID de invitado con la opción External Portal Server apuntando a la URL de su portal de Purple, cree un walled garden completo que cubra la infraestructura de Purple y cualquier proveedor de OAuth que esté utilizando, asegúrese de que su controlador UniFi tenga un certificado SSL válido y sea accesible desde los servidores de la API de Purple, y configure las duraciones de sesión adecuadas para su tipo de espacio.
El caso de negocio es sencillo. El portal integrado de UniFi le ofrece una página de bienvenida. Purple le ofrece una plataforma de experiencia de usuario invitado lista para el cumplimiento normativo y basada en análisis que se integra con su CRM, captura datos de primera mano bajo el consentimiento de la GDPR y proporciona los análisis de afluencia y tiempo de permanencia que los operadores de los espacios y los equipos de marketing realmente necesitan.
Si es un MSP o un integrador de sistemas que despliega UniFi a escala, la gestión multisitio y las capacidades de marca blanca de Purple lo convierten en la superposición adecuada para sus clientes.
Para obtener documentación detallada sobre la configuración, listas de IP de walled garden y guías de integración de la API, visite purple.ai. Gracias por su atención.
