Ver transcripción del podcast
Captive Portal para Ubiquiti UniFi — Una sesión técnica de Purple
[INTRODUCCIÓN Y CONTEXTO — aproximadamente 1 minuto]
Le damos la bienvenida a la serie de sesiones técnicas de Purple. Soy su anfitrión, y hoy analizaremos los detalles de la implementación de un Captive Portal externo en la infraestructura de Ubiquiti UniFi, una de las plataformas de red más implementadas a nivel mundial en entornos de hospitalidad, retail y corporativos.
Si usted es un gerente de TI, arquitecto de redes o integrador de sistemas que trabaja con UniFi Cloud Gateways, Dream Machines o la aplicación UniFi Network, este episodio es para usted. Analizaremos exactamente cómo funciona el mecanismo del portal externo a nivel técnico, cómo configurarlo correctamente, cuáles son los errores comunes y por qué superponer Purple sobre una implementación de UniFi es la decisión arquitectónica correcta para los establecimientos que necesitan más que una página de inicio básica.
Comencemos.
[ANÁLISIS TÉCNICO DETALLADO — aproximadamente 5 minutos]
Primero, comprendamos qué sucede realmente cuando el dispositivo de un usuario invitado se conecta a un SSID de UniFi que tiene habilitado un Captive Portal.
Cuando un dispositivo invitado se asocia con su SSID de invitado, el punto de acceso de UniFi le asigna una dirección IP a través de DHCP de forma normal. Pero el dispositivo se coloca de inmediato en lo que UniFi denomina un estado "pendiente". En este estado, el proceso DNSmasq integrado del AP intercepta cada consulta DNS que realiza el dispositivo, independientemente del servidor DNS que el dispositivo crea que está utilizando. El AP redirige todo el tráfico DNS hacia sí mismo.
Simultáneamente, el AP 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 el 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 dispositivos iOS y Android.
Ahora, aquí es donde la distinción entre el portal integrado y el portal externo se vuelve crítica. Con el Hotspot Portal integrado de UniFi, la aplicación UniFi Network sirve directamente la página de inicio. Es funcional y rápido de configurar, pero es sumamente limitado. Obtiene 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 de datos significativos más allá del recuento de sesiones.
Cuando configura un servidor de portal externo (que es la configuración en la que nos enfocamos hoy), le está indicando al controlador de UniFi que redirija a los invitados a una aplicación web completamente independiente. En nuestro caso, esa aplicación es Purple. La URL que ingresa 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 usuario 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 a la que el cliente intentaba acceder y el nombre del SSID. Su portal externo - Purple en este contexto - captura esos parámetros, los utiliza para identificar el dispositivo que se está conectando, presenta la splash page adecuada, gestiona la autenticación y luego realiza una llamada de API de vuelta a la UniFi Network Application para autorizar esa dirección MAC.
Esa llamada de API es el saludo de conexión crucial. A partir de la versión 9.1 de UniFi Network Application y 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 usuario invitado pasa de estar pendiente a autorizado. Se concede el acceso a Internet.
Ahora hablemos del Walled Garden, al que UniFi llama Pre-Authorization Access. Esta es la lista de dominios y direcciones IP permitidos a los que los usuarios 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 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 con redes sociales (Facebook, Google, Microsoft), también debe agregar los dominios de los endpoints 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.
Hay 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 del 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 determinar que no hay un 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 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 la API correspondientes estén accesibles. Para controladores autoalojados, esto es normalmente 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 de invitado abierto - el servidor RADIUS integrado de UniFi admite métodos estándar 802.1X EAP. Configure el perfil RADIUS en Settings, Networks, RADIUS Servers y luego haga 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, 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 compartirle 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 la red. Su SSID de invitado debe estar en una VLAN dedicada, aislada de sus redes corporativas y de IoT. UniFi facilita esto: cree una red dedicada en Settings, Networks, asígnele un VLAN ID y asocie su SSID de invitado 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 de Let's Encrypt o uno comercial para este, y configure UniFi para que use ese certificado. Esto resuelve la mayoría de los problemas de redirección HTTPS.
Tercero, configure su walled garden cuidadosamente y pruébelo. Las entradas mínimas son: su dominio del portal de Purple y sus rangos de IP, los dominios de detección del Captive Portal para iOS, Android y Windows, y cualquier dominio de proveedor de OAuth que esté utilizando. Realice pruebas con un dispositivo que nunca 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 versión 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 cuidadosamente la duración de la sesión. El vencimiento predeterminado de la sesión de invitados de UniFi puede ser tan corto como de ocho horas. Para implementaciones de hotelería donde los huéspedes pueden hospedarse 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 implementar 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. Siempre verifique la conectividad de la API desde la infraestructura de Purple antes de entrar en producción.
[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 múltiples sitios de UniFi desde una sola cuenta de Purple? Sí. La arquitectura de múltiples sitios de Purple está diseñada exactamente para esto. Cada lugar se configura como un sitio independiente en Purple, mapeado al sitio de UniFi correspondiente.
¿Necesito abrir puertos de firewall 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 en el puerto 443. El puerto de la API del controlador también debe estar 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, que 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 sólida y bien soportada a nivel de arquitectura. Los pasos clave son: configure su SSID de invitados con la opción External Portal Server apuntando a la URL de su portal de Purple, cree un walled garden integral que cubra la infraestructura de Purple y cualquier proveedor de OAuth que esté utilizando, asegúrese de que su controlador de 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 establecimiento.
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 analítica y lista para el cumplimiento normativo que se integra con su CRM, captura datos de primera fuente bajo el consentimiento de GDPR, y proporciona la analítica de visitas y tiempo de permanencia que los operadores de establecimientos y los equipos de marketing realmente necesitan.
Si es un MSP o un integrador de sistemas que implementa UniFi a escala, la gestión de múltiples sitios de Purple y sus capacidades de marca blanca lo convierten en el complemento ideal 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 API, visite purple.ai. Gracias por escuchar.
