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 bienvenida (splash page) adecuada, gestiona la autenticación y luego 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 (handshake) crucial. A partir de UniFi Network Application 9.1 y posterior, existe una REST API 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 pendiente a autorizado. Se concede el acceso a Internet.
Ahora hablemos del Walled Garden, que UniFi denomina acceso previo a la autorización (Pre-Authorization Access). Esta es la lista blanca de dominios y direcciones IP a las que los invitados pueden acceder antes de autenticarse. Es esencial y es una de las fuentes más comunes de errores de configuración.
Como mínimo, su walled garden debe incluir el nombre de dominio completamente calificado de su portal Purple y las direcciones IP o rangos CIDR en los que se resuelve la infraestructura de Purple. Si utiliza el inicio de sesión con redes sociales - Facebook, Google, Microsoft -, también debe agregar los dominios de endpoint OAuth para esos proveedores. Los endpoints de inicio de sesión de Google abarcan múltiples rangos de IP y varios dominios, incluidos accounts.google.com y oauth2.googleapis.com. La infraestructura de inicio de sesión de Facebook requiere de manera similar 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 peculiaridad crítica específica de UniFi que afecta a muchas implementaciones. El redireccionador HTTP en el AP solo intercepta el tráfico HTTP sin cifrar 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 reciben 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 incluya los dominios de detección de Captive Portal para los principales sistemas operativos, y que su portal Purple sea accesible a través de HTTPS con un certificado SSL válido y de confianza. Los certificados autofirmados provocarán advertencias de seguridad del navegador que impedirán que el portal se cargue. Esto no es negociable para implementaciones de 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 los controladores autoalojados, normalmente es el puerto 8443 para la API heredada, o el 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-Enterprise o WPA3-Enterprise en lugar del modelo de SSID para invitados abierto - el servidor RADIUS integrado de UniFi admite métodos estándar 802.1X EAP. Se configura el perfil RADIUS en Settings, Networks, RADIUS Servers, y luego se hace referencia a ese perfil en la configuración de su SSID. UniFi también admite RADIUS sobre TLS, conocido como RADSEC, a partir de la versión 8.4 en adelante, lo que cifra el tráfico RADIUS entre el AP y el servidor de autenticación. Para implementaciones multisitio donde el tráfico RADIUS atraviesa el internet público, se recomienda encarecidamente RADSEC.
[RECOMENDACIONES DE IMPLEMENTACIÓN Y ERRORES COMUNES — aproximadamente 2 minutos]
Permítame compartir la lista de verificación de implementación práctica que revisaría con cualquier cliente que implemente Purple en UniFi.
Primero, la segmentación de red. Su SSID de invitados debe estar en una VLAN dedicada, aislada de sus redes corporativas y de IoT. UniFi hace que esto sea sencillo: cree una red dedicada en Settings, Networks, asígnele un VLAN ID y asocie su SSID de invitados con esa red. Habilite el aislamiento de clientes en la red de invitados para evitar el tráfico de invitado a invitado.
Segundo, el controlador debe tener un FQDN válido y un certificado SSL de confianza. No dependa de la dirección IP. Use un nombre de dominio adecuado, obtenga un certificado Let's Encrypt o comercial para el mismo y configure UniFi para usar ese certificado. Esto resuelve la mayoría de los problemas de redirección HTTPS.
Tercero, 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; el DNS en caché y el estado de la red pueden ocultar fallas en el walled garden durante las pruebas.
Cuarto, para la integración de la API, use 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 la Network Application 9.1 o posterior, use el nuevo mecanismo de clave API en Control Plane, Integrations; es más seguro y no requiere autenticación basada en credenciales.
En quinto lugar, considere detenidamente la duración de la sesión. El tiempo de expiración predeterminado de la sesión de invitado de UniFi puede ser de tan solo ocho horas. Para implementaciones de hotelería donde los huéspedes pueden quedarse 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 la implementación en un controlador autohospedado que no es de acceso público. Si Purple no puede comunicarse con su controlador para autorizar a los invitados, el portal se cargará pero la autenticación fallará silenciosamente. Siempre verifique la conectividad de la API desde la infraestructura de Purple antes de lanzar el servicio.
[Preguntas y respuestas rápidas - aproximadamente 1 minuto]
¿Esto funciona en UniFi Dream Machine Pro? Sí. Todas las consolas UniFi OS - UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max - son compatibles con la configuración de External Portal Server. La Network Application 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 sucursal se configura como un sitio independiente en Purple, asignado al sitio de UniFi correspondiente.
¿Necesito abrir puertos de firewall en el gateway 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 es compatible con 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: implementar Purple como un Captive Portal externo en UniFi es una integración de arquitectura sólida y con un excelente soporte. Los pasos clave son: configurar su SSID de invitado con la opción External Portal Server apuntando a la URL de su portal de Purple, crear un walled garden integral que cubra la infraestructura de Purple y cualquier proveedor de OAuth que esté utilizando, asegurarse de que su controlador UniFi tenga un certificado SSL válido y sea accesible desde los servidores de la API de Purple, y configurar las duraciones de sesión adecuadas para su tipo de sucursal.
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 invitados basada en análisis y lista para cumplir con las normativas que se integra con su CRM, captura datos de primera fuente bajo el consentimiento de GDPR y proporciona los análisis de afluencia y tiempo de permanencia que los operadores de sucursales y los equipos de marketing realmente necesitan.
Si usted es un MSP o un integrador de sistemas que implementa UniFi a escala, la gestión multisitio de Purple y sus capacidades de marca blanca la convierten en la solución superpuesta ideal para sus clientes.
Para obtener documentación de configuración detallada, listas de IP de walled garden y guías de integración de la API, visite purple.ai. Gracias por escuchar.
