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 la mecánica de red subyacente, la implementación paso a paso de la red de invitados, la lista de permitidos del walled garden, la autenticación RADIUS y las estrategias de resolución de problemas para profesionales senior de TI y administradores de redes.

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

Escucha esta guía

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 profundizaremos en 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 utilizadas a nivel mundial en los sectores de hostelería, retail y entornos corporativos.

Si usted es administrador 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 bajo el capó, cómo configurarlo correctamente, cuáles son los errores comunes y por qué superponer Purple a una implementación de UniFi es la decisión arquitectónica correcta para los establecimientos que necesitan más que una página de bienvenida básica.

Comencemos.

[ANÁLISIS TÉCNICO DETALLADO — aproximadamente 5 minutos]

En primer lugar, entendamos qué sucede realmente cuando un dispositivo de invitado se conecta a un SSID de UniFi que tiene habilitado un Captive Portal.

Cuando el dispositivo de un 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. Sin embargo, el dispositivo se coloca inmediatamente en lo que UniFi denomina un estado "pendiente". En este estado, el proceso DNSmasq integrado del AP intercepta cada consulta de DNS que realiza el dispositivo, independientemente del servidor DNS que el dispositivo crea que está utilizando. El AP redirige todo el tráfico de DNS hacia sí mismo.

Al mismo tiempo, 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 de "Iniciar sesión en la red WiFi" en 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 integrado de UniFi, la página de bienvenida se sirve directamente desde la aplicación UniFi Network. Es funcional y rápido de configurar, pero está muy limitado. Se obtiene una autenticación de contraseña básica, cupones y pagos con Stripe. No hay captura de correo electrónico, ni inicio de sesión con redes sociales, ni gestión de consentimiento de GDPR, ni integración con CRM, ni analíticas significativas más allá de los conteos de sesiones.

