Voir la transcription du podcast
Captive Portal pour Ubiquiti UniFi - Une présentation technique de Purple
[INTRODUCTION & CONTEXTE - environ 1 minute]
Bienvenue dans la série de présentations techniques de Purple. Je suis votre hôte, et nous allons aujourd'hui nous intéresser de près au déploiement d'un Captive Portal externe sur l'infrastructure Ubiquiti UniFi - l'une des plateformes réseau les plus déployées au monde dans les secteurs de l'hôtellerie, du commerce de détail et de l'entreprise.
Si vous êtes responsable informatique, architecte réseau ou intégrateur de systèmes travaillant avec les UniFi Cloud Gateways, les Dream Machines ou l'UniFi Network Application, cet épisode est pour vous. Nous allons détailler précisément comment le mécanisme de portail externe fonctionne sous le capot, comment le configurer correctement, quels sont les pièges courants à éviter et pourquoi l'intégration de Purple à un déploiement UniFi s'impose comme la bonne décision d'architecture pour les établissements qui ont besoin de plus qu'une simple page d'accueil de base.
C'est parti.
[ZOOM TECHNIQUE - 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é, le point d'accès UniFi lui attribue normalement une adresse IP via DHCP. Mais l'appareil est immédiatement placé dans ce que UniFi appelle un état "en attente". Dans cet état, le processus DNSmasq intégré du point d'accès intercepte chaque requête DNS formulée par l'appareil, quel que soit le serveur DNS que ce dernier pense utiliser. Le point d'accès redirige tout le trafic DNS vers lui-même.
Simultanément, le point d'accès exécute un redirecteur HTTP léger sur le port 80. Dès que le navigateur de l'invité formule 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 à ce stade que la distinction entre le portail intégré et le portail externe devient essentielle. Avec l'UniFi Hotspot Portal intégré, la page d'accueil est hébergée directement par l'UniFi Network Application. C'est fonctionnel, rapide à configurer, mais très 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'adresses e-mail, pas de connexion via les réseaux sociaux, pas de gestion du consentement GDPR, pas d'intégration CRM et pas d'analyses approfondies au-delà du nombre de sessions.
Lorsque vous configurez un serveur de portail externe (le paramètre qui nous intéresse aujourd'hui), vous indiquez au contrôleur UniFi de rediriger les invités vers une application web complètement 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 visiteur 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 réseau UniFi pour autoriser cette adresse MAC.
Cet appel API est l'étape d'authentification cruciale. À partir de la version 9.1 et ultérieures de l'application réseau UniFi, il existe une API REST officielle avec une authentification par clé appropriée. Le point de terminaison d'autorisation est une requête POST vers la version un de l'API des sites, ciblant l'identifiant client spécifique, avec un corps JSON qui peut spécifier des limites de temps en minutes, des limites d'utilisation des 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 le visiteur passe du statut en attente à autorisé. L'accès à Internet est accordé.
Parlons maintenant du Walled Garden, qu'UniFi appelle l'accès de pré-autorisation. Il s'agit de la liste blanche de domaines et d'adresses IP que les visiteurs peuvent atteindre avant de s'être authentifiés. C'est essentiel, 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 pointe. 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 à mesure que ces fournisseurs mettent à jour leur infrastructure.
Il existe une particularité critique propre à UniFi qui piège de nombreux déploiements. Le redirecteur HTTP sur l'AP n'intercepte que le trafic HTTP en texte brut 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 contactent captive.apple.com via HTTPS. Les appareils Android contactent 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é du navigateur qui empêcheront le chargement du portail. C'est une condition non négociable pour les déploiements en production.
L'autre considération spécifique à UniFi est 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 correspondants sont accessibles. Pour les contrôleurs auto-hébergés, il s'agit généralement du port 8443 pour l'ancienne API, ou du port HTTPS standard 443 pour la nouvelle API introduite dans la version 9.1. La documentation de support de Purple précise 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é de UniFi prend en charge les méthodes standard 802.1X EAP. 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]
Laissez-moi 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 être sur un VLAN dédié, isolé de vos réseaux d'entreprise et IoT. UniFi rend cela 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 commercial, et configurez UniFi pour utiliser ce certificat. Cela résout la majorité des problèmes de redirection HTTPS.
Troisièmement, construisez votre walled garden avec soin et testez-le. Les entrées minimales sont : votre domaine de portail 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 dans le walled garden lors des tests.
Quatrièmement, pour l'intégration API, utilisez un compte d'administrateur local dédié dans l'UniFi Network Application avec les autorisations minimales requises. N'utilisez pas vos identifiants d'administrateur principal. Si vous utilisez Network Application 9.1 ou une version ultérieure, utilisez le nouveau mécanisme de clé API sous Control Plane, Intégrations - il est plus sécurisé et ne nécessite pas d'authentification basée sur des identifiants.
Cinquièmement, tenez compte de la durée de la session. L'expiration par défaut de la session invité sur UniFi peut être de seulement huit heures. Pour les déploiements dans le secteur de l'hôtellerie où les clients séjournent plusieurs nuits, configurez des durées de session appropriées dans les paramètres du Purple portal, et assurez-vous que ces durées sont correctement transmises lors de l'appel d'autorisation 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é API depuis l'infrastructure de Purple avant la mise en service.
[Q&R RAPIDE - 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 du serveur de portail externe (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-sites de Purple est conçue exactement pour cela. Chaque site physique 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 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 de 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 802.1X et RADIUS, ce qui correspond à un flux d'authentification différent.
[RÉSUMÉ ET PROCHAINES ÉTAPES - environ 1 minute]
Pour résumer : le déploiement de Purple en tant que Captive Portal externe sur UniFi est une intégration bien prise en charge et à l'architecture solide. Les étapes clés sont les suivantes : 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 dispose d'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'analyse de rentabilité est simple. Le portail UniFi intégré vous offre une page de connexion. Purple vous offre une plateforme d'expérience client conforme aux réglementations et axée sur l'analyse, qui s'intègre à votre CRM, capture des données de première partie avec le 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 de systèmes déployant UniFi à grande échelle, la gestion multi-sites 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, les listes d'adresses IP de walled garden et les guides d'intégration API, visitez purple.ai. Merci pour votre écoute.
