Saltar al contenido principal
Español

Captive Portal para Ubiquiti UniFi

Esta guía técnica autorizada detalla la configuración de un Captive Portal externo (Purple) en la aplicación de red Ubiquiti UniFi. Cubre el funcionamiento interno de la red, la implementación paso a paso de la red de invitados, la lista blanca del walled garden, la autenticación RADIUS y las estrategias de resolución de problemas para profesionales de TI sénior y administradores de red.

📖 10 min de lectura📝 2,475 palabras🔧 2 ejemplos prácticos❓ 3 preguntas de práctica📚 8 definiciones clave

Escuchar esta guía

Ver transcripción del podcast
Captive Portal for Ubiquiti UniFi — Un informe técnico de Purple [INTRODUCCIÓN Y CONTEXTO — aproximadamente 1 minuto] Bienvenido a la serie de informes técnicos de Purple. Soy su presentador, y hoy nos adentraremos en los aspectos 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 utilizadas en los sectores de hostelería, comercio minorista y entornos empresariales a nivel mundial. Si es usted administrador de TI, arquitecto de red o integrador de sistemas que trabaja con UniFi Cloud Gateways, Dream Machines o la aplicación de red UniFi Network Application, este episodio es para usted. Vamos a repasar exactamente cómo funciona internamente el mecanismo del portal externo, 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 algo más que una página de bienvenida básica. Comencemos. [ANÁLISIS TÉCNICO DETALLADO — aproximadamente 5 minutos] En primer lugar, entendamos qué ocurre realmente cuando un dispositivo de invitado se conecta a un SSID de UniFi que tiene habilitado un Captive Portal. Cuando un dispositivo de 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. Pero el dispositivo se coloca inmediatamente en lo que UniFi denomina un estado "pendiente". En este estado, el proceso DNSmasq integrado en el 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 bienvenida del Captive Portal. Este es el mecanismo que activa la notificación "Iniciar sesión en la red Wi-Fi" 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 portal UniFi Hotspot Portal integrado, la página de bienvenida la sirve directamente la aplicación UniFi Network Application. Es funcional y rápido de configurar, pero está muy limitado. Se obtiene una autenticación básica por contraseña, vales 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. Al configurar un servidor de portal externo (External Portal Server) —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 External Portal Server 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 (splash page) adecuada, gestiona la autenticación y, a continuación, realiza una llamada a la API de vuelta a la aplicación UniFi Network para autorizar esa dirección MAC. Esa llamada a la API es el saludo de conexión (handshake) 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 acceso a Internet. Ahora hablemos del Walled Garden (entorno cerrado), que UniFi denomina Acceso Previo a la Autorización. Esta es la lista blanca de dominios y direcciones IP a los 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 completo (FQDN) 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 social — Facebook, Google, Microsoft —, también debe añadir los dominios de endpoint de OAuth para 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 ofrece una lista actualizada de las entradas exactas requeridas, y esta lista se mantiene al día a medida que dichos proveedores actualizan su infraestructura. Existe una peculiaridad crítica específica de UniFi que suele afectar a muchas implementaciones. El redireccionador HTTP del AP solo intercepta el tráfico HTTP simple 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, sencillamente, 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 en el navegador que bloquearán la carga del portal. Esto no es negociable para implementaciones de producción. La otra consideración específica de UniFi es la accesibilidad del controlador. La aplicación UniFi Network (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 tengan éxito. Si su controlador se encuentra en una red privada detrás de NAT, deberá asegurarse de que los puertos de la API correspondientes estén accesibles. Para controladores autoalojados, 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-Enterprise o WPA3-Enterprise en lugar del modelo de SSID para invitados abierto), el servidor RADIUS integrado de UniFi admite métodos estándar EAP 802.1X. El perfil RADIUS se configura en Settings, Networks, RADIUS Servers y, a continuación, se hace referencia a dicho 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, lo que cifra el tráfico RADIUS entre el AP y el servidor de autenticación. Para implementaciones multisitio en las que 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 repasarí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 ID de VLAN y asocie su SSID de invitados a esa red. Habilite la opción de aislamiento de clientes (client isolation) en la red de invitados para evitar el tráfico entre ellos. En segundo lugar, el controlador 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 de Let's Encrypt o comercial para el mismo y configure UniFi para utilizar ese certificado. Esto resuelve la mayoría de los problemas de redirección HTTPS. En tercer lugar, configure su walled garden (jardín vallado) 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 de OAuth que esté utilizando. Realice las pruebas con un dispositivo que nunca se haya conectado a la red anteriormente; la caché de DNS y el estado de la red pueden enmascarar 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 aplicación UniFi Network con los permisos mínimos necesarios. No utilice sus credenciales de administrador principal. Si utiliza la versión de Network Application 9.1 o posterior, emplee 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 vencimiento predeterminado de la sesión de invitado de UniFi puede ser de tan solo ocho horas. En despliegues para el sector hotelero, 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 dichas 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 de alojamiento propio 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) son compatibles con la configuración de servidor de portal externo. La aplicación Network se ejecuta en el propio dispositivo. ¿Puedo utilizar 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, mapeado con el sitio correspondiente de UniFi. ¿Necesito abrir puertos del cortafuegos en la pasarela de UniFi? Debe asegurarse de que el tráfico de la VLAN de invitados pueda llegar al dominio del Captive 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, que es un flujo de autenticación diferente. [RESUMEN Y PASOS SIGUIENTES — aproximadamente 1 minuto] En resumen: desplegar Purple como un Captive Portal externo en UniFi es una integración consolidada y con una arquitectura sólida. Los pasos clave son: configurar su SSID de invitados con la opción de servidor de portal externo 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 de 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 espacio. El argumento comercial es sencillo. El portal integrado de UniFi le ofrece una página de bienvenida. Purple le ofrece una plataforma de experiencia de invitado basada en análisis y preparada para el cumplimiento normativo que se integra con su CRM, captura datos de origen bajo el consentimiento de la GDPR y proporciona los análisis 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 y las capacidades de marca blanca de Purple la convierten en la solución superpuesta 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. Gracias por su atención.