Al configurar un servidor de portal externo (que es la opció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.

Aquí está el detalle técnico importante sobre esa URL de redirección. Cuando UniFi redirige a un invitado a tu 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 de SSID. Tu 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 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 (handshake) 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 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 Acceso de Preautorización (Pre-Authorization Access). 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, tu walled garden debe incluir el nombre de dominio completamente calificado (FQDN) de tu portal de Purple y las direcciones IP o rangos CIDR a los que se resuelve la infraestructura de Purple. Si utilizas el inicio de sesión con redes sociales — Facebook, Google, Microsoft —, también debes agregar los dominios de los endpoints de 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 de texto plano 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 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 tu walled garden incluya los dominios de detección de Captive Portal para los principales sistemas operativos, y que tu 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 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 tengan éxito. Si tu controlador está en una red privada detrás de NAT, deberás asegurarte de que los puertos de la API correspondientes sean accesibles. Para controladores autoalojados, normalmente es 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 requieren acceso entrante a tu controlador.

Para la autenticación basada en RADIUS (que es relevante cuando implementas 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 los métodos estándar 802.1X EAP. Configuras el perfil de RADIUS en Settings, Networks, RADIUS Servers, y luego haces referencia a ese perfil en la configuración de tu 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 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íteme darte la lista de verificación práctica para la implementación que revisaría con cualquier cliente que implemente Purple en UniFi.

Primero, la segmentación de red. Tu SSID de invitado debe estar en una VLAN dedicada, aislada de tus redes corporativas y de IoT. UniFi hace que esto sea sencillo: crea una red dedicada en Settings, Networks, asígnale un ID de VLAN y asocia tu SSID de invitado con esa red. Habilita el aislamiento de clientes en la red de invitados para evitar el tráfico entre invitados.

Segundo, el controlador debe tener un FQDN válido y un certificado SSL de confianza. No dependas de la dirección IP. Utiliza un nombre de dominio adecuado, obtén un certificado Let's Encrypt o comercial para este y configura UniFi para que use ese certificado. Esto resuelve la mayoría de los problemas de redirección HTTPS.

Tercero, construye tu walled garden con cuidado y pruébalo. Las entradas mínimas son: el dominio de tu 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és utilizando. Realiza 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, utiliza una cuenta de administrador local dedicada en la UniFi Network Application con los permisos mínimos requeridos. No utilices tus credenciales de administrador principal. Si estás en Network Application 9.1 o posterior, utiliza 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 en UniFi puede ser de tan solo ocho horas. Para implementaciones en el sector de la hospitalidad, donde los huéspedes pueden hospedarse varias noches, configure las duraciones de sesión adecuadas en la configuración 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 realizar la implementación en un controlador autohospedado que no es de acceso público. Si Purple no puede comunicarse con su controlador para autorizar a los invitados, el portal se cargará pero la autenticación fallará de forma silenciosa. Siempre verifique la conectividad de la API desde la infraestructura de Purple antes de lanzar el servicio.

[PREGUNTAS Y RESPUESTAS RÁPIDAS — aproximadamente 1 minuto]

¿Esto funciona en UniFi Dream Machine Pro? Sí. Todas las consolas de 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 varios sitios de UniFi desde una sola cuenta de Purple? Sí. La arquitectura multisitio de Purple está diseñada exactamente para esto. Cada establecimiento se configura como un sitio independiente en Purple, asignado al sitio correspondiente de UniFi.

¿Necesito abrir puertos de firewall en el gateway 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, lo cual es un flujo de autenticación diferente.

[RESUMEN Y SIGUIENTES PASOS — aproximadamente 1 minuto]

En resumen: implementar Purple como un Captive Portal externo en UniFi es una integración sólida y con un soporte excelente. Los pasos clave son: configurar su SSID de invitado con la opción de External Portal Server apuntando a la URL de su portal de Purple, crear un walled garden integral 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 establecimiento.

El caso de negocio es sencillo. El portal integrado de UniFi le ofrece una splash page. Purple le ofrece una plataforma de experiencia de invitado basada en analíticas y lista para el cumplimiento normativo que se integra con su CRM, captura datos de primera mano bajo el consentimiento de GDPR y proporciona las analíticas de flujo de personas 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 multisitio y las capacidades de marca blanca de Purple lo convierten en el complemento perfecto 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 escuchar.

Puntos clave

✓La integración de Purple con Ubiquiti UniFi utiliza la función de Servidor de Portal Externo para enrutar la autenticación de invitados a través de la nube segura de Purple.
✓Los clientes no autenticados se colocan en un estado de cuarentena donde el AP UniFi intercepta el tráfico DNS y HTTP, emitiendo una redirección 302 a Purple.
✓Es obligatoria una lista completa de acceso de preautorización (Walled Garden) para permitir que los clientes lleguen a Purple y a proveedores de identidad de terceros (Google, Facebook) antes de la autenticación.
✓Un certificado SSL con confianza pública en el controlador UniFi es indispensable para evitar advertencias de seguridad del navegador durante el flujo de redirección.
✓La autorización de la API se establece utilizando las claves API REST modernas de UniFi (Network Application 9.1+) o una cuenta de administrador local dedicada para sistemas heredados.
✓La implementación de Purple añade análisis avanzados de afluencia de personas, automatización de marketing, integración de CRM y cumplimiento normativo multisitio sobre el hardware de alto rendimiento de UniFi.

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

Resumen ejecutivo

A medida que los recintos físicos empresariales —que abarcan desde cadenas de retail a gran escala [1] y grupos hoteleros multisitio [2] hasta los principales 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 confiable, rentable y escalable. Sin embargo, su portal de invitados nativo carece de la captura avanzada de datos, la analítica multisitio, la integración con CRM, el cumplimiento de 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 funcionalidad de External Portal Server de UniFi, los arquitectos de red e integradores de sistemas pueden omitir las limitaciones del controlador local. Esta integración canaliza 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 de marketing y operaciones de nivel empresarial.

Análisis técnico profundo

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 ocurren cuando un cliente no autenticado se conecta a la red inalámbrica.

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

El flujo de trabajo del Captive Portal de UniFi opera bajo un modelo estricto basado en estados. Cuando un cliente se asocia con un SSID habilitado para invitados, 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, máscara de subred, puerta de enlace y servidores DNS.	Asociación estándar 802.11 y concesión DHCP.
2. Cuarentena	Punto de Acceso UniFi (AP)	El AP coloca la dirección MAC del cliente en un estado En 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 DNS del cliente.
4. Intercepción de HTTP	Redireccionador del AP	El AP ejecuta un demonio redireccionador HTTP ligero en el puerto 80.	Cualquier solicitud HTTP realizada por el cliente es interceptada. El AP responde con una redirección HTTP 302 Found.
5. Redirection	Client Browser	El navegador del cliente (o el Asistente de Captive Portal del sistema operativo) se redirecciona a la URL del portal externo configurado.	La URL de redirección 302 se complementa con parámetros de consulta críticos que contienen metadatos del cliente y del AP.
6. Authentication	External Portal (Purple)	El cliente interactúa con la splash page de Purple, completando la autenticación (por ejemplo, inicio de sesión con redes sociales, registro de correo electrónico, OTP por SMS).	Sesión HTTPS segura alojada en la infraestructura de nube de Purple.
7. API Handshake	Purple Cloud & UniFi Controller	Purple valida las credenciales y emite una llamada de API segura a la aplicación de red UniFi.	Llamada de 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. Authorization	UniFi Controller & AP	El controlador UniFi 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 enrutamiento completo a la puerta de enlace 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 autorización posterior de la API:

https://portal.purplehotspot.com/guest/s/default/?ap=94:2a:6f:d0:30:57&amp;id=1c:71:25:63:e4:24&amp;t=1742398732&amp;url=http://connectivitycheck.gstatic.com%2F&amp;ssid=purple-guest

ap: La dirección MAC del Access Point UniFi específico al que está asociado el cliente.
id: La dirección MAC del dispositivo cliente que solicita acceso a la red.
t: Una marca de tiempo Unix epoch que representa la hora 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 de Captive Portal del sistema operativo).
ssid: El nombre de SSID al que se conectó el cliente, lo que permite al portal presentar una imagen de marca específica del sitio.

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 los destinos definidos explícitamente en la lista de Acceso previo a la autorización (comúnmente denominada Walled Garden). Debido a que los dispositivos cliente modernos ejecutan Asistentes de Captive Portal (CPA) automatizados que prueban la conectividad a través de HTTPS, y debido a que la autenticación externa a menudo depende de proveedores de identidad (IdP) de terceros, configurar un walled garden robusto y preciso es fundamental.

Si se omite un dominio o rango de IP requerido del walled garden, la splash page no se cargará, los botones de inicio de sesión social se congelarán o el dispositivo del cliente interrumpirá la conexión WiFi por completo, asumiendo una red defectuosa.

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 Ubiquiti UniFi Network Application (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.

Vaya a Settings > Networks en la UniFi Network Application.
Haga clic en Create New Network.
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 de invitado a invitado).
- 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, de 10.90.0.10 a 10.90.3.254).
- DNS Server: Establézcalo en resolutores públicos confiables (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 de invitados

Vaya a Settings > WiFi y haga clic en Create New WiFi Network.
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).
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.

