Guía de configuración de Captive Portal de UniFi

Captive Portal para Ubiquiti UniFi - Una sesión informativa técnica de Purple [INTRODUCCIÓN Y CONTEXTO - aproximadamente 1 minuto] Le damos la bienvenida a la serie de sesiones informativas técnicas de Purple. Soy su anfitrión, y hoy profundizaremos en los detalles específicos de la implementación de un Captive Portal externo en la infraestructura de Ubiquiti UniFi, una de las plataformas de red más desplegadas a nivel mundial en los sectores de hotelería, retail y entornos corporativos. Si usted es gerente de TI, arquitecto de redes o integrador de sistemas que trabaja con UniFi Cloud Gateways, Dream Machines o la UniFi Network Application, este episodio es para usted. Analizaremos exactamente cómo funciona el mecanismo del portal externo bajo el cofre, cómo configurarlo correctamente, cuáles son los errores comunes y por qué superponer Purple sobre un despliegue de UniFi es la decisión de arquitectura adecuada para los establecimientos que necesitan más que una página de inicio de sesión básica. Comencemos. [ANÁLISIS TÉCNICO DETALLADO - aproximadamente 5 minutos] Primero, entendamos qué sucede realmente cuando un dispositivo de invitado se conecta a un SSID de UniFi que tiene un Captive Portal habilitado. Cuando un dispositivo de invitado se asocia a su SSID de invitado, el Access Point de UniFi le asigna una dirección IP a través de DHCP de manera 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 al navegador a la página de inicio de sesión del Captive Portal. Este es el mecanismo que activa la notificación "Iniciar sesión en WiFi" en los 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 UniFi Hotspot Portal integrado, la página de inicio de sesión se sirve directamente desde la UniFi Network Application. Es funcional y se configura rápidamente, pero está muy limitada. Se obtiene una 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 analíticas significativas más allá del recuento de sesiones. Cuando configura un Servidor de Portal Externo - que es el ajuste en el 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 es Purple. La URL que ingresa en el campo del Servidor de Portal Externo se convierte en el destino de todas esas redirecciones 302. Aquí está el detalle técnico importante sobre esa URL de redireccionamiento. Cuando UniFi redirecciona 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 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 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. Esta es la lista blanca de dominios y direcciones IP a los que los invitados pueden acceder antes de haberse autenticado. Es esencial, y es una de las fuentes más comunes de configuración incorrecta. 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 a los que apunta la infraestructura de Purple. Si utiliza el inicio de sesión social - 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 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 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 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 local, debe ser accesible desde la infraestructura de Purple para que las llamadas de autorización de la API tengan éxito. 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 locales, este es típicamente 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 es compatible con los métodos estándar 802.1X EAP. Debe configurar el perfil RADIUS en Settings, Networks, RADIUS Servers, y luego 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, el cual cifra el tráfico RADIUS entre el AP y el servidor de autenticación. Para implementaciones en múltiples sitios 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 práctica para la implementación que revisaría con cualquier cliente que vaya a implementar Purple en UniFi. Primero, la segmentación de red. Su SSID de invitado debe estar en una VLAN dedicada, aislada de sus redes corporativas y de IoT. UniFi facilita este proceso: cree una red dedicada en Settings, Networks, asígnele un VLAN ID y asocie su SSID de invitado a esa red. Habilite la opción de aislamiento de clientes (client isolation) en la red de invitados para evitar el tráfico entre dispositivos de invitados. Segundo, 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 uno comercial para este, y configure UniFi para usar ese certificado. Esto resuelve la mayoría de los problemas de redireccionamiento HTTPS. Tercero, configure su walled garden con cuidado y pruébelo. Las entradas mínimas son: el dominio de su Captive 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 ocultar fallas en el walled garden durante las pruebas. Cuarto, 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 está utilizando Network Application 9.1 o posterior, emplee 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 vencimiento 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 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 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. 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 multisitio 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 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, 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 respaldada desde el punto de vista de la arquitectura. Los pasos clave son: configure su SSID de invitado con la opción de 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 UniFi tenga un certificado SSL válido y sea accesible desde los servidores API de Purple, y configure las duraciones de sesión adecuadas para su tipo de establecimiento. El caso de negocio es sencillo. El portal UniFi integrado le ofrece una página de bienvenida. Purple le ofrece una plataforma de experiencia de invitado impulsada por análisis y lista para el cumplimiento normativo que se integra con su CRM, captura datos de primera mano bajo el consentimiento de GDPR y proporciona los análisis de afluencia y tiempo de permanencia que los operadores de establecimientos 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 lo convierten en la plataforma complementaria 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 API, visite purple.ai. Gracias por escuchar.