📚 Part of our core series: Multi-Tenant WiFi →

header_image.png

Resumen ejecutivo

A medida que los entornos físicos empresariales (que abarcan desde cadenas de retail a gran escala [1] y grupos de hostelería multisitio [2] hasta importantes centros de transporte [3] e instituciones educativas [4]) buscan maximizar el valor de su infraestructura inalámbrica, las limitaciones de los controladores de hotspot integrados se convierten en un cuello de botella operativo significativo. El ecosistema Ubiquiti UniFi proporciona hardware altamente fiable, rentable y escalable. Sin embargo, su portal de invitados nativo carece de la captura de datos avanzada, la analítica multisitio, la integración con CRM, el cumplimiento de la privacidad global (GDPR, CCPA, PCI DSS) y las capacidades de monetización que requieren las operaciones empresariales modernas.

Esta guía de referencia técnica proporciona un recorrido arquitectónico completo para superponer la Enterprise WiFi Intelligence Platform de Purple [5] sobre una arquitectura de red Ubiquiti UniFi. Al utilizar la capacidad de External Portal Server de UniFi, los arquitectos de red y los integradores de sistemas pueden eludir las limitaciones del controlador local. Esta integración enruta la autenticación de invitados a través del motor de identidad y analítica seguro y alojado en la nube de Purple, transformando un servicio básico en un activo operativo y de marketing de nivel empresarial.

Inmersión técnica detallada

Para implementar un Captive Portal externo seguro y estable, los ingenieros de red deben comprender la comunicación de bajo nivel y las transiciones de estado que se producen cuando un cliente no autenticado se conecta a la red inalámbrica.

El ciclo de vida de la conexión y redirección de invitados

El flujo de trabajo del Captive Portal de UniFi funciona bajo un modelo estricto basado en estados. Cuando un cliente se asocia a un SSID con la función de invitados habilitada, se inicia el siguiente proceso secuencial:

Fase Componente Acción / Transición de estado Mecanismo técnico
1. Asociación Cliente y punto de acceso El cliente se asocia con el SSID; el servidor DHCP asigna la dirección IP, la máscara de subred, la puerta de enlace y los servidores DNS. Asociación estándar 802.11 y concesión DHCP.
2. Cuarentena Punto de acceso (AP) UniFi El AP coloca la dirección MAC del cliente en un estado de Cuarentena / Pendiente (authorized: false). Reglas de bloqueo de Capa 2/3 aplicadas localmente en la interfaz virtual del AP.
3. Intercepción de DNS Demonio local del AP El AP ejecuta un proceso DNSmasq local que intercepta todas las consultas DNS de los clientes pendientes. El AP redirige todo el tráfico del puerto 53 (UDP/TCP) a su resolución DNS local, independientemente de la configuración de DNS del cliente.
4. Intercepción HTTP Redireccionador del AP El AP ejecuta un demonio redireccionador HTTP ligero en el puerto 80. Se intercepta cualquier solicitud HTTP realizada por el cliente. El AP responde con una redirección HTTP 302 Found.
5. Redirección Navegador del cliente El navegador del cliente (o el asistente de Captive Portal del SO) es redirigido a la URL del portal externo configurada. Se añaden parámetros de consulta críticos a la URL de redirección 302 que contienen metadatos del cliente y del AP.
6. Autenticación Portal externo (Purple) El cliente interactúa con la página de bienvenida de Purple, completando la autenticación (p. ej., inicio de sesión con redes sociales, registro por correo electrónico, OTP por SMS). Sesión HTTPS segura alojada en la infraestructura en la nube de Purple.
7. Intercambio de API Nube de Purple y UniFi Controller Purple valida las credenciales y emite una llamada API segura a la aplicación de red UniFi. Llamada REST API (solicitud POST) que contiene la dirección MAC del cliente, el ID del sitio y los parámetros de la sesión.
8. Autorización UniFi Controller y AP El UniFi Controller actualiza el estado del cliente a authorized: true y envía la ACL actualizada al AP. El AP elimina los bloqueos de Capa 2/3 para la dirección MAC del cliente, otorgando un enrutamiento completo a la pasarela de internet.

