Ver transcripción del podcast
Captive Portal for Ubiquiti UniFi - Un informe técnico de Purple
[INTRODUCCIÓN Y CONTEXTO - aproximadamente 1 minuto]
Le damos la bienvenida a la serie de informes técnicos de Purple. Soy su anfitrión y hoy vamos a analizar los detalles de la implementación de un Captive Portal externo en la infraestructura Ubiquiti UniFi, una de las plataformas de red más utilizadas en entornos de hostelería, comercio minorista y empresas a nivel mundial.
Si es usted administrador de TI, arquitecto de red o integrador de sistemas y trabaja con UniFi Cloud Gateways, Dream Machines o la UniFi Network Application, este episodio es para usted. Vamos a explicar exactamente cómo funciona el mecanismo del portal externo bajo el capó, cómo configurarlo correctamente, cuáles son los errores más comunes y por qué superponer Purple a una implementación de UniFi es la decisión de arquitectura adecuada para aquellos establecimientos que necesitan algo más que una página de inicio básica.
Comencemos.
[ANÁLISIS TÉCNICO DETALLADO - aproximadamente 5 minutos]
En primer lugar, entendamos qué ocurre realmente cuando el dispositivo de un invitado se conecta a un SSID de UniFi que tiene habilitado un Captive Portal.
Cuando el dispositivo de un invitado se asocia a su SSID de invitado, el punto de acceso de UniFi le asigna una dirección IP a través de DHCP de forma normal. Sin embargo, el dispositivo se coloca inmediatamente en lo que UniFi denomina un estado "pendiente". En este estado, el proceso DNSmasq integrado en el punto de acceso intercepta todas las consultas DNS que realiza el dispositivo, independientemente del servidor DNS que el dispositivo crea que está utilizando. El punto de acceso redirige todo el tráfico DNS hacia sí mismo.
Al mismo tiempo, el punto de acceso ejecuta un redireccionador HTTP ligero en el puerto 80. En el momento en que el navegador del invitado realiza cualquier solicitud HTTP (y esta es la palabra clave, HTTP, no HTTPS), el redireccionador devuelve una redirección 302, enviando al navegador a la página de inicio del Captive Portal. Este es el mecanismo que activa la notificación "Iniciar sesión en WiFi" en los dispositivos iOS y Android.
Ahora bien, aquí es donde la distinción entre el portal integrado y el portal externo se vuelve fundamental. Con el portal de hotspot integrado de UniFi, la página de inicio es servida directamente por la UniFi Network Application. Es funcional y rápido de configurar, pero está muy limitado. Dispone de autenticación básica por contraseña, cupones y pagos con Stripe. No hay captura de correo electrónico, ni inicio de sesión social, ni gestión de consentimiento de GDPR, ni integración con CRM, ni análisis significativos más allá del recuento de sesiones.
Al configurar un servidor de portal externo (que es el ajuste en el que nos centramos hoy), le está indicando al controlador de UniFi que redirija a los invitados a una aplicación web completamente independiente. En nuestro caso, se trata de Purple. La URL que introduzca en el campo Servidor de portal externo se convierte en el destino de todas esas redirecciones 302.
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 a la API de vuelta a la UniFi Network Application para autorizar esa dirección MAC.
Esa llamada a la 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 basada en claves adecuada. 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.
Ahora hablemos del Walled Garden, que UniFi denomina Pre-Authorization Access. Se trata de la lista blanca de dominios y direcciones IP a los que los invitados pueden acceder antes de autenticarse. Es esencial, y es uno de los orígenes de errores de configuración más comunes.
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 los endpoints de OAuth de 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 un comportamiento crítico específico de UniFi que suele afectar a muchas implementaciones. El redireccionador HTTP del AP solo intercepta el tráfico HTTP sin cifrar en el puerto 80. Los dispositivos modernos — iOS, Android, Windows, macOS — realizan la detección del Captive Portal mediante 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 determinar 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 de 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 en el navegador que impedirán que se cargue el 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 autohospedado — debe ser accesible desde la infraestructura de Purple para que las llamadas de autorización de la API se realicen correctamente. Si su controlador se encuentra en una red privada detrás de NAT, deberá asegurarse de que los puertos de la API correspondientes sean accesibles. Para controladores autohospedados, 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 requieren acceso entrante a su controlador.
Para la autenticación basada en RADIUS - que es relevante cuando se 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. Debe configurar el perfil RADIUS en Ajustes, Redes, Servidores RADIUS y, a continuación, hacer 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, 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 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 práctica para la implementación que revisaría con cualquier cliente que vaya a desplegar 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 facilita este proceso: 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 dependa de la dirección IP. Utilice un nombre de dominio adecuado, obtenga un certificado Let's Encrypt o comercial para el mismo y configure UniFi para que utilice ese certificado. Esto resuelve la mayoría de los problemas de redireccionamiento HTTPS.
En tercer lugar, cree su walled garden con cuidado y pruébelo. Las entradas mínimas son: el 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 las pruebas con un dispositivo que nunca se haya conectado a la red; el estado de la red y la caché de DNS pueden ocultar fallos 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 principales. Si utiliza la Network Application 9.1 o posterior, use el nuevo mecanismo de clave de API en Plano de control, Integraciones: 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 en el sector de la hostelería, donde los huéspedes pueden alojarse varias noches, configure las duraciones de sesión adecuadas en los ajustes de configuración del portal de Purple y asegúrese de que dichas duraciones se transmitan 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 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 la puesta en marcha.
[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 Network Application se ejecuta en el propio dispositivo.
¿Puedo utilizar Purple en múltiples sitios de UniFi desde una única 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 de UniFi correspondiente.
¿Necesito abrir puertos de cortafuegos en la puerta de enlace de UniFi? Debe asegurarse de que el tráfico de la VLAN de invitados pueda llegar al dominio del portal de Purple a través del 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é ocurre 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 que representa 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 sólida y con un excelente soporte técnico a nivel de arquitectura. Los pasos clave son: configurar su SSID de invitado con la opción External Portal Server apuntando a la URL del portal de Purple, crear un walled garden exhaustivo 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 el tipo de espacio.
El caso de negocio es sencillo. El portal integrado de UniFi le ofrece una página de bienvenida básica. Purple le proporciona una plataforma de experiencia de invitado basada en analíticas y preparada para cumplir con las normativas vigentes que se integra con su CRM, captura datos de origen bajo el consentimiento del GDPR y ofrece las analíticas 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 implementa UniFi a gran escala, la gestión multisitio de Purple y sus capacidades de marca blanca la convierten en la solución de superposición perfecta 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. Muchas gracias por su atención.