Vaya a Settings > Profiles > Guest Hotspot (o Settings > Guest Control en versiones anteriores del controlador).
En Authentication, seleccione External Portal Server.
Configure los siguientes campos:
- IP / FQDN: Ingrese el FQDN proporcionado por Purple (por ejemplo, portal.purplehotspot.com).
- Use Secure Portal (HTTPS): Active (ON) (Obligatorio para la seguridad y la compatibilidad con navegadores modernos).
- Redirect Using Hostname: Active (ON) e ingrese el FQDN portal.purplehotspot.com.
- Port: 443 (HTTPS estándar).
- HTTPS Redirection: Active (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 previo a la autenticació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, agregue 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 implementaciones que utilicen el procesamiento de pagos de Stripe, agregue *.stripe.com y *.stripe.network a la lista de preautorización.

Paso 5: Establecer el saludo de 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 posteriores (API REST recomendada)

En el controlador UniFi, vaya a Settings > Control Plane > Integrations.
En la sección API Keys, haga clic en Generate New API Key.
Asigne un nombre (por ejemplo, Purple Integration Key) y establezca los permisos en Administrator.
Copie la API Key generada.
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)

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

Mejores 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 aplican una validación SSL/TLS estricta. Un certificado autofirmado provocará una advertencia de seguridad muy visible (por ejemplo, "Su conexión no es privada"), lo que generará altas tasas de abandono y daños a la 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 de DNS lenta es la causa principal de la redirección lenta del Captive Portal.