Parámetros de consulta de redirección

Cuando el AP UniFi emite la redirección HTTP 302, añade un conjunto estandarizado de parámetros de consulta a la URL del portal externo. El portal externo debe capturar estos parámetros para identificar al cliente y realizar la posterior autorización de la API:

https://portal.purplehotspot.com/guest/s/default/?ap=94:2a:6f:d0:30:57&id=1c:71:25:63:e4:24&t=1742398732&url=http://connectivitycheck.gstatic.com%2F&ssid=purple-guest
  • ap: La dirección MAC del punto de acceso UniFi específico con el que está asociado el cliente.
  • id: La dirección MAC del dispositivo cliente que solicita acceso a la red.
  • t: Una marca de tiempo epoch Unix que representa el momento de inicio de la redirección, utilizada para la verificación de seguridad.
  • url: La URL original a la que el cliente intentó acceder (a menudo un endpoint de detección del portal cautivo del SO).
  • ssid: El nombre del SSID al que se conectó el cliente, lo que permite al portal presentar una imagen de marca específica del sitio.

architecture_overview.png

El Walled Garden (control de acceso antes de la autorización)

Antes de que se autorice a un cliente, se bloquea todo el tráfico, excepto para los destinos definidos explícitamente en la lista de Acceso antes de la autorización (comúnmente denominada Walled Garden). Dado que los dispositivos de los clientes modernos ejecutan asistentes de Captive Portal automáticos que prueban la conectividad a través de HTTPS, y dado que la autenticación externa a menudo depende de proveedores de identidad externos (IdP), configurar un Walled Garden robusto y preciso es fundamental.

Si se omite un dominio o un rango de IP necesario en el Walled Garden, la página de bienvenida no se cargará, los botones de inicio de sesión de redes sociales se bloquearán o el dispositivo del cliente perderá la conexión WiFi por completo, asumiendo que la red no funciona.

Guía de implementación

Esta sección describe la configuración paso a paso requerida para integrar el Captive Portal externo de Purple con la aplicación Ubiquiti UniFi Network (Controller).

Paso 1: Segmentación de red y configuración de VLAN

Para garantizar la seguridad y el cumplimiento de nivel empresarial (como PCI DSS y GDPR), el tráfico de invitados debe estar completamente aislado de los recursos corporativos, los sistemas POS y las redes IoT.

  1. Vaya a Settings > Networks en la aplicación UniFi Network.
  2. Haga clic en Create New Network.
  3. Configure los ajustes de red de la siguiente manera:
    • Name: Purple Guest Network
    • VLAN ID: 90 (o cualquier etiqueta de VLAN dedicada para invitados)
    • Network Type: Guest (esto aplica automáticamente el aislamiento de clientes, evitando la comunicación entre invitados).
    • Gateway IP/Subnet: Configure una subred adecuada (por ejemplo, 10.90.0.1/22 para admitir hasta 1022 concesiones de invitados simultáneas).
    • DHCP Range: Habilite DHCP y defina el rango (por ejemplo, 10.90.0.10 a 10.90.3.254).
    • DNS Server: Establézcalo en resolutores públicos fiables (por ejemplo, Cloudflare 1.1.1.1 y Google 8.8.8.8) para garantizar una resolución DNS rápida.

Paso 2: Configuración del SSID para invitados

  1. Vaya a Settings > WiFi y haga clic en Create New WiFi Network.
  2. Configure los parámetros del SSID:
    • Name (SSID): Purple Guest WiFi
    • Security Protocol: Open (el Captive Portal se encargará de la autenticación).
    • Network: Seleccione la Purple Guest Network (VLAN 90) creada en el Paso 1.
    • Client Device Isolation: Asegúrese de que esté activado (ON).
  3. Desplácese hacia abajo hasta Hotspot Portal y marque la casilla para Enable Captive Portal.

Paso 3: Configuración del servidor del portal externo

Una vez habilitado el Hotspot Portal, debe redirigir la autenticación a los servidores en la nube seguros de Purple.

  1. Vaya a Settings > Profiles > Guest Hotspot (o Settings > Guest Control en versiones anteriores del controlador).
  2. En Authentication, seleccione External Portal Server.
  3. Configure los siguientes campos:
    • IP / FQDN: Introduzca el FQDN proporcionado por Purple (por ejemplo, portal.purplehotspot.com).
    • Use Secure Portal (HTTPS): Actívelo (ON) (obligatorio para la seguridad y la compatibilidad con navegadores modernos).
    • Redirect Using Hostname: Actívelo (ON) e introduzca el FQDN portal.purplehotspot.com.
    • Port: 443 (HTTPS estándar).
    • HTTPS Redirection: Actívelo (ON) (esto permite que el AP intercepte las solicitudes HTTPS iniciales y las redirija, aunque requiere una gestión de DNS cuidadosa).

