Guía de configuración del captive portal de UniFi

Captive Portal para 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 presentador, y hoy vamos a analizar 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 en entornos de hostelería, retail y empresas a nivel mundial. Si es un responsable 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. Vamos a explicar exactamente cómo funciona el mecanismo del portal externo a nivel interno, cómo configurarlo correctamente, cuáles son los errores comunes y por qué superponer Purple a un despliegue de UniFi es la decisión arquitectónica correcta para los establecimientos que necesitan algo más que una página de bienvenida básica. Comencemos. [INMERSIÓN TÉCNICA - aproximadamente 5 minutos] En primer lugar, entendamos qué ocurre realmente cuando un dispositivo de un invitado se conecta a un SSID de UniFi que tiene un Captive Portal habilitado. Cuando el dispositivo de un invitado se asocia a su SSID de invitados, el punto de acceso de UniFi le asigna una dirección IP a través de DHCP de la forma habitual. Pero 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 cada consulta 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. Simultáneamente, 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 responde con una redirección 302, enviando al navegador a la página de bienvenida 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 fundamental. Con el portal de hotspot de UniFi integrado, la página de bienvenida se sirve directamente desde la aplicación UniFi Network. Es funcional, se configura rápidamente, pero está muy limitado. Ofrece 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. Cuando configura 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 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 conecta, presenta la página de inicio correspondiente, gestiona la autenticación y, a continuación, 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 una autenticación adecuada basada en claves. El extremo 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 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 a los que apunta la infraestructura de Purple. Si utiliza el inicio de sesión social - Facebook, Google, Microsoft - también debe añadir los dominios de extremo OAuth para esos proveedores. Los extremos 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 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 peculiaridad crítica específica de UniFi que afecta 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 una 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 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 las implementaciones de producción. La otra consideración específica de UniFi es la accesibilidad de la controladora. 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 controladora está en una red privada detrás de NAT, deberá asegurarse de que los puertos de la API correspondientes estén accesibles. Para controladoras autoalojadas, suele ser 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 controladora. 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 invitados abierto - el servidor RADIUS integrado de UniFi admite métodos EAP 802.1X estándar. 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 ofrecerle la lista de verificación de implementación práctica que revisarí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 facilita este proceso: 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 entre invitados. En segundo lugar, la controladora 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 Let's Encrypt o comercial para él y configure UniFi para usar ese certificado. Esto resuelve la mayoría de los problemas de redirección HTTPS. En tercer lugar, configure su walled garden (entorno cerrado) con cuidado y pruébelo. Las entradas mínimas son: el dominio de su 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 OAuth que esté utilizando. Realice la prueba con un dispositivo que nunca se haya conectado a la red antes; la DNS en caché y el estado de la red pueden enmascarar deficiencias 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 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 despliegues 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 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 suelo ver 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 la puesta en marcha. [PREGUNTAS Y RESPUESTAS RÁPIDAS - aproximadamente 1 minuto] ¿Funciona esto en UniFi Dream Machine Pro? Sí. Todas las consolas de UniFi OS - UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max - admiten la configuración de External Portal Server. La aplicación Network Application se ejecuta en el dispositivo. ¿Puedo usar Purple en varios 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 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, que 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: configurar su SSID de invitados con la opción External Portal Server apuntando a la URL de su 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 API de Purple, y configurar las duraciones de sesión adecuadas para su tipo de espacio. El argumento comercial es sencillo. El portal integrado de UniFi le ofrece una página de inicio de sesión. Purple le ofrece una plataforma de experiencia de invitado preparada para el cumplimiento normativo y orientada a la analítica que se integra con su CRM, captura datos de origen bajo el consentimiento del GDPR y proporciona la analítica de afluencia y tiempo de permanencia que los operadores de espacios y los equipos de marketing realmente necesitan. Si es un MSP o un integrador de sistemas que despliega UniFi a gran escala, la gestión multisitio de Purple y sus capacidades de marca blanca la convierten en la solución superpuesta 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.