No apunte 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 alcance de 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 para invitados con RADIUS (Alternativa empresarial)

Para los establecimientos 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 Cloud RADIUS externo [6].

Configure un RADIUS Profile en Settings > Profiles > RADIUS.
Ingrese las direcciones IP de los servidores RADIUS primario y secundario y los secretos compartidos proporcionados por Purple.* Habilite RADIUS Accounting y establezca el Interim Update Interval en 300 segundos para asegurar el seguimiento de la sesión 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.

Solució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 raíz y los pasos exactos para mitigarlos:

Síntoma	Análisis de causa raíz	Acción correctiva y mitigación
Pantalla en blanco / 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. 2. Asegúrese de que el cliente invitado haya recibido una IP válida y un servidor DNS a través de DHCP. 3. Realice una búsqueda DNS 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 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 naturalmente genera advertencias de SSL.
La autenticación es exitosa, pero el Internet está bloqueado	La nube de Purple pudo autenticar al usuario, pero la llamada API para autorizar la dirección MAC del cliente en el UniFi Controller falló.	1. Verifique las reglas del firewall para asegurarse de que el puerto `443` (o `8443` para sistemas heredados) esté abierto de entrada al UniFi Controller desde los rangos de IP de Purple. 2. Verifique que la API Key o las credenciales de administrador local ingresadas en el portal de Purple sean válidas y tengan permisos de administrador. 3. Revise los registros del UniFi Controller (`server.log`) para identificar fallas 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. Agregue los dominios comodín completos para el IdP específico a la lista de acceso de preautorización (p. ej., `.google.com`, `.googleapis.com`). 2. Si usa Facebook, asegúrese de que los dominios del SDK de Facebook estén completamente en la lista de permitidos.
Desconexiones frecuentes / Solicitudes de autenticación recurrentes	El tiempo de espera de la sesión en UniFi Controller es más corto que la duración de la sesión en Purple, o los tiempos de concesión de DHCP son demasiado cortos.	1. Alinee el ajuste de Session Timeout del Guest Hotspot de UniFi con la política de sesión de Purple (por ejemplo, 24 horas). 2. Incremente el tiempo de concesión de DHCP en la VLAN de invitados a por menos 12 o 24 horas para evitar el agotamiento de direcciones IP y la reautenticación a mitad de la sesión.

ROI e impacto comercial

Aunque implementar un Captive Portal externo requiere una ingeniería de red cuidadosa, los resultados comerciales y el retorno de inversión (ROI) superan por mucho la complejidad de la implementación inicial.

Captura de datos empresariales y enriquecimiento de CRM

El portal de invitados nativo de UniFi es una herramienta "a ciegas"; otorga acceso a internet sin registrar la identidad del usuario. Al integrar Purple, los establecimientos pueden capturar valiosos datos de primera mano (correos electrónicos, números de teléfono, perfiles de redes sociales) de conformidad absoluta 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 fidelidad, lo que permite realizar campañas de marketing altamente segmentadas que impulsan las visitas recurrentes y el valor de vida del cliente.

Gestión multisitio y marca blanca