Paso 4: Configuración del acceso de preautorización (Walled Garden)

Para permitir que los invitados no autenticados carguen la página de bienvenida de Purple y se autentiquen a través de IdP de terceros, añada los siguientes dominios y rangos de IP a la lista de Pre-Authorization Access en Settings > Profiles > Guest Hotspot > Pre-Authorization Access:

[
  "portal.purplehotspot.com",
  "*.purple.ai",
  "*.purplehotspot.com",
  "accounts.google.com",
  "ssl.gstatic.com",
  "*.googleapis.com",
  "*.facebook.com",
  "*.facebook.net",
  "*.fbcdn.net",
  "*.apple.com",
  "captive.apple.com",
  "connectivitycheck.gstatic.com",
  "*.microsoft.com",
  "*.live.com"
]

Nota: Para despliegues que utilicen el procesamiento de pagos de Stripe, añada *.stripe.com y *.stripe.network a la lista de preautorización.

Paso 5: Establecer el intercambio (Handshake) de la API

Para que Purple autorice a los invitados, sus servidores en la nube deben comunicarse con su UniFi Network Application.

Para UniFi Network Application 9.1 y versiones posteriores (REST API recomendada)

  1. En el controlador UniFi, vaya a Settings > Control Plane > Integrations.
  2. En la sección API Keys, haga clic en Generate New API Key.
  3. Asigne un nombre (por ejemplo, Purple Integration Key) y establezca los permisos en Administrator.
  4. Copie la API Key generada.
  5. Inicie sesión en su Purple Portal, vaya a Venue Settings > Integration > Ubiquiti UniFi y pegue la API Key junto con el FQDN público de su controlador UniFi (por ejemplo, unifi.yourdomain.com:443).

Para controladores heredados (API basada en credenciales)

  1. Vaya a Settings > System > Admins.
  2. Cree una cuenta de administrador local dedicada (por ejemplo, purple_api).
  3. Asigne privilegios de Administrator o Hotspot Operator.
  4. Configure una contraseña segura y única.
  5. En el Purple Portal, introduzca estas credenciales en la pestaña de integración de UniFi.

Buenas prácticas

1. Requisitos del certificado SSL

