Integración UniFi: Mejores Prácticas y Preguntas Comunes

Resumen

La Integración UniFi conecta Purple directamente con su Controlador de Red UniFi usando un método moderno de inicio de sesión por API, en lugar de depender de canales complejos de autenticación en segundo plano como RADIUS. Piénselo como Purple iniciando sesión de forma segura en su controlador como un usuario automatizado dedicado para aprobar rápidamente a sus invitados cuando completan su página de bienvenida. Debido a que esta configuración funciona como una conexión web directa, solucionar problemas generalmente se reduce a verificar direcciones web, cortafuegos y permisos de cuenta.

Requisitos Previos y Mejores Prácticas

Antes de configurar su integración, asegúrese de que su sistema UniFi esté preparado para comunicarse sin problemas con los servidores seguros en la nube de Purple.

1. Cree una Cuenta de Administrador UniFi Dedicada

Para que la automatización funcione sin ser bloqueada, debe crear una cuenta dedicada directamente dentro de su Controlador UniFi. Por seguridad y fiabilidad, configúrela exactamente así:

• Cuenta Local Sólo: La cuenta debe crearse localmente en el controlador, no una cuenta en la nube de Ubiquiti (ui.com inicio de sesión por correo electrónico). Si su interfaz fuerza una configuración por correo electrónico, cambie su controlador UniFi al modo Legacy UI en la configuración para crear un nombre de usuario y contraseña local estándar al instante.
• Derechos Completos de Administrador: El usuario debe tener privilegios de administrador/escritura. Un perfil de “Solo Lectura” no puede ejecutar autorizaciones de invitados.
• Desactive 2FA: La Autenticación de Dos Factores (2FA) debe estar completamente desactivada para este usuario específico, ya que los desafíos interactivos bloquean las consultas automatizadas en segundo plano.
• Mantenga las Contraseñas Estables: Asegúrese de que la casilla “Requerir que el usuario cambie la contraseña” esté completamente desmarcada.

Actualización Importante para Controladores Modernos:

• Para UniFi OS 8.6.9+ (Consolas de Hardware): Navegue directamente al Panel principal de UniFi OS (la configuración principal del sistema, no solo la aplicación de red), vaya a Administradores y Usuarios y cree un nuevo perfil. Establezca el Tipo de Cuenta explícitamente en Acceso Local Sólo y asigne el rol de Administrador del Sitio para que nuestra API pueda autenticarse correctamente.
• Para Nuevos Entornos Autoalojados (Servidor UniFi OS): Asegúrese de que su cuenta API dedicada se cree en la capa raíz del contenedor del sistema operativo para que el proxy frontal interno Nginx pueda validar las credenciales antes de enrutar al aplicación de red.

2. Registre su Hardware Correctamente en Purple

Al emparejar su red dentro del portal Purple, no seleccione números de modelo individuales de puntos de acceso (UAP). En su lugar, seleccione la plataforma de orquestación que los administra:

• Elija UniFi Network (Predeterminado Actual) para todas las implementaciones nuevas. Esto incluye consolas de hardware físicas (UDM, UDW, UDR, CloudKey Gen2), cortafuegos de alta gama (Enterprise Firewall Gateway / UDM Fortress) y cualquier servidor autoalojado Ubuntu/Debian que haya actualizado a la moderna UniFi OS Server (v5.0.6 / Network App 10.x y superior).
• Elija UniFi Network Controller (Legacy) solo si está ejecutando una instancia antigua y sin actualizar del controlador de software independiente en una computadora interna o host en la nube legado.

3. Abra Rutas de Red y Cortafuegos

Debido a que los servidores de Purple hacen una conexión directa a su controlador, su red necesita una ruta clara para recibir estas solicitudes:

• IP Pública Estática o FQDN: Si su controlador está alojado dentro de su red local, su conexión principal a internet debe usar una IP pública permanente y estática o una dirección web estable (FQDN) para que Purple siempre sepa dónde encontrarlo.
• Configure el Reenvío de Puertos: Asegúrese de que su router o cortafuegos redirija el tráfico entrante a la dirección IP interna de su controlador usando los números de puerto correctos:
  • Puerto 11443 (Nuevo Predeterminado): Requerido si su servidor autoalojado ha sido actualizado a la moderna arquitectura UniFi OS Server.
  • Puerto 8443 (Predeterminado Legacy): Solo se usa si su servidor ejecuta versiones antiguas e independientes de la Aplicación de Red UniFi.
  • Puerto 443: Usado si su sistema está ejecutándose en consolas oficiales de hardware Ubiquiti (UDM, UDW, UDR o CloudKey Gen2).
• Permita en la Lista Blanca las Direcciones IP de Purple: Si tiene un cortafuegos de seguridad activo, configúrelo para permitir tráfico entrante desde los nodos regionales de entrega en la nube de Purple:
  • Región 1: Contacte con Soporte
  • Región 2: Contacte con Soporte
  • Región 3: Contacte con Soporte

Preguntas Comunes y Solución de Problemas

• ¿Por qué mis invitados experimentan largas demoras o se quedan en una pantalla en blanco después de enviar el formulario WiFi?
  Esto ocurre cuando las reglas de invitados de su red bloquean accidentalmente el tráfico web oculto necesario para completar el proceso de inicio de sesión. Aunque el invitado haya completado el formulario con éxito, la red no les permite alcanzar la página final de redirección.
  
  La Solución: Abra su Controlador UniFi, navegue a Control de Acceso y declare explícitamente todas las rutas de destino esenciales dentro de su ACL Pre-Auth (Lista de Control de Acceso) o configuraciones Post-Autorización.