Para los proveedores de servicios gestionados (MSP) y operadores de empresas multisitio, administrar el WiFi de invitados en cientos de establecimientos a través de controladores UniFi individuales es sumamente ineficiente. Purple ofrece un único panel de control centralizado en la nube para gestionar páginas de bienvenida, términos de conformidad y análisis en todos los establecimientos a nivel mundial, independientemente de la distribución del controlador UniFi subyacente.

Análisis 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:

Análisis de afluencia (footfall): Total de visitantes, tráfico de paso y tasas de conversión (de paso a ingreso).
Tiempo de permanencia: Duración promedio de las visitas, segmentada por tipo de cliente (nuevo vs. 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 el diseño del espacio y la asignación de personal.

Monetización a través de redes de medios minoristas

Para grandes establecimientos como estadios, centros comerciales y aeropuertos, la página de bienvenida del Captive Portal representa un espacio digital sumamente valioso. Purple permite a los establecimientos monetizar este espacio mediante la integración con redes de medios minoristas (Retail Media Networks), mostrando publicidad programática dirigida, experiencias de inicio de sesión patrocinadas y promociones localizadas directamente a los invitados en el momento de la conexión.

Referencias

[1] Purple para retail: Análisis y marketing de WiFi para establecimientos comerciales
[2] Purple para hotelería: Soluciones de WiFi de invitados empresariales para hoteles y restaurantes
[3] Purple para transporte: WiFi público y analítica para centros de transporte
[4] Purple para el sector salud: Soluciones de WiFi para pacientes y visitantes en instalaciones de salud
[5] Productos principales de Purple: Plataforma de WiFi para invitados empresariales
[6] Guía de integración de Cloud RADIUS: Cómo implementar la autenticación 802.1X con Cloud RADIUS
[7] Mejores prácticas de control de acceso a la red: Las 10 mejores soluciones de control de acceso a la red (NAC) para 2026
[8] Referencia de Cisco Wireless (arquitectura comparativa): APs de Cisco Wireless: Guía 2026 de productos y despliegue
[9] Referencia de WiFi en la educación: WiFi en escuelas: La guía 2026 para administradores y TI
[10] Plataforma de analítica de Purple: Plataforma de marketing y analítica de WiFi

Definiciones clave

Captive Portal

Una página web que intercepta la conexión inicial de red 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; administrado por el redireccionador del AP y el servidor de portal externo.

Servidor de portal externo

Una aplicación web de terceros (como Purple) que hospeda 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 blanca 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, recursos CSS/JS y endpoints de inicio de sesión de OAuth de terceros.

DNSmasq

Un reenviador de DNS ligero y servidor DHCP que se ejecuta localmente en los puntos de acceso de UniFi para interceptar y redireccionar las consultas 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 de vuelta al controlador de UniFi para cambiar el estado de una dirección MAC de cliente de '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 en 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 al envolverlo en un túnel TLS seguro, evitando la interceptación y manipulación a través de redes públicas.

Soportado en UniFi Network 8.4+ para implementaciones empresariales seguras en múltiples sitios utilizando WPA2/WPA3 Enterprise.

CPA (Asistente de Captive Portal)

Una utilidad de sistema operativo integrada en iOS, Android, Windows y macOS que detecta automáticamente un Captive Portal al intentar recuperar un endpoint HTTP/HTTPS conocido.

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

Ejemplos resueltos

Un centro comercial de gran afluencia con 150 AP de UniFi y una aplicación de red UniFi alojada por ellos mismos en AWS necesita implementar Purple. El equipo de TI desea 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 es causado por un walled garden restrictivo (Pre-Authorization Access) que evita que el dispositivo del invitado resuelva o alcance los puntos de enlace de autenticación de Google y Facebook antes de ser autorizado. Para resolver esto, el administrador de la 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 de 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 alcance 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 apuntarlos a la puerta de enlace local de UniFi, lo 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 'brecha de walled garden'. Debido a 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`) romperá la representación de la página. Los arquitectos de red siempre deben usar comodines (`*.domain.com`) donde el controlador lo admita, y verificar la resolución de DNS desde un cliente no autenticado usando herramientas estándar como `nslookup` o `dig` contra los dominios en la lista de permitidos.

Un MSP está implementando Purple en una cadena de 50 hoteles boutique. Cada hotel tiene un UniFi Cloud Gateway Max local en el sitio. El MSP desea administrar todos los sitios desde una sola cuenta de Purple, pero le preocupa la seguridad y cómo la nube de Purple se comunicará de vuelta 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 reenvío 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 siempre sea rastreable. 2) Configure una regla de reenvío de puertos en la puerta de enlace para reenviar el tráfico HTTPS entrante en un puerto alto no estándar (por ejemplo, 10443) a la IP de administració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 clave API única. 4) En el portal de Purple, configure un 'Venue' único para cada hotel, seleccionando la integración de Ubiquiti UniFi. Ingrese la dirección DDNS única con el puerto reenviado (por ejemplo, hotel01.mspdomain.com:10443) y la clave API específica generada para ese sitio. Finalmente, proteja el reenvío 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 reenvío de puertos, combinado con una lista estricta de permitidos de IP de origen para permitir solo 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 mientras mantiene capacidades robustas de autorización de 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, nota que la página de bienvenida del Captive Portal se carga correctamente, pero después de que el invitado ingresa su dirección de correo electrónico y hace clic en 'Conectar', el navegador se congela y finalmente muestra un error de tiempo de espera agotado. 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ía sus credenciales.

Ver respuesta modelo

La causa más probable es una falla en el saludo de autorización de la API (handshake) entre la nube de Purple y el UniFi Controller. Dado que la página del portal cargó y el invitado pudo interactuar con ella, las configuraciones de DNS y de Acceso de Preautorización (Walled Garden) son correctas. Sin embargo, cuando el invitado completa la autenticación, Purple intenta enviar una llamada de 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 firewall, NAT o en una red privada sin el redireccionamiento de puertos adecuado, o si las credenciales de la API (o la clave de API) son incorrectas, la solicitud de autorización fallará o expirará 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) Revise las reglas de firewall entrantes en la puerta de enlace que protege al UniFi Controller para asegurarse de que el puerto 443 (o 8443) esté abierto. 3) En el Portal de Purple, verifique que la configuración de integración de UniFi contenga la clave de 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 intentos de conexión entrantes o errores de autenticación de 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 quiere usar HTTPS para todo el tráfico del Captive Portal para evitar el robo de credenciales. Habilita '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 de inmediato 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 está intentando interceptar una solicitud HTTPS del cliente y redireccionarla 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 Man-in-the-Middle (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 públicamente confiable 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 del Captive Portal (CPA) del sistema operativo del dispositivo cliente, el cual 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 redireccionarlas a la URL HTTPS segura 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 y, al mismo tiempo, mantener la integración con la plataforma de analíticas de Purple. El equipo de TI local no está seguro de si pueden utilizar el redireccionamiento estándar del servidor del Captive Portal externo con WPA3-Enterprise. ¿Cuál es el enfoque arquitectónico correcto para este escenario?

Sugerencia: WPA3-Enterprise utiliza autenticación 802.1X, la cual 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) mediante métodos EAP (como EAP-TLS o PEAP) antes de que al cliente se le asigne una dirección IP o se le permita el acceso a la red. Por lo tanto, no se puede redirigir a un cliente a una página de bienvenida 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 UniFi Network, ingresando 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 RADIUS Accounting y establezca un Intervalo de actualización intermedio 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 bienvenida 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 multi-inquilino mediante Dynamic PSK de Ruckus.

Integración de Access Points Allied Telesis con Purple WiFi

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

Grandstream GWN Access Points Integration with Purple WiFi

Esta guía de referencia técnica 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 del walled garden, la autenticación segura para el personal mediante 802.1X con direccionamiento dinámico de VLAN y la segmentación PPSK multi-tenant, proporcionando una guía paso a paso y práctica para MSPs y equipos de TI que despliegan WiFi para invitados y personal a gran escala.