Nunca utilice un certificado SSL autofirmado en un controlador UniFi de producción o en un servidor de portal externo. Los navegadores web modernos y los asistentes de Captive Portal (CPA) de los sistemas operativos exigen una validación SSL/TLS estricta. Un certificado autofirmado provocará una advertencia de seguridad muy visible (por ejemplo, "La conexión no es privada"), lo que provocará altas tasas de abandono y daños a la imagen de marca.

  • Implemente un certificado SSL válido y de confianza pública (por ejemplo, Let's Encrypt o un certificado de CA comercial) en el FQDN del controlador UniFi.
  • Asegúrese de que el FQDN del controlador se resuelva correctamente tanto desde la VLAN de invitados interna como desde la internet pública.

2. Configuración de DNS

La resolución lenta de DNS es la causa principal de que la redirección del Captive Portal sea lenta.

  • No dirija el DNS de invitados a la IP local de la puerta de enlace UniFi a menos que la puerta de enlace tenga configurado un reenvío de DNS de alto rendimiento.
  • En su lugar, configure el ámbito DHCP de invitados para distribuir servidores DNS públicos rápidos y resilientes directamente a los clientes (por ejemplo, Primario: 1.1.1.1, Secundario: 8.8.8.8).

3. Configuración de WiFi de invitados con RADIUS (Alternativa Enterprise)

Para las ubicaciones que requieren seguridad 802.1X basada en certificados o credenciales en lugar de un SSID abierto con un portal web, UniFi admite la integración con un Cloud RADIUS externo [6].

  • Configure un RADIUS Profile en Settings > Profiles > RADIUS.
  • Introduzca las direcciones IP de los servidores RADIUS principal y secundario y los secretos compartidos proporcionados por Purple.* Habilite RADIUS Accounting y establezca el Interim Update Interval en 300 segundos para garantizar el seguimiento de sesiones en tiempo real.
  • En la configuración del SSID, establezca el protocolo de seguridad en WPA2 Enterprise o WPA3 Enterprise [7] y seleccione el perfil RADIUS.

comparison_chart.png

Resolución de problemas y mitigación de riesgos

Al implementar Captive Portals externos, los administradores de red suelen encontrarse con varios modos de fallo comunes. La siguiente tabla detalla estos problemas, sus causas principales y las medidas de mitigación precisas:

Síntoma Análisis de la causa raíz Acción correctiva y mitigación
Pantalla blanca / El portal no se carga El dispositivo cliente no puede resolver o alcanzar el FQDN del servidor del portal externo. 1. Verifique que portal.purplehotspot.com esté en la lista de acceso de preautorización (Pre-Authorization Access).
2. Asegúrese de que el cliente invitado haya recibido una IP y un servidor DNS válidos a través de DHCP.
3. Realice una búsqueda DNS (DNS lookup) en el dispositivo cliente para verificar la resolución del FQDN del portal.
Error de SSL "La conexión no es privada" El UniFi Controller está utilizando un certificado autofirmado o el FQDN de redirección no coincide con el nombre común (common name) del certificado SSL. 1. Instale un certificado SSL de confianza pública en el UniFi Controller.
2. Verifique que Redirect Using Hostname esté habilitado y coincida exactamente con el FQDN del certificado.
3. Desactive "Redirect HTTPS" en la configuración de control de invitados de UniFi para evitar que el AP intente interceptar el tráfico HTTPS en el puerto 443, lo que de forma natural genera advertencias de SSL.
La autenticación es correcta, pero el acceso a Internet está bloqueado La nube de Purple pudo autenticar al usuario, pero falló la llamada API para autorizar la dirección MAC del cliente en el UniFi Controller. 1. Compruebe las reglas del firewall para asegurarse de que el puerto 443 (o 8443 para versiones heredadas) esté abierto para el tráfico entrante al UniFi Controller desde los rangos de IP de Purple.
2. Verifique que la API Key o las credenciales de administrador local introducidas en el Portal de Purple sean válidas y tengan permisos de administrador.
3. Revise los registros del UniFi Controller (server.log) para detectar fallos de autenticación de la API.
Los botones de inicio de sesión social (p. ej., Google) no funcionan Los dominios de autenticación del IdP están bloqueados por la lista de control de acceso del AP. 1. Añada los dominios comodín completos para el IdP específico a la lista de acceso de preautorización (Pre-Authorization Access) (p. ej., *.google.com, *.googleapis.com).
2. Si utiliza Facebook, asegúrese de que los dominios del SDK de Facebook estén completamente permitidos en la lista blanca (whitelist).
Desconexiones frecuentes / Solicitudes de autenticación recurrentes El tiempo de espera de la sesión del controlador UniFi es más corto que la duración de la sesión de Purple, o los tiempos de concesión de DHCP son demasiado cortos. 1. Alinee el ajuste de Session Timeout de UniFi Guest Hotspot con la política de sesión de Purple (p. ej., 24 horas).
2. Aumente el tiempo de concesión de DHCP en la VLAN de invitados a un mínimo de 12 o 24 horas para evitar el agotamiento de direcciones IP y la reautenticación a mitad de sesión.

ROI e impacto empresarial

Aunque implementar un captive portal externo requiere una ingeniería de red cuidadosa, los resultados comerciales y el retorno de la inversión (ROI) superan con creces la complejidad de la implementación inicial.

Captura de datos empresariales y enriquecimiento de CRM

El portal de invitados nativo de UniFi es una utilidad "a ciegas"; otorga acceso a Internet sin capturar la identidad del usuario. Al superponer Purple, los establecimientos pueden capturar valiosos datos de origen (correos electrónicos, números de teléfono, perfiles sociales) de manera totalmente compatible con GDPR y CCPA. Estos datos se sincronizan automáticamente en tiempo real con sistemas CRM, plataformas de marketing (por ejemplo, Salesforce, HubSpot, Mailchimp) y programas de fidelización, lo que permite realizar campañas de marketing altamente segmentadas que fomentan las visitas recurrentes y el valor de vida del cliente.

Gestión multisitio y marca blanca (White-Labeling)

Para los proveedores de servicios gestionados (MSP) y los operadores de empresas multisitio, gestionar la red WiFi de invitados en cientos de establecimientos a través de controladores UniFi individuales es muy ineficiente. Purple proporciona un único panel de control centralizado en la nube para gestionar las páginas de inicio, las condiciones de cumplimiento y las analíticas en todos los establecimientos a nivel global, independientemente de la distribución del controlador UniFi subyacente.

Analíticas en tiempo real e inteligencia espacial

Purple transforma la red inalámbrica UniFi en una potente matriz de sensores. Al analizar las solicitudes de sondeo (probe requests) y los metadatos de conexión, Purple ofrece una profunda inteligencia espacial, que incluye:

  • Analíticas de afluencia (Footfall): Visitantes totales, tráfico de paso y tasas de conversión (de paso a entrada).
  • Tiempo de permanencia: Duración media de las visitas, segmentada por tipo de cliente (nuevo frente a recurrente).
  • Recencia y frecuencia: Con qué frecuencia regresan los clientes y el tiempo transcurrido entre visitas.
  • Mapas de calor del establecimiento: Representación visual del flujo y la densidad de visitantes, lo que permite a los operadores de tiendas y establecimientos optimizar la distribución y el personal.

Monetización a través de redes de medios minoristas (Retail Media Networks)

Para grandes recintos como estadios, centros comerciales y aeropuertos, la página de inicio del captive portal representa un espacio digital de gran valor. Purple permite a los establecimientos monetizar este espacio integrándose con redes de medios minoristas, ofreciendo publicidad programática segmentada, experiencias de inicio de sesión patrocinadas y promociones localizadas directamente a los invitados en el momento de la conexión.

Referencias

Definiciones clave

Captive Portal

Una página web que intercepta la conexión de red inicial de un invitado y requiere autenticación, registro o aceptación de términos antes de otorgar acceso total a internet.

Se encuentra inmediatamente al conectarse a un SSID de invitados abierto; gestionado por el redirector del AP y el servidor de portal externo.

Servidor de portal externo

Una aplicación web de terceros (como Purple) que aloja la página de bienvenida para invitados y gestiona la autenticación de usuarios, superando las limitaciones de portal del controlador integrado.

Configurado en los ajustes de UniFi Guest Hotspot para reemplazar la página de destino nativa de UniFi.

Walled Garden (acceso de preautorización)

Una lista permitida de dominios, subdominios o direcciones IP a los que los clientes no autenticados pueden acceder antes de completar el proceso de inicio de sesión del Captive Portal.

Esencial para cargar la propia página del portal, los recursos CSS/JS y los endpoints de inicio de sesión de OAuth de terceros.

DNSmasq

Un servidor DHCP y de reenvío de DNS ligero que se ejecuta localmente en los puntos de acceso de UniFi para interceptar y redirigir las consultas de DNS de los invitados durante el estado de preautorización.

Gestiona la redirección de DNS inicial que obliga a los dispositivos cliente a activar sus asistentes de Captive Portal integrados.

Handshake de autorización de API

El proceso en el que el servidor de portal externo (Purple) realiza una llamada de API segura al controlador de UniFi para cambiar la dirección MAC de un cliente de "en cuarentena" a "autorizada".

Ocurre inmediatamente después de que el usuario completa con éxito el flujo de inicio de sesión en la página de bienvenida.

Aislamiento de dispositivos cliente

Una función de seguridad que evita que los clientes inalámbricos en el mismo SSID o VLAN se comuniquen entre sí, mitigando el riesgo de ataques a la red local.

Habilitado en la configuración de WiFi y red de UniFi para proteger la privacidad de los invitados y asegurar la red del establecimiento.

RADSEC (RADIUS sobre TLS)

Un protocolo que protege el tráfico de autenticación y contabilidad de RADIUS envolviéndolo en un túnel TLS seguro, evitando la interceptación y manipulación en redes públicas.

Compatible con UniFi Network 8.4+ para implementaciones empresariales multisitio seguras mediante WPA2/WPA3 Enterprise.

CPA (Asistente de Captive Portal)

Una utilidad del sistema operativo integrada en iOS, Android, Windows y macOS que detecta automáticamente un Captive Portal intentando obtener un endpoint HTTP/HTTPS conocido.

Activa la ventana emergente "Iniciar sesión en WiFi" en el dispositivo del usuario inmediatamente después de la conexión.

Ejemplos prácticos

Un centro comercial de gran afluencia con 150 puntos de acceso UniFi y una aplicación de red UniFi alojada de forma propia en AWS necesita implementar Purple. El equipo de TI quiere utilizar el inicio de sesión social de Google y Facebook para la autenticación de invitados. Sin embargo, durante las pruebas iniciales, los invitados que hacen clic en los botones de inicio de sesión social se encuentran con una pantalla en blanco o un error de resolución de DNS.

El problema se debe a un walled garden restrictivo (Pre-Authorization Access) que impide que el dispositivo del invitado resuelva o llegue a los endpoints de autenticación de Google y Facebook antes de estar autorizado. Para resolver esto, el administrador de red debe iniciar sesión en la aplicación de red UniFi, ir a Settings > Profiles > Guest Hotspot y expandir la sección Pre-Authorization Access. Debe agregar los dominios comodín completos para los proveedores de identidad de Google y Facebook. Para Google, esto incluye accounts.google.com, ssl.gstatic.com y *.googleapis.com. Para Facebook, requiere *.facebook.com, *.facebook.net y *.fbcdn.net. Además, asegúrese de que el rango de DHCP de la red de invitados esté configurado para distribuir servidores DNS públicos y rápidos (por ejemplo, 1.1.1.1 y 8.8.8.8) directamente a los clientes, en lugar de apuntar a la puerta de enlace local de UniFi, que puede convertirse en un cuello de botella para las consultas DNS de preautorización.

Comentario del examinador: Este es un fallo clásico de 'vacío en el walled garden'. Dado que los flujos de inicio de sesión social dependen de redireccionamientos OAuth complejos a través de múltiples subdominios, omitir incluso un solo dominio de entrega de activos (como la CDN de Facebook `fbcdn.net`) impedirá la carga de la página. Los arquitectos de red siempre deben usar comodines (`*.domain.com`) cuando el controlador lo permita, y verificar la resolución de DNS desde un cliente no autenticado utilizando herramientas estándar como `nslookup` o `dig` contra los dominios de la lista blanca.

Un MSP está implementando Purple en una cadena de 50 hoteles boutique. Cada hotel tiene un UniFi Cloud Gateway Max local en sus instalaciones. El MSP desea gestionar todos los sitios desde una única cuenta de Purple, pero le preocupa la seguridad y cómo la nube de Purple se comunicará con los controladores locales individuales para autorizar las direcciones MAC de los invitados, dado que las puertas de enlace locales están detrás de IP públicas dinámicas con NAT.

La arquitectura óptima utiliza la API REST oficial de UniFi con redireccionamiento de puertos entrantes o un proxy inverso, combinado con DNS dinámico (DDNS). Para cada hotel: 1) Configure un nombre de host DDNS en el Cloud Gateway Max (por ejemplo, hotel01.mspdomain.com) para que la IP pública de la puerta de enlace sea siempre localizable. 2) Configure una regla de redireccionamiento de puertos en la puerta de enlace para redirigir el tráfico HTTPS entrante en un puerto alto no estándar (por ejemplo, 10443) a la IP de gestión de la puerta de enlace local en el puerto 443. 3) En el controlador UniFi, vaya a Settings > Control Plane > Integrations y genere una API Key única. 4) En el portal de Purple, configure un 'Venue' único para cada hotel, seleccionando la integración de Ubiquiti UniFi. Introduzca la dirección DDNS única con el puerto redireccionado (por ejemplo, hotel01.mspdomain.com:10443) y la API Key específica generada para ese sitio. Por último, proteja el redireccionamiento de puertos entrantes en cada puerta de enlace restringiendo las IP de origen a los rangos de IP de la nube pública de Purple, evitando el acceso no autorizado desde el resto de Internet.

