Guide de configuration du Captive Portal UniFi

Captive Portal pour Ubiquiti UniFi - Une présentation technique par Purple [INTRODUCTION & CONTEXTE - environ 1 minute] Bienvenue dans la série des présentations techniques Purple. Je suis votre hôte et aujourd'hui nous allons aborder les spécificités du déploiement d'un Captive Portal externe sur l'infrastructure Ubiquiti UniFi - l'une des plateformes réseau les plus déployées à l'échelle mondiale dans les secteurs de l'hôtellerie, de la vente au détail et des entreprises. Si vous êtes responsable informatique, architecte réseau ou intégrateur système travaillant avec les UniFi Cloud Gateways, les Dream Machines ou l'application UniFi Network, cet épisode s'adresse à vous. Nous allons examiner en détail le fonctionnement du mécanisme de portail externe sous le capot, comment le configurer correctement, quels sont les pièges courants à éviter, et pourquoi l'intégration de Purple au-dessus d'un déploiement UniFi est la décision d'architecture idéale pour les sites qui exigent plus qu'une simple page de connexion basique. C'est parti. [ANALYSE TECHNIQUE APPROFONDIE - environ 5 minutes] Tout d'abord, comprenons ce qui se passe réellement lorsqu'un appareil invité se connecte à un SSID UniFi sur lequel un Captive Portal est activé. Lorsqu'un appareil invité s'associe à votre SSID invité, l'Access Point UniFi lui attribue une adresse IP via DHCP comme d'habitude. Mais l'appareil est immédiatement placé dans un état que UniFi qualifie de "en attente". Dans cet état, le processus DNSmasq intégré à l'AP intercepte chaque requête DNS formulée par l'appareil, quel que soit le serveur DNS que l'appareil pense utiliser. L'AP redirige tout le trafic DNS vers lui-même. Simultanément, l'AP exécute un redirecteur HTTP léger sur le port 80. Dès que le navigateur de l'invité effectue une requête HTTP - et c'est le mot clé, HTTP, pas HTTPS - le redirecteur renvoie une redirection 302, envoyant le navigateur vers la page d'accueil du Captive Portal. C'est ce mécanisme qui déclenche la notification "Se connecter au WiFi" sur les appareils iOS et Android. C'est ici que la distinction entre portail intégré et portail externe devient essentielle. Avec le portail Hotspot UniFi intégré, la page de connexion est servie directement par l'application UniFi Network. C'est fonctionnel, rapide à configurer, mais extrêmement limité. Vous disposez d'une authentification de base par mot de passe, de coupons et de paiements Stripe. Il n'y a pas de collecte d'e-mails, pas de connexion via les réseaux sociaux, pas de gestion du consentement GDPR, pas d'intégration CRM, et aucune analyse de données significative au-delà du décompte des sessions. Lorsque vous configurez un serveur de portail externe - qui est le paramètre sur lequel nous nous concentrons aujourd'hui - vous indiquez au contrôleur UniFi de rediriger les invités vers une application web totalement distincte. Dans notre cas, il s'agit de Purple. L'URL que vous saisissez dans le champ du serveur de portail externe devient la destination de toutes ces redirections 302.Voici le détail technique important concernant cette URL de redirection. Lorsque UniFi redirige un invité vers votre portail externe, il ajoute plusieurs paramètres de requête à l'URL. Ceux-ci incluent : l'adresse MAC de l'AP, l'adresse MAC de l'appareil client, un horodatage Unix, l'URL d'origine que le client tentait d'atteindre, et le nom du SSID. Votre portail externe - Purple dans ce contexte - capture ces paramètres, les utilise pour identifier l'appareil qui se connecte, présente la splash page appropriée, gère l'authentification, puis effectue un appel API vers l'application UniFi Network pour autoriser cette adresse MAC. Cet appel API constitue la liaison cruciale. Depuis la version 9.1 et les suivantes de l'application UniFi Network, il existe une API REST officielle avec une authentification appropriée basée sur des clés. Le point de terminaison d'autorisation est une requête POST vers la version un de l'API des sites, ciblant l'ID client spécifique, avec un corps JSON qui peut spécifier des limites de temps en minutes, des limites d'utilisation de données en mégaoctets et des limites de débit en kilobits par seconde. Une fois que le contrôleur reçoit cette autorisation, il transmet l'instruction à l'AP, et l'invité passe du statut en attente à autorisé. L'accès Internet est alors accordé. Parlons maintenant du Walled Garden, que UniFi appelle Pre-Authorization Access. Il s'agit de la liste blanche des domaines et des adresses IP que les invités peuvent atteindre avant de s'être authentifiés. Elle est essentielle, et c'est l'une des sources de mauvaise configuration les plus courantes. Au minimum, votre walled garden doit inclure le nom de domaine complet de votre portail Purple, ainsi que les adresses IP ou les plages CIDR vers lesquelles l'infrastructure de Purple se résout. Si vous utilisez la connexion via les réseaux sociaux - Facebook, Google, Microsoft - vous devez également ajouter les domaines de point de terminaison OAuth de ces fournisseurs. Les points de terminaison de connexion de Google couvrent plusieurs plages IP et plusieurs domaines, notamment accounts.google.com et oauth2.googleapis.com. L'infrastructure de connexion de Facebook nécessite également plusieurs entrées. La documentation de Purple fournit une liste mise à jour des entrées exactes requises, et cette liste est maintenue à jour au fur et à mesure que ces fournisseurs actualisent leur infrastructure. Il existe une particularité critique propre à UniFi qui piège de nombreux déploiements. Le redirecteur HTTP de l'AP intercepte uniquement le trafic HTTP simple sur le port 80. Les appareils modernes - iOS, Android, Windows, macOS - effectuent tous une détection de Captive Portal basée sur le protocole HTTPS. Les appareils Apple interrogent captive.apple.com en HTTPS. Les appareils Android interrogent connectivitycheck.gstatic.com. Si ces requêtes HTTPS ne reçoivent pas de réponse spécifique, l'appareil peut considérer qu'il n'y a pas de Captive Portal et tout simplement ne pas afficher l'invite de connexion. La solution consiste à s'assurer que votre walled garden inclut les domaines de détection de Captive Portal pour les principaux systèmes d'exploitation, et que votre portail Purple est accessible en HTTPS avec un certificat SSL valide et approuvé. Les certificats auto-signés provoqueront des avertissements de sécurité sur les navigateurs qui empêcheront le chargement du portail. C'est un point non négociable pour les déploiements en production. L'autre considération spécifique à UniFi concerne l'accessibilité du contrôleur. L'UniFi Network Application - qu'elle s'exécute sur une Cloud Gateway, une Cloud Key ou un serveur auto-hébergé - doit être accessible depuis l'infrastructure de Purple pour que les appels d'autorisation API réussissent. Si votre contrôleur se trouve sur un réseau privé derrière un NAT, vous devrez vous assurer que les ports API concernés sont accessibles. Pour les contrôleurs auto-hébergés, il s'agit généralement du port 8443 pour l'API héritée, ou du port HTTPS standard 443 pour la nouvelle API introduite dans la version 9.1. La documentation d'assistance de Purple spécifie les plages d'adresses IP exactes qui nécessitent un accès entrant à votre contrôleur. Pour l'authentification basée sur RADIUS - qui est pertinente lorsque vous déployez Purple aux côtés de SSIDs WPA2-Enterprise ou WPA3-Enterprise plutôt que du modèle de SSID invité ouvert - le serveur RADIUS intégré d'UniFi prend en charge les méthodes EAP 802.1X standard. Vous configurez le profil RADIUS sous Paramètres, Réseaux, Serveurs RADIUS, puis vous référencez ce profil dans la configuration de votre SSID. UniFi prend également en charge le RADIUS sur TLS, connu sous le nom de RADSEC, à partir de la version 8.4, qui chiffre le trafic RADIUS entre l'AP et le serveur d'authentification. Pour les déploiements multi-sites où le trafic RADIUS traverse l'internet public, RADSEC est fortement recommandé. [RECOMMANDATIONS DE MISE EN ŒUVRE ET PIÈGES À ÉVITER - environ 2 minutes] Permettez-moi de vous présenter la liste de contrôle pratique pour la mise en œuvre, que je passerais en revue avec tout client déployant Purple sur UniFi. Premièrement, la segmentation du réseau. Votre SSID invité doit se trouver sur un VLAN dédié, isolé de vos réseaux d'entreprise et IoT. UniFi rend cela très simple - créez un réseau dédié dans Paramètres, Réseaux, attribuez-lui un ID de VLAN et associez votre SSID invité à ce réseau. Activez l'isolation des clients sur le réseau invité pour empêcher le trafic d'invité à invité. Deuxièmement, le contrôleur doit disposer d'un FQDN valide et d'un certificat SSL de confiance. Ne vous fiez pas à l'adresse IP. Utilisez un nom de domaine approprié, obtenez un certificat Let's Encrypt ou un certificat commercial, et configurez UniFi pour utiliser ce certificat. Cela résout la majorité des problèmes de redirection HTTPS. Troisièmement, construisez soigneusement votre walled garden et testez-le. Les entrées minimales sont : le domaine de votre Captive Portal Purple et ses plages d'adresses IP, les domaines de détection de Captive Portal pour iOS, Android et Windows, ainsi que tous les domaines de fournisseurs OAuth que vous utilisez. Testez avec un appareil qui ne s'est jamais connecté au réseau auparavant - le cache DNS et l'état du réseau peuvent masquer des lacunes du walled garden lors des tests. Quatrièmement, pour l'intégration de l'API, utilisez un compte administrateur local dédié dans l'UniFi Network Application avec les autorisations minimales requises. N'utilisez pas vos identifiants d'administrateur principaux. Si vous utilisez Network Application 9.1 ou une version ultérieure, utilisez le nouveau mécanisme de clé API sous Control Plane, Integrations - il est plus sécurisé et ne nécessite pas d'authentification basée sur des identifiants. Cinquièmement, examinez attentivement la durée des sessions. L'expiration par défaut de la session invité d'UniFi peut être de seulement huit heures. Pour les déploiements dans le secteur de l'hôtellerie où les clients peuvent séjourner plusieurs nuits, configurez des durées de session appropriées dans les paramètres du portail Purple, et assurez-vous que ces durées sont correctement transmises dans l'appel d'autorisation de l'API. Le piège le plus courant que je constate est le déploiement sur un contrôleur auto-hébergé qui n'est pas accessible publiquement. Si Purple ne peut pas joindre votre contrôleur pour autoriser les invités, le portail se chargera mais l'authentification échouera silencieusement. Vérifiez toujours la connectivité de l'API depuis l'infrastructure de Purple avant la mise en service. [QUESTIONS - RÉPONSES RAPIDES - environ 1 minute] Cela fonctionne-t-il sur UniFi Dream Machine Pro ? Oui. Toutes les consoles UniFi OS - UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max - prennent en charge la configuration de l'External Portal Server. L'application réseau s'exécute sur l'appareil. Puis-je utiliser Purple sur plusieurs sites UniFi à partir d'un seul compte Purple ? Oui. L'architecture multi-site de Purple est conçue exactement pour cela. Chaque site est configuré comme un site distinct dans Purple, mappé au site UniFi correspondant. Dois-je ouvrir des ports de pare-feu sur la passerelle UniFi ? Vous devez vous assurer que le trafic du VLAN invité peut atteindre le domaine du portail Purple sur le port 443. Le port de l'API du contrôleur doit également être accessible depuis les serveurs de Purple. La documentation de Purple fournit les plages d'adresses IP spécifiques. Qu'en est-il du WPA3 ? UniFi prend en charge WPA3 Personal et WPA3 Enterprise. Le mécanisme de Captive Portal fonctionne avec WPA3 Personal sur les réseaux invités. WPA3 Enterprise utilise le protocole 802.1X et RADIUS, ce qui correspond à un flux d'authentification différent. [RÉSUMÉ & PROCHAINES ÉTAPES - environ 1 minute] En résumé : le déploiement de Purple en tant que Captive Portal externe sur UniFi est une intégration bien prise en charge et robuste sur le plan de l'architecture. Les étapes clés sont : configurez votre SSID invité avec l'option External Portal Server pointant vers l'URL de votre portail Purple, créez un walled garden complet qui couvre l'infrastructure de Purple et tous les fournisseurs OAuth que vous utilisez, assurez-vous que votre contrôleur UniFi possède un certificat SSL valide et est accessible depuis les serveurs API de Purple, et configurez des durées de session adaptées à votre type d'établissement. L'intérêt commercial est évident. Le portail UniFi intégré vous offre une simple page d'accueil. Purple vous offre une plateforme d'expérience client axée sur l'analyse et conforme aux réglementations qui s'intègre à votre CRM, capture des données de première partie sous consentement GDPR, et fournit les analyses de fréquentation et de temps de séjour dont les exploitants de sites et les équipes marketing ont réellement besoin. Si vous êtes un MSP ou un intégrateur système qui déploie UniFi à grande échelle, la gestion multi-site et les capacités de marque blanche de Purple en font la solution idéale pour vos clients. Pour obtenir une documentation de configuration détaillée, des listes d'adresses IP pour le walled garden et des guides d'intégration API, visitez purple.ai. Merci pour votre attention.