• ¿Por qué la pantalla de pago falla o se congela cuando los invitados intentan comprar acceso WiFi?
  El cortafuegos de seguridad de UniFi bloquea estrictamente todo acceso a internet hasta que un invitado esté completamente autenticado. Para permitir que los invitados paguen vía Stripe o PayPal, debe crear una excepción en el cortafuegos.
  
  La Limitación Crítica: Las plataformas UniFi (incluyendo gateways de seguridad empresariales como UXG Enterprise o EFG) no soportan coincidencia real con comodines en dominios (usando *) en sus reglas de cortafuegos. Si su pasarela de pago depende de subdominios dinámicos, UniFi bloqueará el tráfico y causará errores de inspección SSL. Debe buscar manualmente las direcciones IP numéricas públicas específicas del servidor de destino de su proveedor de pagos y añadir esos números exactos directamente en los parámetros de la Lista de Control de Acceso (ACL) Pre-Auth de UniFi.
• Mi servidor se actualizó recientemente y ahora los invitados se quedan atascados o ven un error "404 Not Found" en bucle. ¿Cómo lo soluciono?
  Esto ocurre cuando un servidor de software autoalojado existente se actualiza al moderno marco UniFi OS Server.
  
  La Causa: Las configuraciones legacy usaban la ruta web /api/login en el Puerto 8443. La arquitectura moderna UniFi OS cambia la ruta de inicio de sesión URL requerida a /api/auth/login y cambia el puerto web predeterminado al puerto TCP 11443. Si su panel Purple todavía está configurado con el tipo de hardware legacy, consulta la ruta incorrecta, resultando en una respuesta fatal 404 Not Found.
  
  La Solución: Inicie sesión en el portal Purple, vaya a sus Configuraciones del Lugar y cambie su tipo de hardware de la selección legacy antigua a la opción moderna UniFi Network. Asegúrese de actualizar las reglas de reenvío de puertos de su router para permitir tráfico sobre el Puerto Externo 11443, y agregue el sufijo de referencia de puerto (:11443) justo al lado de la dirección IP de su controlador en Purple.
• Veo una advertencia de "Tiempo de Conexión Agotado" o de inaccesibilidad en el panel de mi portal. ¿Qué pasa?
  Esto significa que la plataforma en la nube de Purple está intentando alcanzar su red, pero su Controlador UniFi no responde a la solicitud.
  
  Verifique sus direcciones: Confirme que la dirección IP pública o la dirección web de su controlador esté escrita perfectamente en las Configuraciones del Lugar en Purple.
  Verifique el estado de su IP: Asegúrese de que su conexión a internet use una IP pública permanente y estática si el controlador está alojado dentro de la red de su empresa.
  Revise el Reenvío de Puertos: Asegúrese de que las reglas de reenvío de puertos de su router estén activas y envíen tráfico a la IP interna de su controlador usando el Puerto 11443 o el Puerto 443 según su configuración.
  Revise su Cortafuegos: Asegúrese de que su cortafuegos de seguridad permita en la lista blanca las direcciones IP regionales en la nube de Purple.
• ¿Por qué recibo un error genérico de fallo de inicio de sesión o incompatibilidad durante la configuración?
  Si su nombre de usuario y contraseña son correctos pero el portal se niega a conectar, hay una incompatibilidad en la estructura de datos entre Purple y su sistema UniFi.
  
  La Solución: Esto casi siempre ocurre cuando el tipo de hardware seleccionado en el portal Purple no coincide con su versión de software, lo que obliga al sistema a usar el puerto y ruta de inicio de sesión incorrectos. Seleccione UniFi Network para todas las implementaciones modernas: consolas de hardware físicas (UDM, UDW, UDR, CloudKey Gen2), cortafuegos empresariales y servidores autoalojados actualizados a UniFi OS Server. Solo seleccione UniFi Network Controller (Legacy) si está ejecutando una instancia antigua y sin actualizar del controlador independiente.
• Las credenciales que ingresé son correctas, pero la integración aún falla al autorizar invitados. ¿Por qué?
  Sus datos de inicio de sesión coinciden perfectamente, pero la cuenta específica que creó para Purple no tiene la autoridad interna requerida para modificar estados de red. Aunque el inicio de sesión tenga éxito, Purple necesita poder "escribir" activamente datos de permiso para aprobar a un invitado en su red.
  
  La Solución: Inicie sesión en su Controlador UniFi, revise su lista de administradores y eleve el rol de la cuenta API de Purple a Administrador completo con privilegios de escritura.
• La configuración falla y menciona un desafío de seguridad o bloqueo de autenticación. ¿Cómo lo evito?
  Esto indica que la Autenticación de Dos Factores (2FA) o un aviso obligatorio de cambio de contraseña está activo en la cuenta que Purple intenta usar. Como Purple es un sistema automatizado en la nube, no puede leer un texto de seguridad temporal ni hacer clic en un enlace interactivo.
  
  La Solución: Convierta el perfil o cree uno nuevo que sea una cuenta de administrador local dedicada con 2FA completamente desactivado. Asegúrese de que la casilla “Requerir que el usuario cambie la contraseña” esté completamente desmarcada.
• Alojo mi controlador en unifi-hosting.ui.com y la configuración no puede encontrar mi sitio. ¿Cómo lo soluciono?
  Si usa las instancias oficiales de alojamiento en la nube gestionado de Ubiquiti, el sistema maneja los puertos de datos de manera diferente a un controlador de software alojado en computadora tradicional. Debido a que está construido sobre UniFi OS para ejecutar múltiples aplicaciones simultáneamente, la clasificación legacy fuerza una ruta de puerto incorrecta.
  
  La Solución: Vaya a sus configuraciones en Purple y cambie su Tipo de Hardware WiFi a UniFi Network. Esto obliga a Purple a comunicarse usando el puerto y ruta de inicio de sesión correctos de UniFi OS en lugar del puerto legacy del software 8443.