Comentario del examinador: El uso de un puerto alto no estándar para el redireccionamiento de puertos, combinado con una lista blanca estricta de IP de origen para permitir únicamente los bloques de IP de la nube de Purple, mitiga los riesgos de seguridad de exponer el puerto de la API del controlador a la Internet pública. Esta arquitectura evita la necesidad de costosas IP públicas estáticas en cada sitio, al tiempo que mantiene capacidades sólidas de autorización MAC en tiempo real.

Preguntas de práctica

Q1. Un administrador de red ha configurado un Captive Portal externo en una red de invitados de UniFi. Durante las pruebas, observa que la página de bienvenida del Captive Portal se carga correctamente, pero después de que el invitado introduce su dirección de correo electrónico y hace clic en "Conectar", el navegador se queda colgado y finalmente muestra un error de tiempo de espera. El cliente permanece en cuarentena. ¿Cuál es la causa más probable de este problema y cómo debería investigarse?

Sugerencia: La página del portal se cargó, lo que significa que el DNS y el walled garden están funcionando. El fallo ocurre *después* de que el invitado envíe sus credenciales.

Ver respuesta modelo

La causa más probable es un fallo en el protocolo de autorización de la API (handshake) entre la nube de Purple y el UniFi Controller. Dado que la página del portal se cargó y el invitado pudo interactuar con ella, las configuraciones de DNS y del Acceso de Preautorización (Walled Garden) son correctas. Sin embargo, cuando el invitado completa la autenticación, Purple intenta enviar una llamada API REST segura (solicitud POST) al UniFi Controller para autorizar la dirección MAC del cliente. Si el UniFi Controller está detrás de un cortafuegos, NAT o en una red privada sin el redireccionamiento de puertos adecuado, o si las credenciales de la API (o clave API) son incorrectas, la solicitud de autorización fallará o se agotará el tiempo de espera. Para investigar: 1) Verifique que el FQDN y el puerto del UniFi Controller sean accesibles públicamente desde los rangos de IP de Purple. 2) Compruebe las reglas de entrada del cortafuegos en la puerta de enlace que protege al UniFi Controller para asegurarse de que el puerto 443 (u 8443) esté abierto. 3) En el Portal de Purple, verifique que la configuración de integración de UniFi contenga la clave API o las credenciales de administrador correctas y que la URL del controlador sea exacta. 4) Inspeccione el archivo server.log del UniFi Controller para buscar cualquier intento de conexión entrante o errores de autenticación de la API desde las direcciones IP de Purple.

Q2. Una implementación empresarial requiere configurar una red de invitados con un Captive Portal externo. El arquitecto de red desea utilizar HTTPS para todo el tráfico del Captive Portal para evitar la interceptación de credenciales. Habilitan "Use Secure Portal (HTTPS)" y "Redirect Using Hostname" en UniFi, apuntando al FQDN del portal externo. Sin embargo, cuando los clientes se conectan, sus navegadores muestran inmediatamente una advertencia grave de "SSL Certificate Common Name Mismatch" o "Certificate Not Trusted", bloqueando el acceso. ¿Cómo se puede resolver esto?

Sugerencia: Piense en qué dispositivo está sirviendo el redireccionamiento inicial y qué certificado SSL está presentando al cliente.

Ver respuesta modelo

Este problema ocurre porque el punto de acceso (AP) o el UniFi Controller intentan interceptar una solicitud HTTPS del cliente y redirigirla al Captive Portal. Cuando un cliente se conecta e intenta visitar un sitio web HTTPS (por ejemplo, https://www.google.com), el redireccionador del AP intercepta el tráfico. Para realizar el redireccionamiento a través de HTTPS, el AP debe presentar un certificado SSL. Dado que el AP no posee un certificado SSL válido para www.google.com, el navegador del cliente detecta una condición de intermediario (MITM) y genera una advertencia de SSL grave. Para resolver esto: 1) Asegúrese de que el propio UniFi Controller tenga instalado un certificado SSL válido y de confianza pública que coincida con su FQDN configurado. 2) En la configuración de la red de invitados de UniFi, desactive "Redirect HTTPS" (deje habilitado únicamente el redireccionamiento HTTP). Esto evita que el AP intente interceptar el tráfico HTTPS. En su lugar, la red dependerá del asistente de Captive Portal (CPA) del sistema operativo del dispositivo cliente, que prueba la conectividad mediante endpoints HTTP simples (por ejemplo, http://captive.apple.com o http://connectivitycheck.gstatic.com). El AP puede interceptar de forma segura estas solicitudes HTTP en el puerto 80 y redirigirlas a la URL segura HTTPS del portal de Purple (https://portal.purplehotspot.com) sin activar ninguna advertencia de SSL en el navegador.

Q3. Una cadena hotelera desea implementar seguridad WPA3-Enterprise para su red de invitados VIP manteniendo la integración con la plataforma analítica de Purple. El equipo de TI local no está seguro de si pueden utilizar el redireccionamiento estándar de Captive Portal de External Portal Server con WPA3-Enterprise. ¿Cuál es el enfoque arquitectónico correcto para este escenario?

Sugerencia: WPA3-Enterprise utiliza autenticación 802.1X, que ocurre en la fase de asociación, antes de que se asigne una dirección IP. Esto es fundamentalmente diferente de un SSID abierto con un Captive Portal.

Ver respuesta modelo

WPA3-Enterprise (y WPA2-Enterprise) utilizan la autenticación 802.1X, la cual es fundamentalmente incompatible con la redirección web estándar de un Captive Portal. En una red 802.1X, la autenticación ocurre en la fase de asociación (Capa 2) utilizando métodos EAP (como EAP-TLS o PEAP) antes de que se asigne una dirección IP al cliente o se le permita el acceso a la red. Por lo tanto, no se puede redirigir a un cliente a una página de inicio de sesión (splash page) basada en web. Para integrar WPA3-Enterprise con Purple: 1) Cambie del modelo de "Servidor de Portal Externo" a un modelo de RADIUS Externo. 2) Configure un Perfil RADIUS en la aplicación de red UniFi, introduciendo las direcciones IP del servidor Cloud RADIUS de Purple, los puertos de autenticación (normalmente 1812), los puertos de contabilidad (normalmente 1813) y el secreto compartido. 3) Habilite la Contabilidad RADIUS (RADIUS Accounting) y establezca un Intervalo de actualización intermedio (Interim Update Interval) de 300 segundos. 4) Configure el SSID VIP para usar WPA3 Enterprise y seleccione el Perfil RADIUS. Cuando un invitado VIP se conecta, su dispositivo se autentica directamente contra el servidor Cloud RADIUS de Purple utilizando sus credenciales empresariales únicas o su certificado. El servidor RADIUS de Purple autoriza la conexión y recibe las actualizaciones de contabilidad, lo que permite al establecimiento capturar análisis de conexión, duración de la sesión y uso de datos sin necesidad de una página de inicio de sesión basada en web.

Continúe leyendo esta serie

Integración de CommScope Ruckus con Purple WiFi: Guía de instalación y configuración

Esta guía de referencia técnica proporciona un manual de configuración definitivo para integrar arquitecturas de CommScope Ruckus con Purple WiFi. Detalla implementaciones paso a paso para captive portals de Guest WiFi, WiFi seguro para el personal a través de 802.1X y aislamiento de red multiinquilino mediante Ruckus Dynamic PSK.

Leer la guía →

Integración de puntos de acceso Allied Telesis con Purple WiFi

Esta guía proporciona un manual de configuración completo para integrar los puntos de acceso de la serie TQ de Allied Telesis con Purple WiFi. Cubre la redirección externa de Captive Portal, la autenticación RADIUS 802.1X y el direccionamiento dinámico de VLAN mediante claves precompartidas privadas (PPSK) para despliegues multiinquilino seguros.

Leer la guía →

Integración de los puntos de acceso Grandstream GWN con Purple WiFi

Esta guía técnica de referencia autorizada detalla cómo integrar los puntos de acceso Grandstream GWN con la plataforma de análisis y Guest WiFi de Purple. Cubre la configuración del Captive Portal de Grandstream, los ajustes de RADIUS AAA, la configuración de walled garden, la autenticación segura para el personal mediante 802.1X con direccionamiento dinámico de VLAN y la segmentación PPSK multiinquilino, proporcionando una guía práctica paso a paso para MSP e instalaciones de TI que desplieguen WiFi para invitados y personal a gran escala.

Leer la guía →